API: container YAHOO.widget.Module (YUI Library)

# Yahoo! UI Library

### Container 2.9.0

Yahoo! UI Library > container > YAHOO.widget.Module
Search:
Filters Show Private Show Protected Show Deprecated

## Class YAHOO.widget.Module

Known Subclasses:
  YAHOO.widget.Overlay

Module is a JavaScript representation of the Standard Module Format. Standard Module Format is a simple standard for markup containers where child nodes representing the header, body, and footer of the content are denoted using the CSS classes "hd", "bd", and "ft" respectively. Module is the base class for all other classes in the YUI Container package.

### Constructor

YAHOO.widget.Module `( el , userConfig )`

Parameters:
  `el <String>` The element ID representing the Module OR
  `el <HTMLElement>` The element representing the Module
  `userConfig <Object>` The configuration Object literal containing the configuration that should be set for this module. See configuration documentation for more details.

### Properties

#### body - `HTMLElement`

The body element, denoted with CSS class "bd"

#### browser - `{String|Boolean}`

String representing the user-agent of the browser
Deprecated: Use YAHOO.env.ua

#### cacheEffects - `boolean`

If true, ContainerEffects (and Anim instances) are cached when "effect" is set, and reused. If false, new instances are created each time the container is hidden or shown, as was the behavior prior to 2.9.0.
Default Value: true

#### cfg - `YAHOO.util.Config`

The Module's Config object used for monitoring configuration properties.

#### contructor - `Function`

The class's constructor function

#### DEFAULT_CONFIG - `private final Object`

Constant representing the Module's configuration properties

#### element - `HTMLElement`

The main module element that contains the header, body, and footer

#### EVENT_TYPES - `private final Object`

Constant representing the name of the Module's events

#### footer - `HTMLElement`

The footer element, denoted with CSS class "ft"

#### header - `HTMLElement`

The header element, denoted with CSS class "hd"

#### id - `String`

The id of the element

#### imageRoot - `String`

A string representing the root path for all images created by a Module instance.
Deprecated: It is recommend that any images for a Module be applied via CSS using the "background-image" property.

#### isSecure - `Boolean`

Boolean representing whether or not the current browsing context is secure (https)

#### platform - `{String|Boolean}`

String identifying whether the current platform is windows or mac. This property currently only identifies these 2 platforms, and returns false otherwise.
Deprecated: Use YAHOO.env.ua

#### YAHOO.widget.Module.CSS_BODY - `static final String`

CSS classname representing the module body. NOTE: The classname is inserted into the DOM as HTML, and should be escaped by the implementor if coming from an external source.

#### YAHOO.widget.Module.CSS_FOOTER - `static final String`

CSS classname representing the module footer. NOTE: The classname is inserted into the DOM as HTML, and should be escaped by the implementor if coming from an external source.

#### YAHOO.widget.Module.CSS_HEADER - `static final String`

CSS classname representing the module header. NOTE: The classname is inserted into the DOM as HTML, and should be escaped by the implementor if coming from an external source.

#### YAHOO.widget.Module.CSS_MODULE - `static final String`

Constant for the default CSS class name that represents a Module

#### YAHOO.widget.Module.IMG_ROOT - `static final String`

Constant representing the prefix path to use for non-secure images

#### YAHOO.widget.Module.IMG_ROOT_SSL - `static final String`

Constant representing the prefix path to use for securely served images

#### YAHOO.widget.Module.RESIZE_MONITOR_BUFFER - `static Number`

Constant representing the buffer amount (in pixels) to use when positioning the text resize monitor offscreen. The resize monitor is positioned offscreen by an amount eqaul to its offsetHeight + the buffer value.

#### YAHOO.widget.Module.RESIZE_MONITOR_SECURE_URL - `static final String`

Constant representing the url for the "src" attribute of the iframe used to monitor changes to the browser's base font size

### Methods

#### _addToParent

`protected void _addToParent ( The )`
This method is a protected helper, used when constructing the DOM structure for the module to account for situations which may cause Operation Aborted errors in IE. It should not be used for general DOM construction.

