Print Friendly

# Class YAHOO.util.Config

Package: | YAHOO.util
Class: | Config
Extends: | Object
Defined In: | container_core.js

Config is a utility used within an Object to allow the implementer to maintain a list of local configuration properties and listen for changes to those properties dynamically using CustomEvent. The initial values are also maintained so that the configuration can be reset at any given point to its initial state.

## Public Properties

Property | Defined By
--- | ---
| CSS_BODY<static> : String | Config
<static> Constant representing the module body
| CSS_FOOTER<static> : String | Config
<static> Constant representing the module footer
| CSS_HEADER<static> : String | Config
<static> Constant representing the module header
| CSS_MODULE<static> : String | Config
<static> Constant for the default CSS class name that represents a Module
| body : HTMLElement | Config
The body element, denoted with CSS class "bd"
| browser : String | Config
String representing the current user-agent browser
| cfg : YAHOO.util.Config | Config
The Module's Config object used for monitoring configuration properties.
| contructor : Function | Config
The class's constructor function
| element : HTMLElement | Config
The main module element that contains the header, body, and footer
| footer : HTMLElement | Config
The footer element, denoted with CSS class "ft"
| header : HTMLElement | Config
The header element, denoted with CSS class "hd"
| http : String | Config
<static> Constant representing the prefix path to use for non-secure images
| https : String | Config
<static> Constant representing the prefix path to use for securely served images
| id : String | Config
The id of the element
| imageRoot : String | Config
The String representing the image root
| isSecure : Boolean | Config
Boolean representing whether or not the current browsing context is secure (https)
| javascript : String | Config
<static> Constant representing the url for the "src" attribute of the iframe used to monitor changes to the bro...
| owner : Object | Config
Object reference to the owner of this Config Object
| platform : String | Config
String representing the current user-agent platform
| queueInProgress : Boolean | Config
Boolean flag that specifies whether a queue is currently being executed

## Public Methods

Method | Defined By
--- | ---
| Config(`Object owner`) | Config
| addProperty(`String key`, `Object propertyObject`) : void | Config
Adds a property to the Config Object's private config hash.
| alreadySubscribed<static>(`YAHOO.util.CustomEvent evt`, `Function fn`, `Object obj`) : Boolean | Config
<static> Checks to determine if a particular function/Object pair are already subscribed to the specified Custo...
| appendToBody(`HTMLElement element`) : void | Config
Appends the passed element to the body. If no body is present, one will be automatically created.
| appendToFooter(`HTMLElement element`) : void | Config
Appends the passed element to the footer. If no footer is present, one will be automatically created.
| appendToHeader(`HTMLElement element`) : void | Config
Appends the passed element to the header. If no header is present, one will be automatically created.
| applyConfig(`Object userConfig`, `Boolean init`) : void | Config
Applies a key-value Object literal to the configuration, replacing any existing values, and queueing the property eve...
| checkBoolean(`Object val`) : Boolean | Config
Validates that the value passed in is a Boolean.
| checkNumber(`Object val`) : Boolean | Config
Validates that the value passed in is a number.
| configMonitorResize(`String type`, `Object[] args`, `Object obj`) : void | Config
Default event handler for the "monitorresize" configuration property
| configVisible(`String type`, `Object[] args`, `Object obj`) : void | Config
Default event handler for changing the visibility property of a Module. By default, this is achieved by switching the...
| destroy() : void | Config
Removes the Module element from the DOM and sets all child elements to null.
| fireQueue() : void | Config
Fires the normalized list of queued property change events
| getConfig() : Object | Config
Returns a key-value configuration map of the values currently set in the Config Object.
| getProperty(`String key`) : Object | Config
Returns the value of specified property.
| hide() : void | Config
Hides the Module element by setting the visible configuration property to false. Also fires two events: beforeHideEve...
| init(`String el`, `HTMLElement el`, `Object userConfig`) : void | Config
The Module class's initialization method, which is executed for Module and all of its subclasses. This method is auto...
| initDefaultConfig() : void | Config
Initializes the custom events for Module which are fired automatically at appropriate times by the Module class.
| initEvents() : void | Config
Initializes the custom events for Module which are fired automatically at appropriate times by the Module class.
| initResizeMonitor() : void | Config
Initialized an empty IFRAME that is placed out of the visible area that can be used to detect text resize.
| onDomResize(`DOMEvent e`, `Object obj`) : void | Config
Event handler fired when the resize monitor element is resized.
| outputEventQueue() : String | Config
Returns a string representation of the Config object's current CustomEvent queue
| queueProperty(`String key`, `String value`) : Boolean | Config
Sets the value of a property and queues its event to execute. If the event is already scheduled to execute, it is mov...
| refireEvent(`String key`) : void | Config
Fires the event for a property using the property's current value.
| refresh() : void | Config
Refires the events for all configuration properties using their current values.
| render(`String appendToNode`, `HTMLElement appendToNode`, `HTMLElement moduleElement`) : Boolean | Config
Renders the Module by inserting the elements that are not already in the main Module into their correct places. Optio...
| resetProperty(`String key`) : Boolean | Config
Resets the specified property's value to its initial value.
| setBody(`String bodyContent`, `HTMLElement bodyContent`) : void | Config
Sets the Module's body content to the HTML specified, or appends the passed element to the body. If no body is presen...
| setFooter(`String footerContent`, `HTMLElement footerContent`) : void | Config
Sets the Module's footer content to the HTML specified, or appends the passed element to the footer. If no footer is ...
| setHeader(`String headerContent`, `HTMLElement headerContent`) : void | Config
Sets the Module's header content to the HTML specified, or appends the passed element to the header. If no header is ...
| setProperty(`String key`, `String value`, `Boolean silent`) : Boolean | Config
Sets the value of a property. If the silent property is passed as true, the property's event will not be fired.
| show() : void | Config
Shows the Module element by setting the visible configuration property to true. Also fires two events: beforeShowEven...
| subscribeToConfigEvent(`String key`, `Function handler`, `Object obj`, `Boolean override`) : Boolean | Config
Subscribes an external handler to the change event for any given property.
| toString() : String | Config
Returns a String representation of the Object.
| unsubscribeFromConfigEvent(`String key`, `Function handler`, `Object obj`) : Boolean | Config
Unsubscribes an external handler from the change event for any given property.

