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: Overlay

YUI 2: Overlay

The Overlay control is an extension of Module; its role is to facilitate the creation of modular content that is absolutely positioned above the flow of a page. It adds additional functionality to Module, including methods for positioning, multiple custom events for monitoring internal property changes, and a built-in IFRAME solution for dealing with SELECT element bleed-through in Internet Explorer.

Note: Overlay is a building block for other UI controls and does not in and of itself solve a particular interaction problem; if you're looking for a specific implementation of Overlay, check out the Tooltip, Panel, Dialog and SimpleDialog controls.

Getting Started

To use Overlay, 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. <!-- Source file -->
  11. <script src="http://yui.yahooapis.com/2.9.0/build/container/container-min.js"></script>
  12.  
<!-- 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>
 
<!-- Source file -->
<script src="http://yui.yahooapis.com/2.9.0/build/container/container-min.js"></script>
 

If you are not using Tooltip, Panel, Dialog, or SimpleDialog, you may substitute container-min.js with the smaller container_core-min.js file:

  1. <!-- If not using Tooltip, Panel, Dialog, or SimpleDialog: -->
  2. <script src="http://yui.yahooapis.com/2.9.0/build/container/container_core-min.js"></script>
  3.  
<!-- If not using Tooltip, Panel, Dialog, or SimpleDialog: -->
<script src="http://yui.yahooapis.com/2.9.0/build/container/container_core-min.js"></script>
 

Note that a CSS file is not required if you're only using container_core-min.js, however for the Overlay to operate as designed, it does need to be positioned absolutely. The yui-overlay class applied to all overlays can be used to define your own rule to apply position:absolute for all overlays. Alternatively you could include the container.css file mentioned above, but since it only has a single rule which applies to Overlays, it's overkill if you're aiming to optimize the amount of code required for your page.

Next, apply the yui-skin-sam class name to an element that is a parent of the element in which the Overlay 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 Overlay

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

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

Defining Overlay Markup

In its most basic form, the HTML markup for an Overlay looks like this:

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

Initializing Overlay

To instantiate an Overlay around a pre-existing piece of markup (as exemplified above), simply pass the id of your modular content to the Overlay constructor: 

  1. var myOverlay = new YAHOO.widget.Overlay("myOverlay");
  2.  
var myOverlay = new YAHOO.widget.Overlay("myOverlay");
 

Positioning the Overlay

Overlay has several useful methods that can be used to position the Overlay, by either specifying specific pixel coordinates, or using special methods for contextually aligning or centering the Overlay.

To position an Overlay using pixel coordinates, use the x, y, or xy properties:

  1. // Set the x position
  2. myOverlay.cfg.setProperty("x", 100);
  3. // Set the y positon
  4. myOverlay.cfg.setProperty("y", 200);
  5. // Set the x and y positions simultaneously
  6. myOverlay.cfg.setProperty("xy", [100,200]);
  7.  
// Set the x position
myOverlay.cfg.setProperty("x", 100);
// Set the y positon
myOverlay.cfg.setProperty("y", 200);
// Set the x and y positions simultaneously
myOverlay.cfg.setProperty("xy", [100,200]);
 

To center an Overlay manually, you can call its center() method:

  1. // Center the Overlay
  2. myOverlay.center();
  3.  
// Center the Overlay
myOverlay.center();
 

An alternative to manually centering the Overlay is to set its fixedcenter property to always keep the Overlay centered in the viewport:

  1. // Center the Overlay
  2. myOverlay.cfg.setProperty("fixedcenter", true);
  3.  
// Center the Overlay
myOverlay.cfg.setProperty("fixedcenter", true);
 

To align an Overlay to another element on the page contextually, you can set the context property:

  1. // This call says that myOverlay's top right corner should be snapped to "myContextEl"'s top left corner.
  2. myOverlay.cfg.setProperty("context", ["myContextEl", "tr", "tl"]);
  3. // To change the alignment later, you can also call "align" once the context property has already been set.
  4. // This call will change the alignment so that myOverlay's top right corner is snapped to "myContextEl"'s bottom left corner.
  5. myOverlay.align("tr", "bl"); 
  6.  
// This call says that myOverlay's top right corner should be snapped to "myContextEl"'s top left corner.
myOverlay.cfg.setProperty("context", ["myContextEl", "tr", "tl"]);
// To change the alignment later, you can also call "align" once the context property has already been set.
// This call will change the alignment so that myOverlay's top right corner is snapped to "myContextEl"'s bottom left corner.
myOverlay.align("tr", "bl");
 