If the parentNode is not document.body, the element is appended as the last element.

If the parentNode is document.body the element is added as the first child to help prevent Operation Aborted errors in IE.

Parameters:
  `The <parentNode>` HTML element to which the element will be added
  `The <element>` HTML element to be added to parentNode's children

#### _createEffects

`protected Array _createEffects ( effectCfg )`
Creates an array of ContainerEffect instances from the provided configs

Parameters:
  `effectCfg <Array|Object>` An effect configuration or array of effect configurations

Returns: `Array`
  An array of ContainerEffect instances.

#### _initResizeMonitor

`protected void _initResizeMonitor ( )`
Create and initialize the text resize monitoring iframe.

#### _renderBody

`protected void _renderBody ( moduleElement )`
Renders the currently set body into it's proper position under the module element. If the module element is not provided, "this.element" is used.

Parameters:
  `moduleElement <HTMLElement>` Optional. A reference to the module element.

#### _renderFooter

`protected void _renderFooter ( moduleElement )`
Renders the currently set footer into it's proper position under the module element. If the module element is not provided, "this.element" is used.

Parameters:
  `moduleElement <HTMLElement>` Optional. A reference to the module element

#### _renderHeader

`protected void _renderHeader ( moduleElement )`
Renders the currently set header into it's proper position under the module element. If the module element is not provided, "this.element" is used.

Parameters:
  `moduleElement <HTMLElement>` Optional. A reference to the module element

#### _supportsCWResize

`private void _supportsCWResize ( )`
Text resize monitor helper method. Determines if the browser supports resize events on iframe content windows.

#### appendToBody

`void appendToBody ( element )`
Appends the passed element to the body. If no body is present, one will be automatically created.

Parameters:
  `element <HTMLElement | DocumentFragment>` The element to append to the body. In the case of a document fragment, the children of the fragment will be appended to the body.

#### appendToFooter

`void appendToFooter ( element )`
Appends the passed element to the footer. If no footer is present, one will be automatically created.

Parameters:
  `element <HTMLElement | DocumentFragment>` The element to append to the footer. In the case of a document fragment, the children of the fragment will be appended to the footer

#### appendToHeader

`void appendToHeader ( element )`
Appends the passed element to the header. If no header is present, one will be automatically created.

Parameters:
  `element <HTMLElement | DocumentFragment>` The element to append to the header. In the case of a document fragment, the children of the fragment will be appended to the header.

#### configEffect

`void configEffect ( type , args , obj )`
Default event handler for the "effect" configuration property

Parameters:
  `type <String>` The CustomEvent type (usually the property name)
  `args <Object[]>` The CustomEvent arguments. For configuration handlers, args[0] will equal the newly applied value for the property.
  `obj <Object>` The scope object. For configuration handlers, this will usually equal the owner.

#### configMonitorResize

`void configMonitorResize ( type , args , obj )`
Default event handler for the "monitorresize" configuration property

Parameters:
  `type <String>` The CustomEvent type (usually the property name)
  `args <Object[]>` The CustomEvent arguments. For configuration handlers, args[0] will equal the newly applied value for the property.
  `obj <Object>` The scope object. For configuration handlers, this will usually equal the owner.

#### configVisible

`void configVisible ( type , args , obj )`
Default event handler for changing the visibility property of a Module. By default, this is achieved by switching the "display" style between "block" and "none". This method is responsible for firing showEvent and hideEvent.

Parameters:
  `type <String>` The CustomEvent type (usually the property name)
  `args <Object[]>` The CustomEvent arguments. For configuration handlers, args[0] will equal the newly applied value for the property.
  `obj <Object>` The scope object. For configuration handlers, this will usually equal the owner.

#### destroy

`void destroy ( shallowPurge )`
Removes the Module element from the DOM, sets all child elements to null, and purges the bounding element of event listeners.

