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

# Yahoo! UI Library

### Container 2.9.0

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

## Class YAHOO.widget.Panel - extends YAHOO.widget.Overlay

Known Subclasses:
  YAHOO.widget.Dialog

Panel is an implementation of Overlay that behaves like an OS window, with a draggable header and an optional close icon at the top right.

### Constructor

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

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

### Properties

#### dd - `YAHOO.util.DD`

The YAHOO.util.DD instance, used to implement the draggable header for the panel if draggable is enabled

#### DEFAULT_CONFIG - `private final Object`

Constant representing the Panel's configuration properties

#### EVENT_TYPES - `private final Object`

Constant representing the name of the Panel's events

#### YAHOO.widget.Panel.CSS_PANEL - `static final String`

Constant representing the default CSS class used for a Panel

#### YAHOO.widget.Panel.CSS_PANEL_CONTAINER - `static final String`

Constant representing the default CSS class used for a Panel's wrapping container

#### YAHOO.widget.Panel.FOCUSABLE - `static Array`

Constant representing the default set of focusable elements on the pagewhich Modal Panels will prevent access to, when the modal mask is displayed

#### Properties inherited from YAHOO.widget.Module:

`body, browser, cacheEffects, cfg, contructor, DEFAULT_CONFIG, element, EVENT_TYPES, footer, header, id, imageRoot, isSecure, platform`

#### Properties inherited from YAHOO.widget.Overlay:

`CONTEXT_TRIGGERS, DEFAULT_CONFIG, EVENT_TYPES, YAHOO.widget.Overlay._initialized`

### Methods

#### _addFocusHandlers

`protected void _addFocusHandlers ( p_sType , p_aArgs )`
"showMask" event handler that adds a "focus" event handler to all focusable elements in the document to enforce a Panel instance's modality from being compromised.

Parameters:
  `p_sType <String>` Custom event type
  `p_aArgs <Array>` Custom event arguments

#### _autoFillOnHeightChange

`protected void _autoFillOnHeightChange ( type , args , el )`
The default custom event handler executed when the Panel's height is changed, if the autofillheight property has been set.

Parameters:
  `type <String>` The event type
  `args <Array>` The array of arguments passed to event subscribers
  `el <HTMLElement>` The header, body or footer element which is to be resized to fill out the containers height

#### _createHiddenFocusElement

`private void _createHiddenFocusElement ( )`
Creates a hidden focusable element, used to focus on, to enforce modality for browsers in which focus cannot be applied to the container box.

#### _doClose

`protected void _doClose ( e )`
Event handler for the close icon

Parameters:
  `e <DOMEvent>`

#### _focusFirstModal

`void _focusFirstModal ( )`
Focuses on the first element if present, otherwise falls back to the focus mechanisms used for modality. This method does not try/catch focus failures. The caller is responsible for catching exceptions, and taking remedial measures.

#### _focusOnShow

`void _focusOnShow ( type , args , obj )`
Focus handler for the show event

Parameters:
  `type <String>` Event Type
  `args <Array>` Event arguments
  `obj <Object>` Additional data

#### _onElementFocus

`private void _onElementFocus ( e )`
"focus" event handler for a focuable element. Used to automatically blur the element when it receives focus to ensure that a Panel instance's modality is not compromised.

Parameters:
  `e <Event>` The DOM event object

#### _removeFocusHandlers

`protected void _removeFocusHandlers ( p_sType , p_aArgs )`
"hideMask" event handler that removes all "focus" event handlers added by the "addFocusEventHandlers" method.

Parameters:
  `p_sType <String>` Event type
  `p_aArgs <Array>` Event Arguments

#### _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.innerElement" 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.innerElement" 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.innerElement" is used.

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

#### _setTabLoop

`protected void _setTabLoop ( firstElement , lastElement )`
Protected internal method for setTabLoop, which can be used by subclasses to jump in and modify the arguments passed in if required.

Parameters:
  `firstElement <HTMLElement>`
  `lastElement <HTMLElement>`

#### _testIfFocusable

`protected void _testIfFocusable ( el , focusable )`
This is the test method used by getFocusableElements, to determine which elements to include in the focusable elements list. Users may override this to customize behavior.

Parameters:
  `el <Object>` The element being tested
  `focusable <Object>` The hash of known focusable elements, created by an array-to-map operation on Panel.FOCUSABLE

#### buildMask

`void buildMask ( )`
Builds the mask that is laid over the document when the Panel is configured to be modal.

#### buildWrapper

`void buildWrapper ( )`
Builds the wrapping container around the Panel that is used for positioning the shadow and matte underlays. The container element is assigned to a local instance variable called container, and the element is reinserted inside of it.

#### configClose

`void configClose ( type , args , obj )`
The default event handler fired when the "close" property is changed. The method controls the appending or hiding of the close icon at the top right of the Panel.

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.

#### configDraggable

