YUI recommends YUI3.

YUI 2 has been deprecated since 2011. This site acts as an archive for files and documentation.

This documentation is no longer maintained.

YUI 2: Panel

YUI 2: Panel

The Panel control is an extension of Overlay that is meant to behave similarly to an OS window. Unlike true browser popup windows, panels are floating DHTML elements embedded directly within the page context. The Panel control extends the functionality of Overlay, adding support for modality, drag and drop, and close/dismiss buttons. Panel includes a pre-defined stylesheet to support default look and feel characteristics.

Getting Started

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

  1. <!-- Sam Skin CSS -->
  2. <link rel="stylesheet" type="text/css" href="http://yui.yahooapis.com/2.9.0/build/container/assets/skins/sam/container.css">
  3.  
  4. <!-- Dependencies -->
  5. <script src="http://yui.yahooapis.com/2.9.0/build/yahoo-dom-event/yahoo-dom-event.js"></script>
  6.  
  7. <!-- OPTIONAL: Animation (only required if using ContainerEffect) -->
  8. <script src="http://yui.yahooapis.com/2.9.0/build/animation/animation-min.js"></script>
  9.  
  10. <!-- OPTIONAL: Drag & Drop (only required if enabling Drag & Drop) -->
  11. <script src="http://yui.yahooapis.com/2.9.0/build/dragdrop/dragdrop-min.js"></script>
  12.  
  13. <!-- Source file -->
  14. <script src="http://yui.yahooapis.com/2.9.0/build/container/container-min.js"></script>
  15.  
<!-- Sam Skin CSS -->
<link rel="stylesheet" type="text/css" href="http://yui.yahooapis.com/2.9.0/build/container/assets/skins/sam/container.css">
 
<!-- Dependencies -->
<script src="http://yui.yahooapis.com/2.9.0/build/yahoo-dom-event/yahoo-dom-event.js"></script>
 
<!-- OPTIONAL: Animation (only required if using ContainerEffect) -->
<script src="http://yui.yahooapis.com/2.9.0/build/animation/animation-min.js"></script>
 
<!-- OPTIONAL: Drag & Drop (only required if enabling Drag & Drop) -->
<script src="http://yui.yahooapis.com/2.9.0/build/dragdrop/dragdrop-min.js"></script>
 
<!-- Source file -->
<script src="http://yui.yahooapis.com/2.9.0/build/container/container-min.js"></script>
 
Next, apply the yui-skin-sam class name to an element that is a parent of the element in which the Panel Control lives. You can usually accomplish this simply by putting the class on the <body> tag:

  1. <body class="yui-skin-sam">
  2.  
<body class="yui-skin-sam">
 

For more information on skinning YUI components and making use of default skins, see our Understanding YUI Skins article here on the website.

YUI dependency configurator.

YUI Dependency Configurator:

Instead of copying and pasting the filepaths above, try letting the YUI dependency Configurator determine the optimal file list for your desired components; the Configurator uses YUI Loader to write out the full HTML for including the precise files you need for your implementation.

Note: If you wish to include this component via the YUI Loader, its module name is container. (Click here for the full list of module names for YUI Loader.)

Where these files come from: The files included using the text above will be served from Yahoo! servers. JavaScript files are minified, meaning that comments and white space have been removed to make them more efficient to download. To use the full, commented versions or the -debug versions of YUI JavaScript files, please download the library distribution and host the files on your own server.

Order matters: As is the case generally with JavaScript and CSS, order matters; these files should be included in the order specified above. If you include files in the wrong order, errors may result.

Using Panel

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

Panel inherits its constructor and configuration, as well as several other important methods, from Overlay. See Overlay for more information on how to utilize Panel's inherited features.

Defining Panel Markup

HTML markup for Panel uses the same modular format underlying Module. Placing a panel's markup in the page, rather than adding Panel content via script once the Panel instance is created, allows you to use Progressive Enhancement — showing the full content and functionality of your site to users who may have older browsers or who have JavaScript disabled while still providing a richer interaction to modern, standards-compatible browsers. In most cases, you won't place a Panel's content on the page prior to creating the panel; setting content dynamically is the most common use case. However, where it's possible and useful to do so, you may instantiate a Panel based on modular content that follows the following pattern (inherited from Module):

  1. <div id="myPanel">
  2.     <div class="hd"></div>
  3.     <div class="bd"></div>
  4.     <div class="ft"></div>
  5. </div>
  6.  
<div id="myPanel">
    <div class="hd"></div>
    <div class="bd"></div>
    <div class="ft"></div>
</div>
 

Initializing the Panel

Panel is easy to use and can generate extremely powerful interactions with simple configuration options and CSS styling. In its simplest case, a Panel's constructor looks like this:

  1. myPanel = new YAHOO.widget.Panel("myPanel");
  2.  
myPanel = new YAHOO.widget.Panel("myPanel");
 