Parameters:
  `shallowPurge <boolean>` If true, only the parent element's DOM event listeners are purged. If false, or not provided, all children are also purged of DOM event listeners. NOTE: The flag is a "shallowPurge" flag, as opposed to what may be a more intuitive "purgeChildren" flag to maintain backwards compatibility with behavior prior to 2.9.0.

#### hide

`void hide ( )`
Hides the Module element by setting the visible configuration property to false. Also fires two events: beforeHideEvent prior to the visibility change, and hideEvent after.

#### init

`void init ( el , userConfig )`
The Module class's initialization method, which is executed for Module and all of its subclasses. This method is automatically called by the constructor, and sets up all DOM references for pre-existing markup, and creates required markup if it is not already present.

If the element passed in does not have an id, one will be generated for it.

Parameters:
  `el <String>` The element ID representing the Module OR
  `el <HTMLElement>` The element representing the Module
  `userConfig <Object>` The configuration Object literal containing the configuration that should be set for this module. See configuration documentation for more details.

#### initDefaultConfig

`void initDefaultConfig ( )`
Initializes the custom events for Module which are fired automatically at appropriate times by the Module class.

#### initEvents

`void initEvents ( )`
Initializes the custom events for Module which are fired automatically at appropriate times by the Module class.

#### initResizeMonitor

`void initResizeMonitor ( )`
Initialize an empty IFRAME that is placed out of the visible area that can be used to detect text resize.

#### onDomResize

`void onDomResize ( e , obj )`
Event handler fired when the resize monitor element is resized.

Parameters:
  `e <DOMEvent>` The DOM resize event
  `obj <Object>` The scope object passed to the handler

#### render

`Boolean render ( appendToNode , moduleElement )`
Renders the Module by inserting the elements that are not already in the main Module into their correct places. Optionally appends the Module to the specified node prior to the render's execution.

For Modules without existing markup, the appendToNode argument is REQUIRED. If this argument is ommitted and the current element is not present in the document, the function will return false, indicating that the render was a failure.

NOTE: As of 2.3.1, if the appendToNode is the document's body element then the module is rendered as the first child of the body element, and not appended to it, to avoid Operation Aborted errors in IE when rendering the module before window's load event is fired. You can use the appendtodocumentbody configuration property to change this to append to document.body if required.

Parameters:
  `appendToNode <String>` The element id to which the Module should be appended to prior to rendering OR
  `appendToNode <HTMLElement>` The element to which the Module should be appended to prior to rendering
  `moduleElement <HTMLElement>` OPTIONAL. The element that represents the actual Standard Module container.

Returns: `Boolean`
  Success or failure of the render

#### setBody

`void setBody ( bodyContent )`
Sets the Module's body content to the HTML specified. If no body is present, one will be automatically created. An empty string can be passed to the method to clear the contents of the body.

Parameters:
  `bodyContent <HTML>` The HTML used to set the body content As a convenience, non HTMLElement objects can also be passed into the method, and will be treated as strings, with the body innerHTML set to their default toString implementations.

  NOTE: Markup passed into this method is added to the DOM as HTML, and should be escaped by the implementor if coming from an external source.

  OR
  `bodyContent <HTMLElement>` The HTMLElement to add as the first and only child of the body element. OR
  `bodyContent <DocumentFragment>` The document fragment containing elements which are to be added to the body

#### setFooter

`void setFooter ( footerContent )`
Sets the Module's footer content to the HTML specified, or appends the passed element to the footer. If no footer is present, one will be automatically created. An empty string can be passed to the method to clear the contents of the footer.

Parameters:
  `footerContent <HTML>` The HTML used to set the footer As a convenience, non HTMLElement objects can also be passed into the method, and will be treated as strings, with the footer innerHTML set to their default toString implementations.

  NOTE: Markup passed into this method is added to the DOM as HTML, and should be escaped by the implementor if coming from an external source.

  OR
  `footerContent <HTMLElement>` The HTMLElement to append to the footer OR
  `footerContent <DocumentFragment>` The document fragment containing elements which are to be added to the footer

#### setHeader

