Getting Started

We provide two separate builds of Container: One build (continer_core.js) includes just the two foundation classes, Module and Overlay, and a second, larger build (container.js) contains the entire Container family, including the four controls based on Module and Overlay: Tooltip, Panel, Dialog and SimpleDialog. You can optimize your use of the Container family by understanding the Container object model and using the correct build in your page:

To use the Container family of components, include the following source code in your web page:

<!-- 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> <!-- OPTIONAL: Connection (only required if using Dialog/SimpleDialog) --> <script type="text/javascript" src="http://yui.yahooapis.com/2.5.1/build/connection/connection-min.js"></script> <!-- OPTIONAL: Drag & Drop (only required if enabling Drag & Drop for Panel/Dialog/SimpleDialog) --> <script type="text/javascript" src="http://yui.yahooapis.com/2.5.1/build/dragdrop/dragdrop-min.js"></script> <!-- OPTIONAL: YUI Button (only required if using Dialog/SimpleDialog with YUI Buttons) --> <!-- You only need to include element and button if you're using Dialog or SimpleDialog and want the Dialog or SimpleDialog to use YUI Buttons, instead of HTML Buttons --> <script type="text/javascript" src="http://yui.yahooapis.com/2.5.1/build/element/element-beta-min.js"></script> <script type="text/javascript" src="http://yui.yahooapis.com/2.5.1/build/button/button-min.js"></script> <!-- Source file --> <script type="text/javascript" src="http://yui.yahooapis.com/2.5.1/build/container/container-min.js"></script>

And the following CSS files:

<!-- Sam Skin CSS --> <link rel="stylesheet" type="text/css" href="http://yui.yahooapis.com/2.5.1/build/container/assets/skins/sam/container.css"> <!-- OPTIONAL: You only need the YUI Button CSS if you're including the Button script fille, mentioned above. --> <link rel="stylesheet" type="text/css" href="http://yui.yahooapis.com/2.5.1/build/button/assets/skins/sam/button.css">

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.

Container Object Model

Known Issues

• "Sam" skin Panel missing left and right borders when declared with a height

  If the height of a Panel instance exceeds the total height of its header, body and footer elements, the space not filled with content will lack a left and right border. Therefore, to set a Panel instance to a fixed height when using the "Sam" skin, apply the desired height to the body element, taking into account the height of the header and footer elements. To set the height of a Panel instance's body via CSS:

  #mypanel .bd { height: 100px; }

  Or via JavaScript:

  oMyPanel.body.style.height = "100px";

• Elements with scrollbars poke through Overlay instances floating above them

  There is a bug in Gecko-based browsers for Mac OS X where an element's scrollbars will poke through absolutely positioned elements floating above them. To fix this problem the "overflow" property of an Overlay instance's root element is toggled between "hidden" and "auto" (through the application and removal of the "hide-scrollbars" and "show-scrollbars" CSS classes) as its "visibility" configuration property is toggled between "false" and "true."

  PLEASE NOTE:

  1. The "hide-scrollbars" and "show-scrollbars" CSS classes classes are applied only for Gecko on Mac OS X and are added/removed to/from the Overlay's root HTML element (DIV) via the "hideMacGeckoScrollbars" and "showMacGeckoScrollbars" methods of YAHOO.widget.Overlay.
  2. For Panel (and its subclasses) it is the underlay element, not the root element, whose "overflow" property is toggled between "hidden" and "auto." The underlay element therefore acts as a shim to correct the scrollbar problem.
  3. For Tooltip instances using the "Sam" skin it is the shadow element, not the root element, whose "overflow" property is toggled between "hidden" and "auto." The shadow element therefore acts as a shim to correct the scrollbar problem.
  4. Once the fix is applied the bug will reappear if the window loses focus. This can be remedied via Javascript by hiding and showing the Overlay instance when the window receives focus: YAHOO.util.Event.on(window, "focus", function () { oMyOverlay.hide(); oMyOverlay.show(); });
  For more information see the Mozilla bug report for this issue.

