applies to Nexus 1.8 and above

Terminology

YUI Component - A uniquely name area of functionality available as part of the YUI library. 

A plugin can add a javascript or CSS module using the iwPage::addCssModule or iwPage::addJavascriptModule methods of the page object.  The page object is usually made available as a parameter to the plugin callback.  When adding a module, you are simply setting up the module to be loaded (not actually loading it).  Adding a module involves telling the engine what the unique name of the module is, what dependencies on other modules it has and the path to the module file. 

Adding CSS module:
$page->addCssModule('path/to/css.css','my_css',array('my_other_css'));

Adding Javascript module:
$page->addJavascriptModule(path/to/js.js','my_js',array('my_other_js'));

You do not have to add YUI components because the YUI itself has already prepared all of its own components and knows the dependencies each one requires.

Loading Theme Modules

When your action requires that a certain javascript file or CSS file be loaded, you should then load the module.  Only modules that have already been added (see above) can be loaded, though.  To load a module, simply call the iwPage::loadModule method using the unique name given to the module when adding it.  If loading a YUI component just use the name that the YUI documentation specifies (e.g. "treeview"). 

Loading a theme module:
$page->loadModule('my_js');

For a complete list of modules, visit the Modules page

Delay Load of Modules

Modules are loaded after the page is loaded.  Any scripts that once were inline or even run after a "window load" event was received will probably no longer work correctly.  This is because scripts which are dependent on any YUI component or Nexus module have not been loaded yet.  To get around this, use a Nexus Javascript Object instead (see below).

Nexus Javascript Objects

This delayed load of javascript and CSS modules has a sideffect that will break inline scripts which depend on one of the aforementioned modules.  For example, if the theme renders a template file that uses one of the YUI Dom methods like "YAHOO.util.Dom.get", this will fail because although the page may have loaded already, modules (which include the base YUI scripts) have not yet loaded. 

To get around this effect, create a Javascript object that implements the "onScriptsLoaded" method.  This object is called a Nexus Javascript Object (or NJO).  The php code on the backend will add the NJO object insantiation to the list of those to be called after the scripts have loaded.

For example, the main template file implements an NJO called "mainTemplate".

In an HTML file:

var MainTemplate = new function() {
   
    this.onScriptsLoaded = function() {
       
        if ($('briefcase') != undefined)
        {
            // Initialize the sidebar drop targets
            new YAHOO.util.DDTarget("briefcase");
        }
       
        if ($('trashcan') != undefined)
        {
            new YAHOO.util.DDTarget("trashcan");
        }
    }
}

In PHP code:

$page->addNexusJsObject('MainTemplate');