Getting Started

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

<!-- Dependencies --> <script type="text/javascript" src="http://yui.yahooapis.com/2.5.2/build/yahoo-dom-event/yahoo-dom-event.js"></script> <!-- Source file --> <script type="text/javascript" src="http://yui.yahooapis.com/2.5.2/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:

<!-- If not using Tooltip, Panel, Dialog, or SimpleDialog: --> <script type="text/javascript" src="http://yui.yahooapis.com/2.5.2/build/container/container_core-min.js"></script>

Using Module

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

• Defining Module Markup
• Initializing the Module
• Using Configuration Properties
• Monitoring Events
• Rendering the Module
• Showing and Hiding the Module

Defining Module Markup

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

<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:

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:

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:

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:

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:

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:

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:

// 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:

// 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. 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 ydn-javascript mailing list.

In addition, please visit the 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 YUI SourceForge project site. Before filing new feature requests or bug reports, please review our reporting guidelines.

• Guidelines for YUI feature requests and bug reports.
• Review current bug list or file a new bug.
• Review current feature requests or file a new feature request.