## Public Events

Event | Defined By
--- | ---
| appendEvent : () | Config
CustomEvent fired when the Module is appended to the DOM
| beforeHideEvent : () | Config
CustomEvent fired before the Module is hidden
| beforeInitEvent : (`class classRef`) | Config
CustomEvent fired prior to class initalization.
| beforeRenderEvent : () | Config
CustomEvent fired before the Module is rendered
| beforeShowEvent : () | Config
CustomEvent fired before the Module is shown
| changeBodyEvent : (`String/HTMLElement content`) | Config
CustomEvent fired when the body content of the Module is modified
| changeContentEvent : () | Config
CustomEvent fired when the content of the Module is modified
| changeFooterEvent : (`String/HTMLElement content`) | Config
CustomEvent fired when the footer content of the Module is modified
| changeHeaderEvent : (`String/HTMLElement content`) | Config
CustomEvent fired when the header content of the Module is modified
| configChangedEvent : () | Config
Object reference to the owner of this Config Object
| destroyEvent : () | Config
CustomEvent fired when the Module is destroyed
| hideEvent : () | Config
CustomEvent fired after the Module is hidden
| initEvent : (`class classRef`) | Config
CustomEvent fired after class initalization.
| renderEvent : () | Config
CustomEvent fired after the Module is rendered
| showEvent : () | Config
CustomEvent fired after the Module is shown

## Property Details

### CSS_BODY<static>

`public String CSS_BODY<static>`
<static> Constant representing the module body
This property is defined by Config.

### CSS_FOOTER<static>

`public String CSS_FOOTER<static>`
<static> Constant representing the module footer
This property is defined by Config.

### CSS_HEADER<static>

`public String CSS_HEADER<static>`
<static> Constant representing the module header
This property is defined by Config.

### CSS_MODULE<static>

`public String CSS_MODULE<static>`
<static> Constant for the default CSS class name that represents a Module
This property is defined by Config.

### body

`public HTMLElement body`
The body element, denoted with CSS class "bd"
This property is defined by Config.

### browser

`public String browser`
String representing the current user-agent browser
This property is defined by Config.

### cfg

`public YAHOO.util.Config cfg`
The Module's Config object used for monitoring configuration properties.
This property is defined by Config.

### contructor

`public Function contructor`
The class's constructor function
This property is defined by Config.

### element

`public HTMLElement element`
The main module element that contains the header, body, and footer
This property is defined by Config.