• Scrollbars remain visible after an Overlay is hidden

  There is a bug in Gecko-based browsers for Mac OS X where an element's scrollbars and the scrollbars of its child nodes remain visible when its "visibility" property property is set to "hidden." To fix this problem, the "overflow" property of an Overlay instance's root element and child nodes is toggled between "hidden" and "auto" (through the application and removal of the "hide-scrollbars" and "show-scrollbars" CSS classes) as its "visibility" configuration property is toggled between "false" and "true."

  PLEASE NOTE:

  1. The "hide-scrollbars" and "show-scrollbars" CSS classes classes are applied only for Gecko on Mac OS X and are added/removed to/from the Overlay's root HTML element (DIV) via the "hideMacGeckoScrollbars" and "showMacGeckoScrollbars" methods of YAHOO.widget.Overlay.
  2. There may be instances where the CSS for a web page or application contains style rules whose specificity override the rules implemented by the Container CSS files to fix this bug. In such cases, is necessary to leverage the provided "hide-scrollbars" and "show-scrollbars" classes to write custom style rules to guard against this bug. For example: To fix the scrollbars issue for an Overlay instance with an id of "myoverlay" whose body element has scrollbars applied by default: #myoverlay .bd { height: 100px; /* Apply scrollbars for all browsers. */ overflow: auto; } #myoverlay.hide-scrollbars .bd { /* Hide scrollbars by default for Gecko on OS X */ overflow: hidden; } #myoverlay.show-scrollbars .bd { /* Show scrollbars for Gecko on OS X when the Overlay is visible */ overflow: auto; } To fix the scrollbars issue for a Panel instance with an id of "mypanel" whose body element has scrollbars applied by default: #mypanel .bd { height: 100px; /* Apply scrollbars for all browsers. */ overflow: auto; } .yui-panel-container.hide-scrollbars #mypanel .bd { /* Hide scrollbars by default for Gecko on OS X */ overflow: hidden; } .yui-panel-container.show-scrollbars #mypanel .bd { /* Show scrollbars for Gecko on OS X when the Panel is visible */ overflow: auto; }
  For more information see the Mozilla bug report for this issue.

• Flash Movies appear on top of Overlay instances

  Flash movies can appear on top of Overlay instances in IE and Gecko-based browsers. To fix this problem, set the "wmode" of the Flash movie to either "transparent" or "opaque" as indicated below:

  Via the <object> tag:

  <object> <param name="wmode" value="opaque"> </object> <object> <param name="wmode" value="transparent"> </object>

  Via the <embed> tag:

  <embed wmode="transparent"> ... </embed> <embed wmode="opaque"> ... </embed> For more information see the Adobe TechNote on this issue.

• Overlay instances not rendered at correct z-index in IE

  In IE, when an Overlay instance is rendered inside a relatively positioned element the z-index of the Overlay instance is now relative to its relatively positioned parent element. This is not a bug in the Overlay class, but rather a bug in IE where relatively positioned elements establish a new stacking context for their child nodes. To avoid this bug it is recommend that all Overlay instances that need to be able to float above any other element in the document be made direct descendants of the <body> element.

  [Read more on this issue.]

• Header elements for Panel instances using "Sam" skin shrinkwrap in IE 7

  In IE 7 (Standards Mode) if a Panel instance is created without specifying a value for the "width" configuration property the width of the Panel's header element will shrinkwrap to the width of its text node. To avoid triggering this bug in IE always specify a value for the "width" configuration property when using Panel.

• Panel instances render at 100% of the browser viewport

  In IE 7 (Quirks Mode) and IE 6 (Quirks Mode and Standards Mode) if any of the child nodes of a Panel instance's root element have "layout" and no value has been specified for the "width" configuration property, the Panel will render at 100% of the width of browser's viewport. This bug will manifest when using the "Sam" skin as layout is applied to the header, body and footer elements (by setting the CSS "zoom" property of the element to "1" ) in order to get the negative margins required for the rounded corners to render correctly. To avoid triggering this bug in IE always specify a value for the "width" configuration property when using Panel.

  For more information on IE and layout, see MSDN's hasLayout reference.