`void configDraggable ( type , args , obj )`
The default event handler fired when the "draggable" property is changed.

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.

#### configHeight

`void configHeight ( type , args , obj )`
The default event handler fired when the "height" property is changed.

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.

#### configKeyListeners

`void configKeyListeners ( type , args , obj )`
The default event handler fired when the "keylisteners" property is changed.

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.

#### configModal

`void configModal ( type , args , obj )`
The default event handler fired when the "modal" property is changed. This handler subscribes or unsubscribes to the show and hide events to handle the display or hide of the modality mask.

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.

#### configStrings

`void configStrings ( )`
The default handler for the "strings" property

#### configUnderlay

`void configUnderlay ( type , args , obj )`
The default event handler fired when the "underlay" property is changed.

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.

#### configWidth

`void configWidth ( type , args , obj )`
The default event handler fired when the "width" property is changed.

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.

#### configzIndex

`void configzIndex ( type , args , obj )`
The default event handler fired when the "zIndex" property is changed.

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 Panel element from the DOM and sets all child elements to null.

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.

#### focusFirst

`Boolean focusFirst ( )`
Sets focus to the first element in the Panel.

Returns: `Boolean`
  true, if successfully focused, false otherwise

#### focusLast

`Boolean focusLast ( )`
Sets focus to the last element in the Panel.

Returns: `Boolean`
  true, if successfully focused, false otherwise

#### forceUnderlayRedraw

`void forceUnderlayRedraw ( )`
Forces the underlay element to be repainted through the application/removal of a yui-force-redraw class to the underlay element.

#### getFocusableElements

`void getFocusableElements ( root )`
Returns an array of the currently focusable items which reside within Panel. The set of focusable elements the method looks for are defined in the Panel.FOCUSABLE static property

Parameters:
  `root <HTMLElement>` element to start from.

#### hideMask

`void hideMask ( )`
Hides the modality mask.

#### init

`void init ( el , userConfig )`
The Overlay initialization method, which is executed for Overlay 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 Overlay OR
  `el <HTMLElement>` The element representing the Overlay
  `userConfig <Object>` The configuration object literal containing the configuration that should be set for this Overlay. See configuration documentation for more details.

#### initDefaultConfig

`void initDefaultConfig ( )`
Initializes the class's configurable properties which can be changed using the Panel's Config object (cfg).

#### initEvents

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

#### registerDragDrop

`void registerDragDrop ( )`
Registers the Panel's header for drag & drop capability.

#### removeMask

`void removeMask ( )`
Removes the modality mask.

#### render

`boolean render ( appendToNode )`
Renders the Panel by inserting the elements that are not already in the main Panel into their correct places. Optionally appends the Panel to the specified node prior to the render's execution. NOTE: For Panels 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

Returns: `boolean`
  Success or failure of the render

#### setFirstLastFocusable

`void setFirstLastFocusable ( )`
Sets the firstElement and lastElement instance properties to the first and last focusable elements in the Panel.

#### setTabLoop

`void setTabLoop ( firstElement , lastElement )`
Sets up a tab, shift-tab loop between the first and last elements provided. NOTE: Sets up the preventBackTab and preventTabOut KeyListener instance properties, which are reset everytime this method is invoked.

Parameters:
  `firstElement <HTMLElement>`
  `lastElement <HTMLElement>`

#### showMask

`void showMask ( )`
Shows the modality mask.

#### sizeMask

`void sizeMask ( )`
Sets the size of the modality mask to cover the entire scrollable area of the document

#### sizeUnderlay

`void sizeUnderlay ( )`
Adjusts the size of the shadow based on the size of the element.

#### stackMask

`void stackMask ( )`
Sets the zindex of the mask, if it exists, based on the zindex of the Panel element. The zindex of the mask is set to be one less than the Panel element's zindex.

NOTE: This method will not bump up the zindex of the Panel to ensure that the mask has a non-negative zindex. If you require the mask zindex to be 0 or higher, the zindex of the Panel should be set to a value higher than 0, before this method is called.

#### toString

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

Returns: `String`
  The string representation of the Panel.

#### Methods inherited from YAHOO.widget.Module:

`_addToParent, _createEffects, _initResizeMonitor, _renderBody, _renderFooter, _renderHeader, _supportsCWResize, appendToBody, appendToFooter, appendToHeader, configEffect, configMonitorResize, configVisible, destroy, hide, init, initDefaultConfig, initEvents, initResizeMonitor, onDomResize, render, setBody, setFooter, setHeader, show, toString`

#### Methods inherited from YAHOO.widget.Overlay:

