YUI recommends YUI3.

YUI 2 has been deprecated since 2011. This site acts as an archive for files and documentation.

This documentation is no longer maintained.

YUI 2: Module

YUI 2: Module

The Module control enables you to create a JavaScript object representation of a basic module of content. It can be used to manipulate existing content modules on your page or to create modules dynamically and append them to the DOM. All other components in the Container family have Module as their lowest-level base class.

Note: Module is fundamentally a building block for other UI controls; this document is of most use to those interested in the inner workings of controls built on Module.

Getting Started

To use Module, include the following code in your page:

  1. <!-- Dependencies -->
  2. <script src="http://yui.yahooapis.com/2.9.0/build/yahoo-dom-event/yahoo-dom-event.js"></script>
  3.  
  4. <!-- Source file -->
  5. <script src="http://yui.yahooapis.com/2.9.0/build/container/container-min.js"></script>
  6.  
<!-- Dependencies -->
<script src="http://yui.yahooapis.com/2.9.0/build/yahoo-dom-event/yahoo-dom-event.js"></script>
 
<!-- Source file -->
<script src="http://yui.yahooapis.com/2.9.0/build/container/container-min.js"></script>
 

If you are not using Tooltip, Panel, Dialog, or SimpleDialog, you may substitute container-min.js with the smaller container_core-min.js file:

  1. <!-- If not using Tooltip, Panel, Dialog, or SimpleDialog: -->
  2. <script src="http://yui.yahooapis.com/2.9.0/build/container/container_core-min.js"></script>
  3.  
<!-- If not using Tooltip, Panel, Dialog, or SimpleDialog: -->
<script src="http://yui.yahooapis.com/2.9.0/build/container/container_core-min.js"></script>
 
Next, apply the yui-skin-sam class name to an element that is a parent of the element in which the Module Control lives. You can usually accomplish this simply by putting the class on the <body> tag:

  1. <body class="yui-skin-sam">
  2.  
<body class="yui-skin-sam">
 

For more information on skinning YUI components and making use of default skins, see our Understanding YUI Skins article here on the website.

YUI dependency configurator.

YUI Dependency Configurator:

Instead of copying and pasting the filepaths above, try letting the YUI dependency Configurator determine the optimal file list for your desired components; the Configurator uses YUI Loader to write out the full HTML for including the precise files you need for your implementation.

Note: If you wish to include this component via the YUI Loader, its module name is container. (Click here for the full list of module names for YUI Loader.)

Where these files come from: The files included using the text above will be served from Yahoo! servers. JavaScript files are minified, meaning that comments and white space have been removed to make them more efficient to download. To use the full, commented versions or the -debug versions of YUI JavaScript files, please download the library distribution and host the files on your own server.

Order matters: As is the case generally with JavaScript and CSS, order matters; these files should be included in the order specified above. If you include files in the wrong order, errors may result.

Using Module

This section describes common tasks for creating and using Module. It contains these sections:

Defining Module Markup

In its most basic form, the HTML markup for a Module might look like this:

  1. <div id="myModule">
  2.   <div class="hd"></div> 
  3.   <div class="bd"></div> 
  4.   <div class="ft"></div> 
  5. </div>
  6.  
<div id="myModule">
  <div class="hd"></div>
  <div class="bd"></div>
  <div class="ft"></div>
</div>
 

Initializing the Module

To instantiate a Module around a pre-existing piece of markup, use this code: 

  1. var myModule = new YAHOO.widget.Module("myModule");
  2.  
var myModule = new YAHOO.widget.Module("myModule");
 

If the Module doesn't exist on the page, a new one will be created. Then, content (as an HTML string or as a DOM element) can be set into each section using the setHeader, setBody, and setFooter methods:

  1. myModule.setHeader("This is my header content");
  2. myModule.setBody("This is my body content");
  3. myModule.setFooter("This is my footer content");
  4.  
myModule.setHeader("This is my header content");
myModule.setBody("This is my body content");
myModule.setFooter("This is my footer content");
 

