YUI Library Home

Site Search (YDN & YUIBlog):

# YUI Library Examples: Container Family: The Module Control

# Container Family: The Module Control

This example looks at the "standard module format" used by many components in YUI to represent modular content on the page. The Module Control is a JavaScript representation of a standard module, one that provides some basic plumbing for interacting with the head, body and foot sections of a standard module. Convenience methods for showing, hinding and rendering the module are also included in the Module Control.

You're most likely to use the Module Control when building a custom widget; its importance in the YUI Library is as a foundation rather than as a UI control in its own right.

View example in new window.

Module #1 from Markup
This is a Module that was marked up in the document.
End of Module #1

## Using the Module Control

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.

Module is fundamentally a building block for other UI controls. The concepts presented in this example will form the basis for the way that you interact with all of its subclasses.

Module has three required dependencies: the YAHOO Global object, the Event Utility, and the DOM Collection.

In addition, the JavaScript file for Container must be included. If you will not be using any of the pre-packaged rich controls (Tooltip, Panel, Dialog, or SimpleDialog), you can include the core libary (`container_core.js`), which only contains Module, Overlay, and its supporting classes. Otherwise, the full library should be included (`container.js`). You can see what the full list of included files looks like below. Please note that your file paths may vary depending on the location in which you installed the YUI libraries.

<script type="text/javascript" src="yahoo.js"></script> <script type="text/javascript" src="event.js" ></script> <script type="text/javascript" src="dom.js" ></script> <script type="text/javascript" src="container_core.js"></script>

Modules can be built using existing markup or dynamically at runtime using JavaScript. In this tutorial, we will construct two Modules: one from markup, and one from script only. First, we'll add the Module from markup to the document. The markup is in Standard Module Format, which consists of an outer container div element and three possible child div elements that represent the header, body, and/or footer:

<div id="module1" class="yui-pe-content"> <div class="hd">Module #1 from Markup</div> <div class="bd">This is a Module that was marked up in the document.</div> <div class="ft">End of Module #1</div> </div>

NOTE: The `yui-pe-content` class is not a Module requirement. It is used in this example to show how we can hide the markup from the users who have JavaScript enabled which we'll discuss later

Next, we'll build the JavaScript for our Modules and wrap it in a function to be executed when the window is finished loading. The Module called `module1` will be associated with our existing markup; `module2` will be created dynamically from script. In this tutorial, we pass to the Module constructor the one required argument: the id associated with that Module's container element.

<script> YAHOO.namespace("example.container"); YAHOO.util.Event.onDOMReady(function () { // Remove progressively enhanced content class, just before creating the module YAHOO.util.Dom.removeClass("module1", "yui-pe-content"); YAHOO.example.container.module1 = new YAHOO.widget.Module("module1", { visible: false }); YAHOO.example.container.module1.render(); YAHOO.example.container.module2 = new YAHOO.widget.Module("module2", { visible: false }); YAHOO.example.container.module2.setHeader("Module #2 from Script"); YAHOO.example.container.module2.setBody("This is a dynamically generated Module."); YAHOO.example.container.module2.setFooter("End of Module #2"); YAHOO.example.container.module2.render("module2"); }); </script>

Note that to avoid using the global variable space, we are placing our example Modules into the `YAHOO.example.container` namespace. For more information about namespacing, see the YAHOO Global object.

Because `module1` is already in the document, the call to the render method requires no arguments. If that element wasn't present in the document, we would pass into the `render` method the element into which we wanted the module rendered.

To see our newly created Modules more easily, we can add a style block that defines custom CSS for the `module` CSS class. By default, Module doesn't come with any predefined styles, so it is up to you as a developer to provide any applicable styles. Our style block will define the `module` CSS class such that Modules and each of their child elements will have distinct border colors:

<style> .module { border:1px dotted black;padding:5px;margin:10px; } .module .hd { border:1px solid red;padding:5px; } .module .bd { border:1px solid green;padding:5px; } .module .ft { border:1px solid blue;padding:5px; } </style>

Finally, we will add some HTML buttons to the page and wire them (using the YUI Event Utility) to the Modules' `show` and `hide` methods:

<div> <button id="show1">Show module1</button> <button id="hide1">Hide module1</button> </div> <div> <button id="show2">Show module2</button> <button id="hide2">Hide module2</button> </div> YAHOO.util.Event.addListener("show1", "click", YAHOO.example.container.module1.show, YAHOO.example.container.module1, true); YAHOO.util.Event.addListener("hide1", "click", YAHOO.example.container.module1.hide, YAHOO.example.container.module1, true); YAHOO.util.Event.addListener("show2", "click", YAHOO.example.container.module2.show, YAHOO.example.container.module2, true); YAHOO.util.Event.addListener("hide2", "click", YAHOO.example.container.module2.hide, YAHOO.example.container.module2, true);

## Avoiding The Initial Flash Of Unstyled Content

When rendering a Module from markup (the progressively enhanced solution), it is usually desirable to hide the markup until the Module is actually instantiated to avoid it being displayed in its unstyled form. However we don't want to hide the markup for users who may not have JavaScript enabled, since it may contain informative content. To achieve these two goals, we use a nested class rule, and add and remove classes programmatically:

.yui-pe .yui-pe-content { display:none; }

The `yui-pe` is added to an ancestor of the Module markup programmatically as early as possible in the page. In this example the class is added to the documentElement, however it could also be added to the body element. It is essentially is used to mark the fact that the page will be progressively enhanced (JavaScript is enabled). Adding it to the body or documentElement allows it to be used by multiple sections of widget markup on the page:

<script> document.documentElement.className = "yui-pe"; </script>

Additionally, the Markup which we want to hide temporarily for JavaScript enabled clients is marked with a `yui-pe-content` class, as shown in the Module markup example above.

Finally, just before we create a Module, we remove the temporary `yui-pe-content` so that the display:none does not impact the way the Module is rendered (NOTE: This is not really an issue for Module, but is required if using this technique for the other members of the container family, since they use `visiblity` instead of `display` to hide themselves:

// Remove progressively enhanced content class, just before creating the module YAHOO.util.Dom.removeClass("module1", "yui-pe-content"); YAHOO.example.container.module1 = new YAHOO.widget.Module("module1", { visible: false }); YAHOO.example.container.module1.render(); ...

The net result is that for clients which don't have JavaScript enabled, the body or documentElement will not have the `yui-pe` class, and so the markup will not be hidden. However for clients which do have JavaScript enabled, the markup will be hidden, until the Module is instantiated, at which point the modules visibility handling will take over.

## Configuration for This Example

You can load the necessary JavaScript and CSS for this example from Yahoo's servers. Click here to load the YUI Dependency Configurator with all of this example's dependencies preconfigured.

### YUI Logger Output:

Note: Logging and debugging is currently turned off for this example.

Reload with logging
and debugging enabled.

### Container Family Examples:

### More Container Family Resources:

- User's Guide (external)
- API Documentation
- Cheat Sheet PDF (external)

Copyright © 2010 Yahoo! Inc. All rights reserved.

Privacy Policy - Terms of Service - Copyright Policy - Job Openings