### footer

`public HTMLElement footer`
The footer element, denoted with CSS class "ft"
This property is defined by Config.

### header

`public HTMLElement header`
The header element, denoted with CSS class "hd"
This property is defined by Config.

### http

`public String http`
<static> Constant representing the prefix path to use for non-secure images
This property is defined by Config.

### https

`public String https`
<static> Constant representing the prefix path to use for securely served images
This property is defined by Config.

### id

`public String id`
The id of the element
This property is defined by Config.

### imageRoot

`public String imageRoot`
The String representing the image root
This property is defined by Config.

### isSecure

`public Boolean isSecure`
Boolean representing whether or not the current browsing context is secure (https)
This property is defined by Config.

### javascript

`public String javascript`
<static> Constant representing the url for the "src" attribute of the iframe used to monitor changes to the browser's base font size
This property is defined by Config.

### owner

`public Object owner`
Object reference to the owner of this Config Object
This property is defined by Config.

### platform

`public String platform`
String representing the current user-agent platform
This property is defined by Config.

### queueInProgress

`public Boolean queueInProgress`
Boolean flag that specifies whether a queue is currently being executed
This property is defined by Config.

## Constructor Details

### Config

`public function Config(`Object owner`)`
Parameters:

- `owner` : Object
  The owner Object to which this Config Object belongs

## Method Details

### addProperty

`public function addProperty(`String key`, `Object propertyObject`)`
Adds a property to the Config Object's private config hash.
Parameters:

- `key` : String
  The configuration property's name
- `propertyObject` : Object
  The Object containing all of this property's arguments

Returns:

- `void`

This method is defined by Config.

### alreadySubscribed<static>

`public function alreadySubscribed<static>(`YAHOO.util.CustomEvent evt`, `Function fn`, `Object obj`)`
<static> Checks to determine if a particular function/Object pair are already subscribed to the specified CustomEvent
Parameters:

- `evt` : YAHOO.util.CustomEvent
  The CustomEvent for which to check the subscriptions
- `fn` : Function
  The function to look for in the subscribers list
- `obj` : Object
  The execution scope Object for the subscription

Returns:

- `Boolean`
  true, if the function/Object pair is already subscribed to the CustomEvent passed in

This method is defined by Config.

### appendToBody

`public function appendToBody(`HTMLElement element`)`
Appends the passed element to the body. If no body is present, one will be automatically created.
Parameters:

- `element` : HTMLElement
  The element to append to the body

Returns:

- `void`

This method is defined by Config.

### appendToFooter

`public function appendToFooter(`HTMLElement element`)`
Appends the passed element to the footer. If no footer is present, one will be automatically created.
Parameters:

- `element` : HTMLElement
  The element to append to the footer

Returns:

- `void`

This method is defined by Config.

### appendToHeader

`public function appendToHeader(`HTMLElement element`)`
Appends the passed element to the header. If no header is present, one will be automatically created.
Parameters:

- `element` : HTMLElement
  The element to append to the header

Returns:

- `void`

This method is defined by Config.

### applyConfig

`public function applyConfig(`Object userConfig`, `Boolean init`)`
Applies a key-value Object literal to the configuration, replacing any existing values, and queueing the property events. Although the values will be set, fireQueue() must be called for their associated events to execute.
Parameters:

- `userConfig` : Object
  The configuration Object literal
- `init` : Boolean
  When set to true, the initialConfig will be set to the userConfig passed in, so that calling a reset will reset the properties to the passed values.

Returns:

- `void`

This method is defined by Config.

### checkBoolean

`public function checkBoolean(`Object val`)`
Validates that the value passed in is a Boolean.
Parameters:

- `val` : Object
  The value to validate

Returns:

- `Boolean`
  true, if the value is valid

This method is defined by Config.

### checkNumber

`public function checkNumber(`Object val`)`
Validates that the value passed in is a number.
Parameters:

- `val` : Object
  The value to validate

Returns:

- `Boolean`
  true, if the value is valid

This method is defined by Config.

### configMonitorResize

`public function configMonitorResize(`String type`, `Object[] args`, `Object 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.

Returns:

- `void`

This method is defined by Config.

### configVisible

`public function configVisible(`String type`, `Object[] args`, `Object 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.

Returns:

- `void`

This method is defined by Config.

### destroy

`public function destroy()`
Removes the Module element from the DOM and sets all child elements to null.
Parameters:

