index.mustache revision 1b94590fd02ca19669dfb4b5deb563a290459d81
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra<div class="intro">
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra <p>Overlay is a positionable and stackable widget, which also provides support for the standard module format layout, with a header, body and footer section.
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra <p>The overlay is built by extending the <a href="{{apiDocs}}/Widget.html">`Widget`</a> class and adding the <a href="{{apiDocs}}/WidgetPosition.html">`WidgetPosition`</a>, <a href="{{apiDocs}}/WidgetStack.html">`WidgetStack`</a>, <a href="{{apiDocs}}/WidgetPositionAlign.html">`WidgetPositionAlign`</a>, <a href="{{apiDocs}}/WidgetPositionConstrain.html">`WidgetPositionConstrain`</a> and <a href="{{apiDocs}}/WidgetStdMod.html">`WidgetStdMod`</a> extensions,
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra and doesn't actually need to add any implementation code of its own. The <a href="../examples/widget/widget-build.html">"Creating Custom Widget Classes"</a> example shows how you can use these extensions to build classes which mix and match some of the above features.</p>
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra{{>getting-started}}
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra<h2 id="using">Using Overlay</h2>
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra<h3 id="instantiating">Instantiating The Overlay</h3>
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra<p>The Overlay widget extends the `Widget` class, and hence the Overlay constructor follows the same pattern as any Widget constructor, accepting a configuration object to set the initial configuration for the widget.</p>
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra<h4>Instantiating From Markup: Progressive Enhancement</h4>
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra<p>The overlay can be instantiated from markup, by specifying the `srcNode` which contains the header, body and footer content for the overlay:</p>
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra<div id="myContent">
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra <div class="yui3-widget-hd">Overlay Header</div>
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra <div class="yui3-widget-bd">Overlay Body</div>
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra <div class="yui3-widget-ft">Overlay Footer</div>
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra<p>The header, body and footer sections provided in markup need to be marked with the class name which `Overlay` (or more accurately, `WidgetStdMod`) expects for the section ("yui3-widget-hd", "yui3-widget-bd" and "yui3-widget-ft") as shown above.
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo MitraAll of these sections are optional. If content is set via the API at a later point the corresponding section will be created dynamically.</p>
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra<p>When instantiating from markup, a reference to the `srcNode` is provided in the configuration object. This reference can be a node reference, or a selector string which can be used to identify the node. If the selector string is too broad (returns multiple nodes), the first node found will be used.
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo MitraThe following code targets the markup shown above:</p>
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo MitraYUI({...}).use("overlay", function(Y) {
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra var overlay = new Y.Overlay({
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra // Specify a reference to a node which already exists
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra // on the page and contains header/body/footer content
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra srcNode:"#myContent",
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra // Also set some of the attributes inherited from
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra // the base Widget class.
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra visible:false,
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra width:"20em"
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra<p>Following instantiation, a call to `render` is required to have the Overlay's state reflected in the DOM, as with all YUI 3 widgets:</p>
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitravar overlay = new Y.Overlay({ ... });
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra<p>Note that you could set the state of the Overlay multiple times (modifying content, changing dimensions etc.) before rendering.
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo MitraWhen the `render` method is invoked, the state of the Overlay at that point in time will be reflected in the DOM.</p>
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra<p>When `render` is invoked, the overlay's content box will be wrapped by the bounding box (another DIV), to provide the <a href="../widget/index.html#markup">nested box structure</a> common to all widgets.</p>
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra<h4>Instantiating From Script</h4>
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra<p>You can also create Overlay instances entirely from script, setting content programmatically, using the `headerContent`, `bodyContent` and `footerContent` attributes.</p>
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitravar overlay = new Y.Overlay({
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra headerContent:"My Overlay Header",
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra bodyContent:"My Overlay Body",
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra footerContent:"My Footer Content",
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitraoverlay.render("#parentNode");
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra<p>Content can be strings containing markup (innerHTML will be used to set the content), or `Node` references, in which case they will be appended to the section (header, body or footer) node.</p>
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra<p>The `render` method can be passed a node reference (or a selector string) as shown above, to specify the node
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitraunder which the overlay's bounding box should be added to the DOM. When rendering an overlay instance which has not been created from markup
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra(so it does not have a position in the DOM) if this argument is not provided the overlay will be added to the document's body element (inserted as the first child to avoid the potential for "operation aborted" errors in IE6).
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra<h3 id="attributes">Attributes</h3>
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra<p>Overlay adds the following key attributes (through the extensions mentioned above), in addition to the attributes provided by the base <a href="../widget/index.html#attributes">Widget</a> class:</p>
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra <tr><th>Attribute</th><th>Description</th></tr>
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra <tr><td>`x`, `y` and `xy`</td><td>Positioning attributes, to set the XY position in page coordinates on the Overlay's bounding box. Set to [0,0] by default</td></tr>
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra <tr><td>`zIndex`</td><td>Sets the z-index on the Overlay's bounding box. Set to 0 by default.</td></tr>
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra <tr><td>`shim`</td><td>Boolean, indicating whether or not an iframe shim should be added to the Overlay to protect against select box bleed through. It is only enabled by default for IE6.</td></tr>
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra <tr><td>`align`</td><td>Used to align a specific point on the Overlay's bounding box to a specific point on another node, or the viewport. Set to null by default.</td></tr>
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra <tr><td>`centered`</td><td>Used to center the Overlay inside another node, or inside the viewport. Set to false by default.</td></tr>
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra <tr><td>`constrain`</td><td>Used to specify a node to constrain the Overlay to, when setting the XY position. Can also be set to true, to constrain to the viewport. Set to false by default.</td></tr>
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra <tr><td>`headerContent`</td><td>Used to set the content of the Overlay's header section. No default value set.</td></tr>
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra <tr><td>`bodyContent`</td><td>Used to set the content of the Overlay's body section. No default value set.</td></tr>
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra <tr><td>`footerContent`</td><td>Used to set the content of the Overlay's footer section. No default value set.</td></tr>
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra <tr><td>`fillHeight`</td><td>Specifies which of the 3 sections - header, body or footer, should be automatically sized to fill out the height of the Overlay if a fixed height has been set. Set to WidgetStdMod.BODY by default. Can be disabled by setting to null.</td></tr>
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra<h3 id="positioning">Positioning</h3>
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra<h4>Basic XY Positioning</h4>
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra<p>Overlay provides basic XY positioning support through its `x`, `y` and `xy` attributes as well as a convenience `move` method which wraps the `xy` attribute.</p>
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra<p>The xy position of the overlay can be set in the constructor, as with any attribute value:</p>
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitravar overlay = new Y.Overlay({
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra srcNode:"#myContent",
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra xy: [200,100]
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitravar overlay = new Y.Overlay({
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra srcNode:"#myContent",
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitravar overlay = new Y.Overlay({
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra srcNode:"#myContent",
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra x: 200 // y defaults to 0
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra<p>The overlay's default position, if xy values are not provided, will be 0,0. Note that xy are page coordinates, not relative coordinates.</p>
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra<p>Changes in the overlay's position, when set programmatically through the API, can be monitored by listening for the attribute `xyChange` event. Listeners
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitrato this event will receive an event facade, which contains previous and new xy values:</p>
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra// Listen to the "on" moment, if you're interested in
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra// preventing the change in position from occurring.
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitraoverlay.on("xyChange", function(e) {
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra var currPosition = e.prevVal;
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra var newPosition = e.newVal;
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra if (newPosition[0] > MAX_X || newPosition[1] > MAX_Y) {
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra // Stop move from occurring.
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra// Listen to the "after" moment, if you're just interested
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra// in being notified when the position has been changed.
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitraoverlay.after("xyChange", function(e) {
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra var position = e.newVal;
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra console.log("Overlay has been moved to: " + position[0] + "," position[1]);
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra<p>Note that changing just the `x` or `y` attribute value, individually, will still fire the `xy` change event. The `x` and
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra`y` attribute values are simply convenience wrappers which end up setting the `xy` attribute.</p>
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra<p>XY position can also be set after construction, as with any attribute, using `set` to change the attribute value directly, or using the `move` method:</p>
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitraoverlay.set("xy", [100,200]);
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra<p>The <a href="../examples/overlay/overlay-xy.html">Basic XY Positioning</a> example shows basic positioning in action.</p>
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra<h4>Extended XY Positioning</h4>
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra<p>Overlay also provides support to help position it relative to another node on the page, or the viewport, through the `align` and `centered` attributes, as well as
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitrathe corresponding `align()` and `centered()` convenience methods, through the application of the `WidgetPositionAlign` extension.</p>
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra<p>The `align` attribute accepts as a value an object literal with the following properties:</p>
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra <dt>node</dt>
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra The node to which the Widget is to be aligned. If set to null, or not provided, the Overlay is aligned to the viewport
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra <dt>points</dt>
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra A two element array, defining the two points on the Overlay and node which are to be aligned. The first element is the point on the Overlay, and the second element is the point on the node (or viewport).
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra Supported alignment points are defined as static properties on <a href="{{apiDocs}}/WidgetPositionAlign.html#property_WidgetPostionAlign.TL">`WidgetPositionAlign`</a>. For example:
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra `[Y.WidgetPositionAlign.TR, Y.WidgetPositionAlign.TL]` aligns the Top-Right corner of the Overlay with the
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra Top-Left corner of the node/viewport, and `[Y.WidgetPositionAlign.CC, Y.WidgetPositionAlign.TC]` aligns the Center of the
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra Overlay with the Top-Center edge of the node/viewport.
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra// Align the:
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra// top-left corner of the overlay, with the
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra// top-right corner of the node with id = "okBtn"
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra node:"#okBtn",
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra points:[Y.WidgetPositionAlign.TL, Y.WidgetPositionAlign.TR]
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra// Align the:
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra// right-center edge of the overlay, with the
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra// right-center edge of the viewport (no node specified)
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra points:[Y.WidgetPositionAlign.RC, Y.WidgetPositionAlign.RC]
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra// Align the:
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra// center of the overlay, with the
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra// top-left corner of the node with id = "okBtn"
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitraoverlay.align("#okBtn", [Y.WidgetPositionAlign.CC, Y.WidgetPositionAlign.TL]);
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra<p>The `centered` property can either by set to `true` to center the Overlay in the viewport, or set to a selector string or node reference to center the Overlay in a particular node.</p>
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra// Center the overlay in the node with id = "module"
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitraoverlay.set("centered", "#module");
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra// Center the overlay in the viewport
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitraoverlay.set("centered", true);
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra<p>The <a href="../examples/overlay/overlay-align.html">"Alignment Support"</a> example shows aligned positioning support in action.</p>
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra<p>Note that currently alignment/centering is not maintained when the viewport is scrolled, window resized etc. Support to re-align the overlay on a default and custom set of trigger events will be
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitraprovided in a future release.</p>
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra<p>In addition to being able to align the overlay to a given element (or the viewport), overlay also supports the ability to constrain its XY position to a given node, or to the viewport.</p>
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra// Constrains the XY position to a given node:
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitraoverlay.set("constrain", "#constrainingNode");
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra// Or to the viewport
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitraoverlay.set("constrain", true);
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra<p>The <a href="../examples/overlay/overlay-constrain.html">"Constrain Support"</a> example shows constrained positioning in action.</p>
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra<h3 id="stacking">Stacking</h3>
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo MitraThe Overlay provides basic stacking support in the form of a `zIndex` attribute and a `shim` attribute. The shimming support protects against <select> box bleed through on
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo MitraIE6 (It is enabled by default for IE6) by adding an iframe shim to the overlay's bounding box (positioned underneath the content box). The default value of the `zIndex` attribute is 0.</p>
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra<p>Using the `zIndex` and `shim` attributes is the same as any other attribute, with the ability to set values in the constructor, or at a later point in time:</p>
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra// Disable shim for all browsers, set zIndex to 10
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitravar overlay = new Y.Overlay({
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra shim:false, // Disable for all browsers, including IE6
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra// Set zIndex to 10. Shim is enabled for IE6 but disabled for all
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra// other browsers (default value)
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitravar overlay = new Y.Overlay({
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra<p>The <a href="../examples/overlay/overlay-stack.html">"Stack Support"</a> example creates a simple "bringToTop" implementation based on the `zIndex` attribute.
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo MitraThis support will be provided as part of Overlay itself (or more precisely, as part of `WidgetStack`) in a future release.</p>
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra<h3 id="content">Setting Section Content</h3>
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra<p>Overlay uses the standard module format for its rendering. It provides a header, body and footer section as described above (through the `WidgetStdMod` extension).</p>
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra<h4>Replacing Content</h4>
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra<p>The content for each of these sections is settable either through the `headerContent`, `bodyContent` and `footerContent` attributes. Setting the content
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitrathrough these properties will replace any existing content in the section. The content can either be specified as a string, in which case innerHTML will be used to set the new content, or
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitraspecified as a `Node` instance, in which case the content will be added to the respective section using `appendChild` after clearing existing content.</p>
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitravar overlay = new Y.Overlay({
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra headerContent: '<span class="title">My Header Content</span>',
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra bodyContent: '<div class="mod">My Body Content</div>'
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra // Don't want a footer
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitraoverlay.set("headerContent", '<span class="title">My Header Content</span>');
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitravar headerContent = Y.Node.create("<span></span>");
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo MitraheaderContent.set("innerHTML", "My Header Content");
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitraoverlay.set("headerContent", headerContent);
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra<p>Overlay will not create the section if there has been no content set for it. (So, for example, the overlay above will not have a footer section). Also, if the section doesn't exist it will be created,
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitrathe first time content is set for it.</p>
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra<p>As with any attribute change, you can listen for (and prevent) changes in content by listening for the corresponding attribute change event:</p>
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitraoverlay.on("bodyContentChange", function(e) {
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra if (someCondition) {
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra // Don't allow body content to be updated
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitraoverlay.after("bodyContentChange", function(e) {
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra // body section has been modified
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra<p>Setting content in any of the sections will fire Widget's `contentUpdate` event, which can be monitored if you want to be notified of changes to any section. However, this event is purely a catch-all notification
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitraevent. It cannot be prevented to stop the content change from occurring:</p>
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitraoverlay.after("contentUpdate", function(e) {
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra // Content has been updated in one of the standard module sections.
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra<p>Setting content using the attributes mentioned above always results in content being replaced. If you need to insert content before, or append content after existing content in the section, you can use the `setStdModContent(section, content, where)` method Overlay provides:</p>
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra "New Content To Insert", // Content
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra "New Content To Append", // Content
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra <li>The `section` argument specifies which section is to be updated. The constants `WidgetStdMod.HEADER`, `WidgetStdMod.BODY` and `WidgetStdMod.FOOTER` define valid values.</li>
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra <li>The `content` argument specifies the new content to be added which, as with the attributes, can be a string HTML value or a node reference.</li>
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra <li>The `where` argument specifies whether the content should be added before, after, or replace existing content. The constants `WidgetStdMod.BEFORE`, `WidgetStdMod.AFTER` and `WidgetStdMod.REPLACE`</p> define valid values.</li>
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra<p><em>Note, the above `WidgetStdMod` constants define the set of valid values wherever the API expects a "section" or "where" argument.</em></p>
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra<p>The content change events mentioned above, will be fired when content is set through the `setStdModContent` method just as they would when setting the content using the attribute.</p>
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra<p>The <a href="../examples/overlay/overlay-stdmod.html">Standard Module</a> example provides a way to exercise the above content attributes and methods.</p>
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra<h3 id="markup">Markup Structure</h3>
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra<p>The final rendered Overlay has the markup structure shown below:</p>
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra<div class="yui3-widget yui3-overlay yui3-widget-positioned yui3-widget-stacked">
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra <!--Bounding Box-->
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra <div class="yui3-overlay-content yui3-widget-stdmod">
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra <!--Content Box-->
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra <div class="yui3-widget-hd">Overlay Header Content</div>
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra <!--Header Section-->
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra <div class="yui3-widget-bd">Overlay Body Content</div>
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra <!--Body Section-->
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra <div class="yui3-widget-ft">Overlay Footer Content</div>
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra <!--Footer Section-->
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra <iframe class="yui3-widget-shim"></iframe>
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra <!-- Stacking shim, if enabled-->
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra<p>The bounding box is absolutely positioned by default, and top/left positioning and z-index values are applied to it. The nested bounding box/content box structure is discussed in detail on the <a href="../widget/index.html#markup">Widget markup discussion</a>.</p>
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra<p>In addition to the default classes applied to the bounding box and content box for all widgets ("yui3-overlay", "yui3-overlay-content", "yui3-widget"), the `WidgetStdMod`, `WidgetPositioned` and `WidgetStack` extensions also mark the appropriate boxes with
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra"yui3-widget-stdmod", "yui3-widget-positioned" and "yui3-widget-stacked" classes as shown above.</p>
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra<p>The iframe shim, added if `shim` is enabled, is added to the bounding box, as sibling to the content box and stacked underneath it (using a -ve z-index).</p>
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra<h3 id="css">CSS</h3>
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra<p>Overlay is a generic, foundation widget and doesn't ship with a default look/feel out of the box. Its Sam Skin (build/overlay/assets/skins/sam/overlay.css) implementation consists only of core functional rules, to control how it is positioned and how it is hidden:</p>
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra.yui3-overlay {
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra position:absolute;
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra.yui3-overlay-hidden {
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra visibility:hidden
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra<p>Since it includes the `WidgetStack` extension, the following functional CSS is also provided (through build/widget/assets/skins/sam/widget-stack.css) to handle the shim element,
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra(along with the Gecko/Mac scroll bar support CSS mentioned above)</p>
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra.yui3-widget-stacked .yui3-widget-shim {
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra filter: alpha(opacity=0);
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra position: absolute;
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra border: none;
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra z-index: -1;
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra width: 100%;
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra height: 100%;
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra We'll be setting these programmatically for IE6,
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra to account for cases where height is not set