`void setHeader ( headerContent )`
Sets the Module's header content to the markup specified, or appends the passed element to the header. If no header is present, one will be automatically created. An empty string can be passed to the method to clear the contents of the header.

Parameters:
  `headerContent <HTML>` The markup used to set the header content. As a convenience, non HTMLElement objects can also be passed into the method, and will be treated as strings, with the header innerHTML set to their default toString implementations.

  NOTE: Markup passed into this method is added to the DOM as HTML, and should be escaped by the implementor if coming from an external source.

  OR
  `headerContent <HTMLElement>` The HTMLElement to append to OR
  `headerContent <DocumentFragment>` The document fragment containing elements which are to be added to the header

#### show

`void show ( )`
Shows the Module element by setting the visible configuration property to true. Also fires two events: beforeShowEvent prior to the visibility change, and showEvent after.

#### toString

`String toString ( )`
Returns a String representation of the Object.

Returns: `String`
  The string representation of the Module

#### YAHOO.widget.Module.forceDocumentRedraw

`static void YAHOO.widget.Module.forceDocumentRedraw ( )`
Helper utility method, which forces a document level redraw for Opera, which can help remove repaint irregularities after applying DOM changes.

### Events

#### appendEvent

`appendEvent ( )`
CustomEvent fired when the Module is appended to the DOM

#### beforeHideEvent

`beforeHideEvent ( )`
CustomEvent fired before the Module is hidden

#### beforeInitEvent

`beforeInitEvent ( classRef )`
CustomEvent fired prior to class initalization.

Parameters:
  `classRef <class>` class reference of the initializing class, such as this.beforeInitEvent.fire(Module)

#### beforeRenderEvent

`beforeRenderEvent ( )`
CustomEvent fired before the Module is rendered

#### beforeShowEvent

`beforeShowEvent ( )`
CustomEvent fired before the Module is shown

#### changeBodyEvent

`changeBodyEvent ( content )`
CustomEvent fired when the body content of the Module is modified

Parameters:
  `content <String/HTMLElement>` String/element representing the new body content

#### changeContentEvent

`changeContentEvent ( )`
CustomEvent fired when the content of the Module is modified

#### changeFooterEvent

`changeFooterEvent ( content )`
CustomEvent fired when the footer content of the Module is modified

Parameters:
  `content <String/HTMLElement>` String/element representing the new footer content

#### changeHeaderEvent

`changeHeaderEvent ( content )`
CustomEvent fired when the header content of the Module is modified

Parameters:
  `content <String/HTMLElement>` String/element representing the new header content

#### destroyEvent

`destroyEvent ( )`
CustomEvent fired when the Module is destroyed

#### hideEvent

`hideEvent ( )`
CustomEvent fired after the Module is hidden

#### initEvent

`initEvent ( classRef )`
CustomEvent fired after class initalization.

Parameters:
  `classRef <class>` class reference of the initializing class, such as this.beforeInitEvent.fire(Module)

#### renderEvent

`renderEvent ( )`
CustomEvent fired after the Module is rendered

#### showEvent

`showEvent ( )`
CustomEvent fired after the Module is shown

#### YAHOO.widget.Module.textResizeEvent

`YAHOO.widget.Module.textResizeEvent ( )`
Singleton CustomEvent fired when the font size is changed in the browser. Opera's "zoom" functionality currently does not support text size detection.

### Configuration Attributes

#### appendtodocumentbody `- Boolean`

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.

Default Value: false

#### effect `- Object`

Object or array of objects representing the ContainerEffect classes that are active for animating the container.

NOTE: Although this configuration property is introduced at the Module level, an out of the box implementation is not shipped for the Module class so setting the proroperty on the Module class has no effect. The Overlay class is the first class to provide out of the box ContainerEffect support.

Default Value: null

#### monitorresize `- Boolean`

Specifies whether to create a special proxy iframe to monitor for user font resizing in the document
Default Value: true

#### visible `- Boolean`

Specifies whether the Module is visible on the page.
Default Value: true

Copyright © 2011 Yahoo! Inc. All rights reserved.