- None.

Returns:

- `void`

This method is defined by Config.

### fireQueue

`public function fireQueue()`
Fires the normalized list of queued property change events
Parameters:

- None.

Returns:

- `void`

This method is defined by Config.

### getConfig

`public function getConfig()`
Returns a key-value configuration map of the values currently set in the Config Object.
Parameters:

- None.

Returns:

- `Object`
  The current config, represented in a key-value map

This method is defined by Config.

### getProperty

`public function getProperty(`String key`)`
Returns the value of specified property.
Parameters:

- `key` : String
  The name of the property

Returns:

- `Object`
  The value of the specified property

This method is defined by Config.

### hide

`public function 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.
Parameters:

- None.

Returns:

- `void`

This method is defined by Config.

### init

`public function init(`String el`, `HTMLElement el`, `Object 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.
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.

Returns:

- `void`

This method is defined by Config.

### initDefaultConfig

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

- None.

Returns:

- `void`

This method is defined by Config.

### initEvents

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

- None.

Returns:

- `void`

This method is defined by Config.

### initResizeMonitor

`public function initResizeMonitor()`
Initialized an empty IFRAME that is placed out of the visible area that can be used to detect text resize.
Parameters:

- None.

Returns:

- `void`

This method is defined by Config.

### onDomResize

`public function onDomResize(`DOMEvent e`, `Object 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

Returns:

- `void`

This method is defined by Config.

### outputEventQueue

`public function outputEventQueue()`
Returns a string representation of the Config object's current CustomEvent queue
Parameters:

- None.

Returns:

- `String`
  The string list of CustomEvents currently queued for execution

This method is defined by Config.

### queueProperty

`public function queueProperty(`String key`, `String value`)`
Sets the value of a property and queues its event to execute. If the event is already scheduled to execute, it is moved from its current position to the end of the queue.
Parameters:

- `key` : String
  The name of the property
- `value` : String
  The value to set the property to

Returns:

- `Boolean`
  true, if the set was successful, false if it failed.

This method is defined by Config.

### refireEvent

`public function refireEvent(`String key`)`
Fires the event for a property using the property's current value.
Parameters:

- `key` : String
  The name of the property

Returns:

- `void`

This method is defined by Config.

### refresh

`public function refresh()`
Refires the events for all configuration properties using their current values.
Parameters:

- None.

Returns:

- `void`

This method is defined by Config.

### render

`public function render(`String appendToNode`, `HTMLElement appendToNode`, `HTMLElement 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. NOTE: 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.
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

This method is defined by Config.

### resetProperty

`public function resetProperty(`String key`)`
Resets the specified property's value to its initial value.
Parameters:

- `key` : String
  The name of the property

Returns:

- `Boolean`
  True is the property was reset, false if not

This method is defined by Config.

### setBody

`public function setBody(`String bodyContent`, `HTMLElement bodyContent`)`
Sets the Module's body content to the HTML specified, or appends the passed element to the body. If no body is present, one will be automatically created.
Parameters:

- `bodyContent` : String
  The HTML used to set the body OR
- `bodyContent` : HTMLElement
  The HTMLElement to append to the body

Returns:

- `void`

This method is defined by Config.

### setFooter

`public function setFooter(`String footerContent`, `HTMLElement 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.
Parameters:

- `footerContent` : String
  The HTML used to set the footer OR
- `footerContent` : HTMLElement
  The HTMLElement to append to the footer

Returns:

- `void`

This method is defined by Config.

### setHeader

`public function setHeader(`String headerContent`, `HTMLElement headerContent`)`
Sets the Module's header content to the HTML specified, or appends the passed element to the header. If no header is present, one will be automatically created.
Parameters:

- `headerContent` : String
  The HTML used to set the header OR
- `headerContent` : HTMLElement
  The HTMLElement to append to the header

Returns:

- `void`

This method is defined by Config.

### setProperty

`public function setProperty(`String key`, `String value`, `Boolean silent`)`
Sets the value of a property. If the silent property is passed as true, the property's event will not be fired.
Parameters:

- `key` : String
  The name of the property
- `value` : String
  The value to set the property to
- `silent` : Boolean
  Whether the value should be set silently, without firing the property event.

Returns:

- `Boolean`
  True, if the set was successful, false if it failed.

This method is defined by Config.

### show

`public function 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.
Parameters:

- None.

Returns:

- `void`

This method is defined by Config.

### subscribeToConfigEvent

`public function subscribeToConfigEvent(`String key`, `Function handler`, `Object obj`, `Boolean override`)`
Subscribes an external handler to the change event for any given property.
Parameters:

- `key` : String
  The property name
- `handler` : Function
  The handler function to use subscribe to the property's event
- `obj` : Object
  The Object to use for scoping the event handler (see CustomEvent documentation)
- `override` : Boolean
  Optional. If true, will override "this" within the handler to map to the scope Object passed into the method.

Returns:

- `Boolean`
  True, if the subscription was successful, otherwise false.

This method is defined by Config.

### toString

`public function toString()`
Returns a String representation of the Object.
Parameters:

- None.

Returns:

- `String`
  The string representation of the Module

This method is defined by Config.

### unsubscribeFromConfigEvent

`public function unsubscribeFromConfigEvent(`String key`, `Function handler`, `Object obj`)`
Unsubscribes an external handler from the change event for any given property.
Parameters:

- `key` : String
  The property name
- `handler` : Function
  The handler function to use subscribe to the property's event
- `obj` : Object
  The Object to use for scoping the event handler (see CustomEvent documentation)

Returns:

- `Boolean`
  True, if the unsubscription was successful, otherwise false.

This method is defined by Config.

## Event Details

### appendEvent

`public event appendEvent`
CustomEvent fired when the Module is appended to the DOM
Subscribers will be called with the following parameters:

- None.

This event is defined by Config.

### beforeHideEvent

`public event beforeHideEvent`
CustomEvent fired before the Module is hidden
Subscribers will be called with the following parameters:

- None.

This event is defined by Config.

### beforeInitEvent

`public event beforeInitEvent`
CustomEvent fired prior to class initalization.
Subscribers will be called with the following parameters:

- `classRef` : class
  class reference of the initializing class, such as this.beforeInitEvent.fire(YAHOO.widget.Module)

This event is defined by Config.

### beforeRenderEvent

`public event beforeRenderEvent`
CustomEvent fired before the Module is rendered
Subscribers will be called with the following parameters:

- None.

This event is defined by Config.

### beforeShowEvent

`public event beforeShowEvent`
CustomEvent fired before the Module is shown
Subscribers will be called with the following parameters:

- None.

This event is defined by Config.

### changeBodyEvent

`public event changeBodyEvent`
CustomEvent fired when the body content of the Module is modified
Subscribers will be called with the following parameters:

- `content` : String/HTMLElement
  String/element representing the new body content

This event is defined by Config.

### changeContentEvent

`public event changeContentEvent`
CustomEvent fired when the content of the Module is modified
Subscribers will be called with the following parameters:

- None.

This event is defined by Config.

### changeFooterEvent

`public event changeFooterEvent`
CustomEvent fired when the footer content of the Module is modified
Subscribers will be called with the following parameters:

- `content` : String/HTMLElement
  String/element representing the new footer content

This event is defined by Config.

### changeHeaderEvent

`public event changeHeaderEvent`
CustomEvent fired when the header content of the Module is modified
Subscribers will be called with the following parameters:

- `content` : String/HTMLElement
  String/element representing the new header content

This event is defined by Config.

### configChangedEvent

`public event configChangedEvent`
Object reference to the owner of this Config Object
Subscribers will be called with the following parameters:

- None.

This event is defined by Config.

### destroyEvent

`public event destroyEvent`
CustomEvent fired when the Module is destroyed
Subscribers will be called with the following parameters:

- None.

This event is defined by Config.

### hideEvent

`public event hideEvent`
CustomEvent fired after the Module is hidden
Subscribers will be called with the following parameters:

- None.

This event is defined by Config.

### initEvent

`public event initEvent`
CustomEvent fired after class initalization.
Subscribers will be called with the following parameters:

- `classRef` : class
  class reference of the initializing class, such as this.beforeInitEvent.fire(YAHOO.widget.Module)

This event is defined by Config.

### renderEvent

`public event renderEvent`
CustomEvent fired after the Module is rendered
Subscribers will be called with the following parameters:

- None.

This event is defined by Config.

### showEvent

`public event showEvent`
CustomEvent fired after the Module is shown
Subscribers will be called with the following parameters:

- None.

This event is defined by Config.

Copyright © 2006 Jack Slocum. All rights reserved.