Getting Started

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

<!-- Sam Skin CSS --> <link rel="stylesheet" type="text/css" href="http://yui.yahooapis.com/2.5.1/build/container/assets/skins/sam/container.css"> <!-- Dependencies --> <script type="text/javascript" src="http://yui.yahooapis.com/2.5.1/build/yahoo-dom-event/yahoo-dom-event.js"></script> <!-- OPTIONAL: Animation (only required if enabling Animation) --> <script type="text/javascript" src="http://yui.yahooapis.com/2.5.1/build/animation/animation-min.js"></script> <!-- Source file --> <script type="text/javascript" src="http://yui.yahooapis.com/2.5.1/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:

<!-- If not using Tooltip, Panel, Dialog, or SimpleDialog: --> <script type="text/javascript" src="http://yui.yahooapis.com/2.5.1/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.

Using Overlay

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

• Defining Overlay Markup
• Initializing Overlay
• Positioning the Overlay
• Stacking the Overlay
• Rendering the Overlay
• Configuration Properties

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:

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

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:

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

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

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

// 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");

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:

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

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

Overlay inherits the following properties:

Support & Community

The YUI Library and related topics are discussed on the on the ydn-javascript mailing list.

In addition, please visit the 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 YUI SourceForge project site. Before filing new feature requests or bug reports, please review our reporting guidelines.

• Guidelines for YUI feature requests and bug reports.
• Review current bug list or file a new bug.
• Review current feature requests or file a new feature request.