The setHeader, setBody, and setFooter methods can take either a DOM element or an HTML string as the argument. Whatever argument you pass in to these methods will entirely replace the current contents of the section you are addressing — that is, setBody will set the body section's innerHTML to "" (empty string) prior to inserting your argument as the body content.

Using Configuration Properties

Configuration properties control the look and behavior of Module instances (and its subclasses). These properties are managed by a configuration object (defined by YAHOO.util.Config) that is automatically instantiated by Module's constructor. The configuration object is accessible at runtime via its host object instance's "cfg" property. The following diagram illustrates the relationship of the configuration object and its properties with its host Container family object instance:

Illustration of the relation of the Configuration object to its host Module instance.

There are two different ways to set the initial value of configuration properties: The first is via an object literal that is passed as a second argument to the Module's constructor. Configuration properties can also be set via the configuration object's queueProperty method. In either case, these properties are not applied to the Container family object instance until it is rendered. For example: 

  1. YAHOO.util.Event.onDOMReady(function () {
  2.  
  3.     // Set the initial value of the "visible" property to "false"
  4.  
  5.     var oModule = new YAHOO.widget.Module("mymodule", { visible: false });
  6.  
  7.     // Set the initial value of the "visible" property to "true"
  8.  
  9.     oModule.cfg.queueProperty("visible", true);
  10.  
  11.     oModule.setBody("This is the body");
  12.  
  13.     // Render the Module instance, triggering the application of the "visible" 
  14.     // configuration property
  15.  
  16.     oModule.render(document.body);
  17.  
  18. });
  19.  
YAHOO.util.Event.onDOMReady(function () {
 
    // Set the initial value of the "visible" property to "false"
 
    var oModule = new YAHOO.widget.Module("mymodule", { visible: false });
 
    // Set the initial value of the "visible" property to "true"
 
    oModule.cfg.queueProperty("visible", true);
 
    oModule.setBody("This is the body");
 
    // Render the Module instance, triggering the application of the "visible" 
    // configuration property
 
    oModule.render(document.body);
 
});
 

Once rendered, a Container object instance's configuration properties are accessible at runtime through the configuration object's getProperty and setProperty methods. It is possible to listen for when the value of a specific configuration property changes by using the configuration object's subscribeToConfigEvent method. Additionally, the configuration fires a "configChanged" event that can be used to listen for changes made to the value of any configuration property. For example: 

  1. YAHOO.util.Event.onDOMReady(function () {
  2.  
  3.     // Set the initial value of the "visible" property to "false"
  4.  
  5.     var oModule = new YAHOO.widget.Module("mymodule", { visible: false });
  6.  
  7.  
  8.     oModule.setBody("This is the body");
  9.  
  10.  
  11.     // Render the Module instance, triggering the application of the "visible" 
  12.     // configuration property
  13.  
  14.     oModule.render(document.body);
  15.  
  16.  
  17.     // Add an event listener for changes to the "visible" configuration property
  18.  
  19.     oModule.cfg.subscribeToConfigEvent("visible", function (p_sType, p_aArgs) {
  20.  
  21.         var oValue = p_aArgs[0];
  22.  
  23.         alert("The value of the visible property was changed to: " + oValue);
  24.  
  25.     });
  26.  
  27.  
  28.     // Add an event listener for all changes to configuration properties
  29.  
  30.     oModule.cfg.subscribe("configChanged", function (p_sType, p_aArgs) {
  31.  
  32.         var aProperty = p_aArgs[0],
  33.             sPropertyName = aProperty[0],
  34.             oPropertyValue = aProperty[1];
  35.  
  36.         alert("The value of the " + sPropertyName + " property was changed to: " + oPropertyValue);
  37.  
  38.     });
  39.  
  40.  
  41.     // Set the "visible" configuration property to "true"
  42.  
  43.     oModule.cfg.setProperty("visible", true);
  44.  
  45. });
  46.  