• Panel instances render at 2px wider when using "Sam" skin

  For the "Sam" skin a Panel instance's rounded corners are created via the application of negative 1px left and right margins on the header, body and footer elements. These negative margins will cause a Panel instance to be rendered at 2px wider than the value specified by the "width" configuration property. Therefore, when using the "Sam" skin consider the negative left and right margins and subtract 2 from the value passed to the "width" configuration property in order to have the Panel render at the desired width. For example, to render a Panel 300px wide, pass a value of "298px" to the "width" configuration property.

• In IE, borders for tables with border-collapse:collapse remain visible when the container is hidden

  If an Overlay, or any of its subclasses, contains a table with its border-collapse CSS property set to "collapse" instead of the default value of "separate", the borders of the table will remain visible, when the Overlay is configured to be initially hidden. The table contents will be hidden correctly.

  This is due to an IE bug, reproducible by the basic test case below:

  <style type="text/css"> .box {visibility:hidden;} td {border:1px solid red;} table {border-collapse:collapse;} </style> <div class="box"> <table> <tr> <td>1</td> <td>2</td> </tr> </table> </div>

  The simplest workaround if you're not using effects, is to use Overlay's hide() method to setup visibility. This will set the Overlays element's "style.visibility" property, which fixes the bug:

  // Start visible, then hide. var ovr = YAHOO.widget.Overlay("ovr"); ovr.render(); ovr.hide();

  You can also apply this workaround if you want to use effects by setting the effect up after you hide:

  // Start visible, but don't apply effects, to avoid initial animation. var ovr = YAHOO.widget.Overlay("ovr"); ovr.render(); ovr.hide(); ovr.cfg.setProperty("effect", {effect:.....});

  If initial flicker is a problem with the above solutions, you could set the visibility directly on the Overlay element after rendering:

  var ovr = YAHOO.widget.Overlay("ovr", {visible:false}); ovr.render(); YAHOO.util.Dom.setStyle(ovr.element, "visibility", "hidden");

  However, if possible one of the previous methods should be used since they use the public API as opposed to manipulating the DOM directly.

