resources

Xarigami now has a mechanism for handling 3rd party javascript libraries. We have chosen JQuery for addition of Javascript to the core and key modules and will use this to illustrate how our javascript framework can be used. However, the same framework should and can handle any of the other popular 3rd party javascript libraries without additional integration requirements at the API level in Xarigami.

The aim of the Javascript framework in Xarigami is to:

• provide a lightweight, consistent and efficient mechanism for integration of Javascript into Xarigami core, modules and themes based on the existing APIs and tags in Xaraya/xarigami, and override principles
• support unobtrusive javascript, the ability to add dynamic behaviours to modules and theme markup without inserting javascript throughout  the markup
• provide graceful degradation when javascript isn't available  ensuring pages still work with the required functionality without javascript and with no left over traces of javascript
• allow for progressive enhancement of pages with javascript and ajax
• provide improved cross browser compatibility
• make xarigami easier and more fun to use!

The Basics

If you have not already read the basic introduction to using Javascript and Xarigami/Xaraya then please take a look now at Adding Javascript to Xaraya (or you can read on and take your luck!)

You require the use of two tags to add javascript to Xarigami:

• One tag placed in your page templates that renders module or other javascript from templates in the head of your page, and does the same for body javascript.
  

  <xar:base-render-javascript position="head" //>  //placed in the head of your page template
  
  <xar:base-render-javascript position="body" //>  //placed at the bottom of your page template
  

• One tag that is used to load in specific javascript in Xarigami/Xaraya's global javascript array, waiting to be rendered when required via the base-render-javascript tags
  

  <xar:base-include-javascript module="articles" position="head|body" filename="filename.js"/> 

The javascript framework for loading JQuery uses exactly the same tags so there are no new tags to get to know. There are a few new parameters to learn about. The key features of the Javascript framework for 3rd party libraries is:

• It makes use of exising APIs and tags so there is little extra overhead with new files or new tags to learn about
• It works as is with JQuery and should do with other 3rd party libraries
• All 3rd party libraries drop into the 'scripts' directory virtually as is so it is easy to maintain and upgrade
• Any of the 3rd party javascripts, images or css files can be overridden in your theme or module as usual

How to use the javascript tag to load JQuery

For jquery there is the core jquery file (minified or other), plus plugins with minified or other source files including css and images.

• To load just the base jQuery core library with a file name different from the library name. The .js extension is assumed on the file name but can be added for clarity if required.
  

  <xar:base-include-javascript libname="jquery" libfile="jquery.min" />

• To load jquery core plus a plugin and some support files use the following which will load them all. If jQuery core is already loaded, or the plugin, the framework ensures they are not loaded again.
  

  <xar:base-include-javascript libname="jquery" libfile="jquery.min" plugin="ui" pluginfile="ui.core.min,ui.dialog.min" style="ui.css" />
  

Some key points to note:

1. This tag and specific parameters loads 3rd party javascript library files from the 'scripts' directory (and subdirectories)  in your Xarigami site. If you want to load specific custom jQuery code for your theme or module then use the same tag using the normal parameters as given above under 'The Basics' (see specific example below).
2. The javascripts are all loaded into the global javascript array (queue) ready for use when required. You must specify the library name (libname) and libfile(library file) as a minimum in the tag.
3. Each javascript file of a given name will only be loaded once into the queue.
4. You can load the core JQuery and a plugin with one or more support files in one tag.
5. If you need another plugin, use the same tag again specifying the libname as well as the plugin and specific plugin file(s)

Where do the files load from and can I override?

The 3rd party libraries all reside in the 'scripts' directory in your site. Xarigami is shipped with the JQuery core, plus a few common plugins, most notably the JQuery UI Plugin. You'll find the structure for JQuery and one plugin (UI) as follows:

scripts  /
            /jquery 
                     -  jquery.js
                     -  jquery.min.js
                     / plugins 
                                   /ui
                                      - ui core.min.js
                                      - ui.all.min.js
                                      - ui.css
                                       /images

The plugin files, including css and images, are referenced in the tag relative to the specific plugin directory so it does not matter whether they are all in the same directory, or an images or css subdirectory, as long as you specify it  in the tag relative to eg the UI plugin directory. This means we can just drop in 3rd party library plugins as we do for the bundled library and plugins.

Load order of javascript files

Xarigami keeps track of your javascript files but you should call the tags and corresponding files in order of use/requirement. eg It makes sense to load the core JQuery and any plugins first and then any othe plugins or custom JQuery code that is dependent on the core or prior plugins.

Overriding javascript and css files

You can override any of these files in your theme in the corresponding theme directory. Eg It may be the js file, the images or for example to override the ui.css you could place it in either the corresponding scripts directory in your theme :

themes/[yourtheme]/scripts/jquery/plugins/ui/ui.css

Now, if we are a developer and want to override the plugin css for our own module, we can just specify the module="mymodule" in our tag to load the plugin and css and the css will be loaded from that module in the usual directory: eg

<xar:base-include-javascript libname="jquery" libfile="jquery.min" plugin="ui" 
pluginfile="ui.core.min,ui.dialog.min" style="ui.css"  module="mymodule" />

and this will deliver the css from :

modules/[mymodule]/xarstyles/jquery/plugins/ui/ui.css

So, you don't like the way the module develper themed their module plugin ui? You can override that specifically for the module in the usual way:

themes/[yourtheme]/modules/[mymodule]/xarstyles/jquery/plugins/ui/ui.css

Loading order for CSS files