Context based alignment by default is a one time operation - the Overlay will be aligned to the context element once, when the property is set (or, if the developer calls Overlay's align() method as shown above). For example, unlike the fixedcenter property which repositions the Overlay when the window is resized or scrolled, context does not realign the Overlay with the context element in response to windowScroll or windowResize events. This is because in most use cases, the page co-ordinates of the context element remains unchanged when the user scrolls or resizes the window.

However if the layout of your page could result in the page co-orindates of the context element being modified (e.g. in fluid layouts), you can provide an optional list of events which should trigger context element re-alignment as shown below: 

  1. // myOverlay's top right corner should be snapped to "myContextEl"'s top left corner, and we should realign just before the Overlay is shown, or whenever the window is resized:
  2. myOverlay.cfg.setProperty("context", ["myContextEl", "tr", "tl", ["beforeShow", "windowResize"]]);
  3.  
// myOverlay's top right corner should be snapped to "myContextEl"'s top left corner, and we should realign just before the Overlay is shown, or whenever the window is resized:
myOverlay.cfg.setProperty("context", ["myContextEl", "tr", "tl", ["beforeShow", "windowResize"]]);
 

Rendering the Overlay

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

Stacking the Overlay

One piece of core functionality provided by Overlay is support for a zIndex configuration property that enables it to be stacked above other elements on the page. The zIndex configuration property is an interface for setting the CSS z-index property, and understanding how the browser handles z-index values is therefore an important part of using the Overlay control and its subclasses.

A commonly asked question when working with Overlays is "Why is my Overlay rendered under DIV X, even though DIV X has a z-index of 10, and I've set the z-index of my Overlay to 9999?". Understanding stacking contexts will help you answer this question.

Understanding z-index and stacking contexts

Relatively and absolutely positioned elements can overlap other elements on the page. In situations where elements overlap, the browser uses the CSS z-index property to determine how overlapping elements are stacked on top of each other along the z-axis: Generally speaking elements with higher z-indices are rendered above elements with lower z-indices.

Consider the following simple markup structure:

  1. <body>
  2.     <!-- DIV A and B are statically positioned, DIV A1, B1 are absolutely positioned -->
  3.     <div id="A">
  4.         <div id="A1" style="position:absolute;z-index:20;">A1, z-index = 20</div>
  5.     </div>
  6.  
  7.     <div id="B">
  8.         <div id="B1" style="position:absolute;z-index:10;">B1, z-index = 10</div>
  9.     </div>
  10. </body>
  11.  
<body>
    <!-- DIV A and B are statically positioned, DIV A1, B1 are absolutely positioned -->
    <div id="A">
        <div id="A1" style="position:absolute;z-index:20;">A1, z-index = 20</div>
    </div>
 
    <div id="B">
        <div id="B1" style="position:absolute;z-index:10;">B1, z-index = 10</div>
    </div>
</body>
 

In the example above, DIV A1 would be rendered on top of DIV B1 if they were to overlap. DIV A1 and DIV B1 both have the same stacking context, the root or body element, and are stacked relative to each other within this context based on their z-index values.

However, if DIV A and DIV B are either relatively or absolutely positioned, the scenario changes: 

  1. <body>
  2.     <!-- DIV A and B are now relatively positioned -->
  3.     <div id="A" style="position:relative; z-index:1">
  4.         <div id="A1" style="position:absolute;z-index:20;">A1, z-index = 20</div>
  5.     </div>
  6.     <div id="B" style="position:relative; z-index:2">
  7.         <div id="B1" style="position:absolute;z-index:10;">B1, z-index = 10</div>
  8.     </div>
  9. </body>
  10.  
<body>
    <!-- DIV A and B are now relatively positioned -->
    <div id="A" style="position:relative; z-index:1">
        <div id="A1" style="position:absolute;z-index:20;">A1, z-index = 20</div>
    </div>
    <div id="B" style="position:relative; z-index:2">
        <div id="B1" style="position:absolute;z-index:10;">B1, z-index = 10</div>
    </div>
</body>
 

DIV B1 (z-index=10) will be rendered on top of DIV A1 (z-index=20), even though it has a lower z-index.

With different, positioned, parent elements, DIV A1 and DIV B1 no longer share a stacking context. As per the W3C layering spec, DIV A and DIV B establish stacking contexts since they are relatively positioned AND have a z-index defined. Therefore, when determining how to stack the elements the browser doesn't compare their z-index values relative to each other, but rather to other elements in the stacking contexts established by their separate parent elements.

Additionally, since DIV A and DIV B share a stacking context (body), they are stacked so that DIV B (z-index=2) is placed above DIV A (z-index=1), based on their z-index values. Furthermore, any elements which are children of DIV A will always be below DIV B and any of its children. No matter how high or low the z-indices of DIV A1 and DIV B1 are set, DIV B1 will always stack above DIV A1, because DIV B is stacked above DIV A.

As mentioned above, positioned elements with a specified z-index will establish new stacking contexts for their child nodes. This is true for all A-Grade browsers. However in IE even positioned elements that lack a defined z-index establish a new stacking context. This is considered to be an IE bug.

To completely avoid the potential impact of ancestor elements establishing new stacking contexts, render Overlays into the document's <body> element. Doing so will gaurantee that all Overlay instances exist within the same stacking context, making it easier to manage how they are stacked above all other elements in the page.

Configuration Properties

Overlay has the following configuration properties, which it passes on to all of its subclasses through inheritance:

Name TypeDefaultDescription
x Number null Sets the element's page X co-ordinate.
y Number null Sets the element's page Y co-ordinate.
xy Array null Sets the element's page XY co-ordinates.
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.
effect Object / Object[] none Sets the ContainerEffect (one or many) that should be used when showing and hiding the Overlay.
fixedcenter Boolean / String false

Specifies whether the Overlay should be automatically centered in the viewport on window scroll and resize.

It also supports the string value "contained", which will enable fixed center behavior, but only if the Overlay fits within the viewport. If the Overlay is larger than the viewport, automatic fixed centering will be disabled until the viewport is large enough to contain the Overlay.

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 Overlay 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.

Overlay inherits the following properties:

Name Type Default Description
visible Boolean true Sets whether or not the Overlay is visible on the page (Overlay uses the CSS "visibility" property to control this).
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.

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.

Container Family Examples:

Other YUI Examples That Make Use of the Container Family:

More Reading about the YUI Overlay Control:

YUI Overlay on del.icio.us:

bookmark on del.icio.us

be the first to bookmark this page!

Copyright © 2013 Yahoo! Inc. All rights reserved.

Privacy Policy - Copyright Policy - Job Openings