• Text input/Textarea caret not displayed in Firefox

  When a Panel's "modal" or "iframe" options are enabled, Gecko-based browsers such as Firefox do not render the flashing caret for text input boxes or text areas contained inside the Panel.

  This is a known problem with Gecko-based browsers related to text input fields being rendered on top of elements with overflow set to "auto" or "scroll", or iframes. More information can be found in the Mozilla bug report for the issue.

  The simplest workaround when using the modal mask, would be to set overflow to "visible" (or "hidden") on the mask, overriding the default value of "auto":

  .mask { overflow:visible; /* or overflow:hidden */ }

  However, there are side-effects associated with this simple mask workaround and it cannot always be applied.

  The value of "overflow:auto" applied to the mask by default is used to workaround another Mozilla bug and prevents scrollbars in Gecko-based browsers on MacOS from bleeding through the mask. If you intend to support Gecko-based browsers on MacOS and your page has elements with scrollbars, then this workaround cannot be used. Note that it also does not solve the problem if you have the "iframe" option enabled, or other page elements with overflow set to "auto" or "scroll" underneath the Panel.

  A more complex workaround for the bug involves setting "overflow:auto" on the text field (or one of it's containers) and also flipping it's display property (see Mozilla Bug 167801, comment 84). Although more complex, this workaround helps resolve the issue for both the iframe and modal mask use cases, as well any other elements you may have on the page with overflow set to "auto" or "scroll".

  See the following example with this workaround applied: Text Input Cursor Fix.

• Container inherits text-align values

  The container family, as currently implemented, does not force a default CSS text-align value for it's contents other than a text-align:right for Dialog's footer buttons. By default, text will be aligned based on the text-align value inherited from the container's ancestor(s) in the document.

  A common YUI scenario where you may see this is when YUI Grids is used. Containers rendered to document.body will have text-align evaluate to center, inherited from the YUI Grids rule for the body element.

  If you do need to specify a default text-align value for any particular member of the container family (and it's subclasses), a simple option is to use the default class name, to define your default text-align value:

  // Align text left by default, for Panel, Dialog and SimpleDialog (subclasses of Panel). // Module, Overlay and Tooltip are not affected. .yui-panel { text-align:left; }

• HTML Validator Mozilla Add-on causes NS_BASE_STREAM_CLOSED chrome exception

  The HTML Validator add-on for Mozilla browsers is known to cause a NS_BASE_STREAM_CLOSED chrome exception, when monitorresize is enabled. The exception does not impact container functionality.

  This appears to be a bug in the HTML Validator add-on and it's ability to validate pages with iframes containing data: urls, which are used by container to implement the monitorresize functionality for Gecko browers. The issue has been posted on the bug forum for the add-on.

  Disabling the add-on will fix the problem.

YUI on Mobile: Using Container Family with "A-Grade" Mobile Browsers

The Container family of controls has a few limitations when run on the default browsers for the Nokia N95 and Apple iPhone, but a majority of the feature set works correctly.

Below is a list of know issues for the mobile environments tested:

• Draggable containers are not supported

  Neither the iPhone nor the Nokia N95 were able to generate the events required to support Drag and Drop within the browser, and hence draggable containers are not supported. The same limitation would apply to the resizable container example.

• Tooltips are not supported on the iPhone

  Due to the absence of consistent mouseover/mouseout events on the iPhone, Tooltips cannot be displayed reliably. It's likely that other touch based devices have similar limitations.

  Tooltips will work on the Nokia N95, since it has a cursor, and it's likely they'd work on other cursor/joystick based devices

• constraintoviewport and fixedcenter configuration properties are not accurate on the iPhone

  The viewport size for the iPhone (as retrieved via the Dom Collection) is the same as the document size and does not reflect the visible screen region as it normally should. As a result, constraintoviewport or fixedcenter are calculated relative to the document size rather than the actual visible screen size. This is likely to result in the container being displayed outside of the visible screen region.

• Shadows/Modal Mask appear opaque on the Nokia N95

  The default Webkit browser on the Nokia N95 does not honor CSS opacity values and hence partially opaque areas of the Container, such as the shadow and modal mask, appear solid black (100% opaque).

Design Considerations

Some general design issues to consider when working on mobile device solutions using Container.

• Latency, Slow Networks

  The Container family allows you to generate Container controls from markup; in other words, the markup is delivered to the page and then transformed by JavaScript into the desired Container widget. When working on high-latency mobile networks, this could lead to the unmodified markup being displayed for a significant period of time before the control is actually rendered/hidden. To account for this, you should avoid using the window load event to construct your control and use one of the earlier page lifecycle events — onDOMReady, onContentReady, or onAvailable; see this example in the Event Utility section for more information about these events.

  Alternatively, you could consider building the control from JavaScript, if progressive enhancement is not a requirement.

• UI Targets

  The default Sam Skin implementation for the Container family works well for mobile devices also. It provides UI targets, such as close buttons, dialog buttons and title bars, which are large enough or have enough whitespace around them so as to be usable on touch devices such as the iPhone.

  If you do wish to optimize the mobile experience for users, you may consider serving up custom skin CSS based on the mobile browser's user agent string. The YAHOO mobile section has an example of how to parse the user agent string on the client; the same logic can be applied on the server also.

  Some of the UI targets/CSS rules you may want to customize when creating a custom mobile skin for Panel based containers to increase their target areas are:

  • Close Button: .yui-skin-sam .yui-panel .container-close
  • Title Bar/Header: .yui-skin-sam .yui-panel .hd
  • Dialogs Buttons: YUI Button CSS

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.