`_alignOnTrigger, _autoFillOnHeightChange, _findTriggerCE, _getComputedHeight, _getConstrainedPos, _getPreciseHeight, _preventOverlap, _primeXYFromDOM, _processTriggers, _setDomVisibility, _validateAutoFillHeight, align, bringToTop, center, configAutoFillHeight, configConstrainToViewport, configContext, configFixedCenter, configHeight, configIframe, configVisible, configWidth, configX, configXY, configY, configzIndex, destroy, doCenterOnDOMEvent, enforceConstraints, fillHeight, fitsInViewport, forceContainerRedraw, getConstrainedX, getConstrainedXY, getConstrainedY, hideIframe, hideMacGeckoScrollbars, init, initDefaultConfig, initEvents, moveTo, onDomResize, showIframe, showMacGeckoScrollbars, stackIframe, syncIframe, syncPosition, toString`

### Events

#### beforeHideMaskEvent

`beforeHideMaskEvent ( )`
CustomEvent fired before the modality mask is hidden. Subscribers can return false to prevent the mask from being hidden

#### beforeShowMaskEvent

`beforeShowMaskEvent ( )`
CustomEvent fired before the modality mask is shown. Subscribers can return false to prevent the mask from being shown

#### dragEvent

`dragEvent ( )`
CustomEvent when the Panel is dragged

#### hideMaskEvent

`hideMaskEvent ( )`
CustomEvent fired after the modality mask is hidden

#### showMaskEvent

`showMaskEvent ( )`
CustomEvent fired after the modality mask is shown

#### Events inherited from YAHOO.widget.Module:

`appendEvent, beforeHideEvent, beforeInitEvent, beforeRenderEvent, beforeShowEvent, changeBodyEvent, changeContentEvent, changeFooterEvent, changeHeaderEvent, destroyEvent, hideEvent, initEvent, renderEvent showEvent YAHOO.widget.Module.textResizeEvent`

#### Events inherited from YAHOO.widget.Overlay:

`beforeMoveEvent, moveEvent, YAHOO.widget.Overlay.windowResizeEvent, YAHOO.widget.Overlay.windowScrollEvent,`

### Configuration Attributes

#### close `- Boolean`

True if the Panel should display a "close" button
Default Value: true

#### draggable `- Boolean`

Boolean specifying if the Panel should be draggable. The default value is "true" if the Drag and Drop utility is included, otherwise it is "false." PLEASE NOTE: There is a known issue in IE 6 (Strict Mode and Quirks Mode) and IE 7 (Quirks Mode) where Panels that either don't have a value set for their "width" configuration property, or their "width" configuration property is set to "auto" will only be draggable by placing the mouse on the text of the Panel's header element. To fix this bug, draggable Panels missing a value for their "width" configuration property, or whose "width" configuration property is set to "auto" will have it set to the value of their root HTML element's offsetWidth before they are made visible. The calculated width is then removed when the Panel is hidden. This fix is only applied to draggable Panels in IE 6 (Strict Mode and Quirks Mode) and IE 7 (Quirks Mode). For more information on this issue see: YUILibrary bugs #1726972 and #1589210.
Default Value: true

#### dragOnly `- Boolean`

Boolean specifying if the draggable Panel should be drag only, not interacting with drop targets on the page.

When set to true, draggable Panels will not check to see if they are over drop targets, or fire the DragDrop events required to support drop target interaction (onDragEnter, onDragOver, onDragOut, onDragDrop etc.). If the Panel is not designed to be dropped on any target elements on the page, then this flag can be set to true to improve performance.

When set to false, all drop target related events will be fired.

The property is set to false by default to maintain backwards compatibility but should be set to true if drop target interaction is not required for the Panel, to improve performance.

Default Value: false

#### keylisteners `- YAHOO.util.KeyListener[]`

A KeyListener (or array of KeyListeners) that will be enabled when the Panel is shown, and disabled when the Panel is hidden.
Default Value: null

#### modal `- Boolean`

True if the Panel should be displayed in a modal fashion, automatically creating a transparent mask over the document that will not be removed until the Panel is dismissed.
Default Value: false

#### strings `- Object`

UI Strings used by the Panel. The strings are inserted into the DOM as HTML, and should be escaped by the implementor if coming from an external source.
Default Value: An object literal with the properties shown below:

close
  HTML : The markup to use as the label for the close icon. Defaults to "Close".

#### underlay `- String`

Sets the type of underlay to display for the Panel. Valid values are "shadow," "matte," and "none". PLEASE NOTE: The creation of the underlay element is deferred until the Panel is initially made visible. For Gecko-based browsers on Mac OS X the underlay elment is always created as it is used as a shim to prevent Aqua scrollbars below a Panel instance from poking through it (See YUILibrary bug #1723530).
Default Value: shadow

#### Configuration attributes inherited from YAHOO.widget.Module:

`appendtodocumentbody, effect monitorresize visible`

#### Configuration attributes inherited from YAHOO.widget.Overlay:

`autofillheight, constraintoviewport, context, fixedcenter, height, iframe preventcontextoverlap width x xy y zIndex`

Copyright © 2011 Yahoo! Inc. All rights reserved.