YAHOO.util.Event.onDOMReady(function () {
 
    // Set the initial value of the "visible" property to "false"
 
    var oModule = new YAHOO.widget.Module("mymodule", { visible: false });
 
 
    oModule.setBody("This is the body");
 
 
    // Render the Module instance, triggering the application of the "visible" 
    // configuration property
 
    oModule.render(document.body);
 
 
    // Add an event listener for changes to the "visible" configuration property
 
    oModule.cfg.subscribeToConfigEvent("visible", function (p_sType, p_aArgs) {
 
        var oValue = p_aArgs[0];
 
        alert("The value of the visible property was changed to: " + oValue);
 
    });
 
 
    // Add an event listener for all changes to configuration properties
 
    oModule.cfg.subscribe("configChanged", function (p_sType, p_aArgs) {
 
        var aProperty = p_aArgs[0],
            sPropertyName = aProperty[0],
            oPropertyValue = aProperty[1];
 
        alert("The value of the " + sPropertyName + " property was changed to: " + oPropertyValue);
 
    });
 
 
    // Set the "visible" configuration property to "true"
 
    oModule.cfg.setProperty("visible", true);
 
});
 

See the Configuration object's API documentation for its full list of properties and methods.

Module has the following configuration properties, which it passes on to all of its subclasses through inheritance:

Name Type Default Description
visible Boolean true Sets whether or not the Module is visible on the page (Module uses the CSS "display" property to control this).
monitorresize Boolean true Configures whether or not to create a hidden off-screen element that can be used to monitor for text size changes in the DOM.
effect Object null Object or array of objects representing the ContainerEffect classes that are active for animating the container. NOTE: The effect configuration property is introduced at the Module class, however Container does not ship with a ContainerEffect implementation for the Module class so setting the effect property on a Module instance has no impact. Overlay is the lowest Container class for which ContainerEffects are implemented out of the box.
appendtodocumentbody Boolean false

Specifies if the module should be rendered as the first child of document.body or appended as the last child when render is called with document.body as the "appendToNode".

Appending to the body while the DOM is still being constructed can lead to Operation Aborted errors in IE hence this flag is set to false by default.

Monitoring Events

Module and its subclasses each introduce hooks for Custom Events to which a listener can subscribe. By listening for the execution of these events, you have the ability to react to the various interesting moments that occur during the lifecycle of a Module. See the full API documentation for more information on the events that are available to listening subscribers.

Rendering the Module

Once a Module is successfully instantiated, a call to its render function is required so that all visual properties are properly applied to the Module. If the Module is already in the DOM, you can simply call: 

  1. // Render the Module that is already in the DOM
  2. myModule.render();
  3.  
// Render the Module that is already in the DOM
myModule.render();
 

If you have created a module scriptologically with no pre-existing markup, you must pass an element to the render function so that the Module can be inserted into the DOM:

  1. // Render the Module into the body of the document.
  2. myModule.render(document.body);
  3.  
// Render the Module into the body of the document.
myModule.render(document.body);
 

Showing and Hiding the Module

Showing and hiding a rendered Module instance (as well as rendered instances of all Module subclasses) is very easy. You can change the visibility of the Module two ways:

  1. // 1. Using show() and hide()
  2. myModule.show();
  3. myModule.hide();
  4. // 2. Using the configuration properties
  5. myModule.cfg.setProperty("visible", true);
  6. myModule.cfg.setProperty("visible", false);
  7.  
// 1. Using show() and hide()
myModule.show();
myModule.hide();
// 2. Using the configuration properties
myModule.cfg.setProperty("visible", true);
myModule.cfg.setProperty("visible", false);
 

Support & Community

The YUI Library and related topics are discussed on the on the YUILibrary.com forums.

Also be sure to check out YUIBlog for updates and articles about the YUI Library written by the library's developers.

Filing Bugs & Feature Requests

The YUI Library's public bug tracking and feature request repositories are located on the YUILibrary.com site. Before filing new feature requests or bug reports, please review our reporting guidelines.

Container Family Examples:

Other YUI Examples That Make Use of the Container Family:

More Reading about the YUI Module Control:

YUI Module on del.icio.us:

Copyright © 2013 Yahoo! Inc. All rights reserved.

Privacy Policy - Copyright Policy - Job Openings