The loading order and fall back using the ui plugin example is as would be expected with Xaraya:

1. Look for a specific module override for the plugin css in themes/[yourheme]/modules/[mymodule]/xarstyles/plugins/ui/ui.css and use it if it exists
2. Look for the original module developers plugin override in  modules/[mymodule]/xarstyles/jquery/plugins/ui/ui.css and use it if it exists
3. Look for a general override in the theme at themes/[yourtheme]/scripts/jquery/plugins/ui/ui.css and use it if it exists
4. If nothing else, use the originally supplied css

A working example from Xarigami core

Here we comment on a specific case in the Xarigami core as an example of use.

• We use the xaraya javascript tag to load our library and plugins into the global javascript queue
• We write some custom jQuery code for the page
• We load the custom jquery code using the xaraya javascript tag into the global javascript queue

Our example is the Blocks module, view instances page which  lists all blocks on your xarigami site. In this page, we have a pop up modal dialog box that appears when the user clicks on the Delete icon.

If you look in the admin-view_instances.xd template you will see the following at the top of the file:

<xar:comment>Include jquery code for delete confirm and the definition for deletemessage</xar:comment>
<xar:set name="deletemessage"><xar:mlstring>Delete this block?</xar:mlstring></xar:set>
<xar:template file="jq-deleteinstance" module="blocks" />

• The first thing you will notice is there is no javascript in the template at all. We have included our tags to load JQuery and the custom JQuery we want for this page in an external template file (that lives in the blocks/xartemplates/include directory in this instance (always in the respective xartemplates/includes directory). We do this by convention to keep the templates neat.
• The second point to note  is the 'deletemessage' is defined in the 'set' tag. This 'deletemessage' variable is defined and used in the custom JQuery code (you will see later). We define it here rather than in the include template as we  reuse the included template in other parts of the core for delete popup modal windows, where applicable. So we can define the message to suit, in each template we need it. So, we have 'reusable' custom JQuery code.
• The third point is that by convention, we name the include templates starting with 'jq-' to indicate it is a jQuery file. The rest of the name is related to its function or the page in which it is used.

If we now look in the included template at blocks/xartemplates/includes/jq-deleteinstance.xd we can see :

1. loading of the jQuery core and UI plugin
   

   <xar:base-include-javascript libname="jquery" libfile="jquery.min" plugin="ui" 
       pluginfile="ui.core.min,ui.dialog.min" style="ui.css" />

2. definition of our custom jQuery code in a xar:set tag with name 'blockscode'
3. loading of this custom jQuery javascript using a normal javascript tag
   

   <xar:base-include-javascript type="code" code="$blockscode" position="body"/>

If you look at the custom jquery code

<xar:set name="blockscode">"
jQuery(document).ready(function() {
    var dialog_width = 300;
    var dialog_height = 180;
    var delmessage = (typeof(\"$deletemessage\") != 'undefined' ) ? \"$deletemessage\" : \"'.xarML('Delete this instance?').'\"; 
    jQuery('table.xar-items a[id^=delete]').click(function() {
        var a = this;
        jQuery('#"."xardialogtarget').remove();

// more code
     
        });
        return false;
    });
});    
"</xar:set>

You can see we have written our custom JQuery code and put it in the xar:set tag. We can then refer to this 'blockscode' variable  in the tag we use to load the javascript into the global javascript queue.

Some specific points on the custom jquery code:

• we wrap the whole custom code in the jQuery(document.ready(function() { .......}); This ensures that our page has loaded and all necessary javascript before our custom script is run.
• We use the full jQuery notation instead of the shortcut $ in case other 3rd party library code is running, to prevent namespace clashes.
• You can embed xaraya tags, functions eg xarML('text'), variables eg $deletemessage,into you custom jQuery.

Other javascripts and  3rd party javascript libraries

Of course these same xarigami javascript tags and tag parameters can be used to load other libraries, not just JQuery. You may even have specific custom non-jquery javascripts that you want to run with the JQuery in the page. This is not a problem.

Sometimes the javascript can be tempermental, and if you do find the load order is not as you want it when mixing JQuery with other libraries and javascripts, you can order them manually yourself.

Weighting

Xarigami javascript tag also allows 'weighting'. Most scripts are loaded by default with a weighting of 10 but you can always add the 'weight' parameter to your own tags and specify a numeric weight to force it to load earier or later than another javascript. In practice this should be a rare case, but the option is there if required when mixing JQuery or other 3rd party libraries and custom javascripts.

Summary of key points for Javascript and Xarigami

• Adding JQuery requires you to load the jQuery library and any plugins if required (one or more base-include-javascript tags with relevant parameters), and then load your custom jQuery code if any using another base-include-javascript tag with standard parameters
• Use unobtrusive javascript - dont' sprinkle it through your page markup
• Use javascript that degrades gracefully - don't leave traces of javascript in the markup or rendered page when there is no javascript support and, ensure the page still functions as it should without the javascript
• When creating a module or page, make sure it works first without javascript, then add the additional behaviours with unobtrusive javascript - progressive enhancement with javascript.
• Keep your specific custom javascript code in files or included templates. This makes for neat pages and reusable snippets of javascript/jquery code
• Try and use the specified naming conventions for jquery included templates  files (commencing with jq- ),
• Use full rather than abbreviated references for jQuery (not $) and use standard indents for your code sprinkled liberally with comments

Core modules demonstration at http://demo.xarigami.com

This is a working draft document and still in progress.
Please direct questions or suggestions for improvement to the forums or add them via the suggestion link.