More often, you'll want to configure some of the properties of Panel by passing in a configuration object as the second argument to your constructor. Configuration options are detailed later in this document; here is an example that implements some very common configurations:

  1. //The second argument passed to the
  2. //constructor is a configuration object:
  3. myPanel = new YAHOO.widget.Panel("win", {
  4.     width: "400px", 
  5.     fixedcenter: true, 
  6.     constraintoviewport: true, 
  7.     underlay: "shadow", 
  8.     close: true, 
  9.     visible: false, 
  10.     draggable: true
  11. });
  12.  
  13. //If we haven't built our panel using existing markup,
  14. //we can set its content via script:
  15.  
  16. myPanel.setHeader("The Panel Control");
  17. myPanel.setBody("The Panel is a powerful UI control
  18.   that enables you to create floating windows without
  19.   using browser popups.  Effects like drag and drop and
  20.   constrain-to-viewport are easy to configure.");
  21.  
  22. //Although we configured many properties in the
  23. //constructor, we can configure more properties or 
  24. //change existing ones after our Panel has been
  25. //instantiated:
  26.  
  27. myPanel.cfg.setProperty("underlay","matte");
  28.  
//The second argument passed to the
//constructor is a configuration object:
myPanel = new YAHOO.widget.Panel("win", {
    width: "400px",
    fixedcenter: true,
    constraintoviewport: true,
    underlay: "shadow",
    close: true,
    visible: false,
    draggable: true
});
 
//If we haven't built our panel using existing markup,
//we can set its content via script:
 
myPanel.setHeader("The Panel Control");
myPanel.setBody("The Panel is a powerful UI control
  that enables you to create floating windows without
  using browser popups.  Effects like drag and drop and
  constrain-to-viewport are easy to configure.");
 
//Although we configured many properties in the
//constructor, we can configure more properties or 
//change existing ones after our Panel has been
//instantiated:
 
myPanel.cfg.setProperty("underlay","matte");
 

For more information about Panel's many configuration options, see Configuration Properties below. For more ideas about how to use Panel and how to customize its look and feel, see the Examples.

Rendering the Panel

Once initialized, a Panel is rendered in the same way as Module, by invoking the render() method. As with Module, if the Panel was not created from markup you need to pass to the render method, the parent element to which the Panel should be added.

Configuration Properties

Panel has the following configuration properties:

Name TypeDefaultDescription
close Boolean null Whether a "close" icon should be displayed in the header.
draggable Boolean "true" if the Drag and Drop utility is included, otherwise "false." Whether to allow the user to drag the Panel using its header.
underlay String "shadow" Specifies the type of underlay to display under the Panel. Other options include "none", and "matte", which renders a small white matte under the Panel.
modal Boolean false Specifies whether the document should be shielded with a partially transparent mask to require the user to close the Panel before being able to activate any elements in the document.

NOTE: When enabling modality, it is strongly recommended that you render the Panel to document.body so that the Panel does not inadvertently have any positioned ancestors which may impact the way the mask, panel and underlying elements are stacked.

For example, if you render a modal Panel inside a relatively positioned ancestor, which doesn't have a z-index, in IE the mask will render on top of the Panel, whereas in all other browsers it will render correctly underneath the Panel unless you control the z-index of the postioned ancestor in relation to the mask.

keylisteners YAHOO.util.KeyListener / Array null A KeyListener or Array of KeyListeners containing key events to enable when the Panel is displayed.

Panel has the following inherited configuration properties:

Name TypeDefaultDescription
visible Boolean true Sets whether or not the Panel is visible on the page (Panel uses the CSS "visibility" property to control this).
effect Object / Object[] none Sets the ContainerEffect (one or many) that should be used when showing and hiding the Panel.
monitorresize Boolean true Configures whether or not to create a hidden off-screen element that can be used to monitor for text size changes in the DOM.
x Number null Sets the element's page X co-orinate.
y Number null Sets the element's page Y co-ordinate.
xy Array null Sets the element's page XY co-ordinate.
context Array null Allows the Overlay to be aligned relative to a context element. The property expects an array value with the format: [contextElementOrId, overlayCorner, contextElementCorner], where "contextElementOrId" is the context element or the id of the context element.

The corner parameters are one of the following string values: "tr" (top right), "tl" (top left), "br" (bottom right), or "bl" (bottom left) and define which corners of the overlay and context element should be aligned.

The array also supports optional 4th and 5th entries.

The 4th entry is an optional array of event names, or Custom Event objects, which should trigger re-alignment of the Overlay with the currently configured context element. For example:

[contextId, overlayCorner, contextCorner, ["beforeShow", "windowResize"]]

Will re-align the Overlay to the context element just before it's shown, and whenever the window is resized.

The 5th entry is an optional XY pixel offset, which is to be applied after the Overlay is aligned to the specified corner of the context element, and can be used to add a pixel buffer between the context element and the Overlay. For example:

[contextId, overlayCorner, contextCorner, triggerEvents, [10, 20]]

Will offset the Overlay by 10 pixels along the X axis, and 20 pixels along the Y axis, after aligning the specified corners.
fixedcenter Boolean false Specifies whether the Overlay should be automatically centered in the viewport on window scroll and resize.
width String null Sets the element's "width" style property.
height String null Sets the element's "height" style property.
zIndex Number null Sets the element's "z-index" style property.
constraintoviewport Boolean false If set to true the Overlay will try to remain inside the confines of the size of viewport.
iframe Boolean false (true by default for IE 6 and below) If set to true the Menu will have and iframe behind it to prevent other elements with a higher z-index from poking through.
autofillheight String "body" Which container element (header, body or footer) should be sized to fill out any remaining vertical space when a height is set on the container using the height configuration property. Supported values are "header", "body" and "footer". Can be set to null (or false) to turn off the feature.

Support & Community

The YUI Library and related topics are discussed on the on the YUILibrary.com forums.

Also be sure to check out 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 YUILibrary.com site. Before filing new feature requests or bug reports, please review our reporting guidelines.

Panel Control Cheat Sheet:

Cheat Sheet for Panel Control.

Download full set of cheat sheets.

Container Family Examples:

Other YUI Examples That Make Use of the Container Family:

More Reading about the YUI Panel Control:

YUI Panel on del.icio.us:

Copyright © 2013 Yahoo! Inc. All rights reserved.

Privacy Policy - Copyright Policy - Job Openings