index.mustache revision b314fc1188609ac757efdb7f61cc5882a070a5e7
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra<div class="intro">
8201152df05092cc62753b69918225acd386bb9dEric Ferraiuolo Panel is a Widget that mimics the functionality of a regular OS window. It is similar to Overlay, with added functionality to support modality, event listeners on which to auto-hide and auto-focus, header/footer button support and skins. Panel does not have any implementation code of it's own. It implements a set of extensions that provide certain sets of functionality. The <a href="../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.
84765788c559bfdead67172a79759ac60c77231bTilo Mitra{{>getting-started}}
8201152df05092cc62753b69918225acd386bb9dEric Ferraiuolo<h2>Creating a Panel</h2>
8201152df05092cc62753b69918225acd386bb9dEric FerraiuoloThis simple example will create a Panel with default functionality. By default, a Panel is rendered with a "close" button added to the header, with modality disabled, and will be hidden if the `esc` key or "close" button is pressed.
b314fc1188609ac757efdb7f61cc5882a070a5e7Eric FerraiuoloYUI().use('panel', function (Y) {
a31d4503481b752a9ea058cce3d9b025d040a87cTilo Mitra var panel = new Y.Panel({
8201152df05092cc62753b69918225acd386bb9dEric Ferraiuolo srcNode : '#myPanelContent',
8201152df05092cc62753b69918225acd386bb9dEric Ferraiuolo centered: true,
8201152df05092cc62753b69918225acd386bb9dEric Ferraiuolo render : true
8201152df05092cc62753b69918225acd386bb9dEric Ferraiuolo<h2>Modal Panel</h2>
8201152df05092cc62753b69918225acd386bb9dEric FerraiuoloA Panel is not modal by default. This functionality can be changed through the `modal` attribute, either during instantiation or later through the `set()` method.
b314fc1188609ac757efdb7f61cc5882a070a5e7Eric FerraiuoloYUI().use('panel', function (Y) {
a31d4503481b752a9ea058cce3d9b025d040a87cTilo Mitra var panel = new Y.Panel({
8201152df05092cc62753b69918225acd386bb9dEric Ferraiuolo srcNode: '#myPanelContent',
8201152df05092cc62753b69918225acd386bb9dEric Ferraiuolo modal : true // Make the Panel modal
8201152df05092cc62753b69918225acd386bb9dEric Ferraiuolo // Optionally, we could have written:
8201152df05092cc62753b69918225acd386bb9dEric Ferraiuolo // panel.set('modal', true);
8201152df05092cc62753b69918225acd386bb9dEric FerraiuoloPanels can be nested in one another, and have different modal behavior. For instance, a modal Panel may launch a non-modal Panel on top of it. The <a href="{{apiDocs}}/classes/WidgetModality.html">`WidgetModality`</a> extension takes care of nesting behavior so no extra code is required for the implementer. Refer to the examples for more information.
8201152df05092cc62753b69918225acd386bb9dEric Ferraiuolo<h2>Choosing When to Focus and Hide</h2>
8201152df05092cc62753b69918225acd386bb9dEric FerraiuoloBy default, a modal Panel will return focus to itself if anything else on the page receives focus or is clicked. On the other hand, clicking the "close" button, or pressing the `esc` key will hide it. Both of these options can be configured as needed through the `hideOn` and `focusOn` attributes.
8201152df05092cc62753b69918225acd386bb9dEric FerraiuoloThe following code snippet shows how to change the default "hide" behavior. Instead of hiding when the `esc` key is pressed, the Panel hides whenever something outside its `boundingBox` is pressed, or when a certain element on the page (with an id of `anotherNode`) is clicked.
b314fc1188609ac757efdb7f61cc5882a070a5e7Eric FerraiuoloYUI().use('panel', function (Y) {
a31d4503481b752a9ea058cce3d9b025d040a87cTilo Mitra var panel = new Y.Panel({
8201152df05092cc62753b69918225acd386bb9dEric Ferraiuolo srcNode : '#myPanelContent',
a31d4503481b752a9ea058cce3d9b025d040a87cTilo Mitra centered: true,
8201152df05092cc62753b69918225acd386bb9dEric Ferraiuolo modal : false,
8201152df05092cc62753b69918225acd386bb9dEric Ferraiuolo render : true,
8201152df05092cc62753b69918225acd386bb9dEric Ferraiuolo // The `hideOn` Attribute takes an array of objects with a required
8201152df05092cc62753b69918225acd386bb9dEric Ferraiuolo // `eventName` property, and two optional properties:
8201152df05092cc62753b69918225acd386bb9dEric Ferraiuolo // `node` and `keyCode`.
8201152df05092cc62753b69918225acd386bb9dEric Ferraiuolo // When we don't specify a `node`,
8201152df05092cc62753b69918225acd386bb9dEric Ferraiuolo // it defaults to the `boundingBox` of this Panel instance.
8201152df05092cc62753b69918225acd386bb9dEric Ferraiuolo eventName: 'clickoutside'
8201152df05092cc62753b69918225acd386bb9dEric Ferraiuolo // Listen to click events on the `node` that was specified.
8201152df05092cc62753b69918225acd386bb9dEric Ferraiuolo node : Y.one('#anotherNode'),
8201152df05092cc62753b69918225acd386bb9dEric Ferraiuolo eventName: 'click'
8201152df05092cc62753b69918225acd386bb9dEric FerraiuoloSimilarly, the `focusOn` attribute can be changed to configure the default focus behavior.
a31d4503481b752a9ea058cce3d9b025d040a87cTilo Mitra var panel = new Y.Panel({
8201152df05092cc62753b69918225acd386bb9dEric Ferraiuolo srcNode : '#myPanelContent',
a31d4503481b752a9ea058cce3d9b025d040a87cTilo Mitra centered: true,
8201152df05092cc62753b69918225acd386bb9dEric Ferraiuolo modal : false,
8201152df05092cc62753b69918225acd386bb9dEric Ferraiuolo render : true,
8201152df05092cc62753b69918225acd386bb9dEric Ferraiuolo // The `hideOn` Attribute takes an array of objects with a required
8201152df05092cc62753b69918225acd386bb9dEric Ferraiuolo // `eventName` property, and two optional properties:
8201152df05092cc62753b69918225acd386bb9dEric Ferraiuolo // `node` and `keyCode`.
8201152df05092cc62753b69918225acd386bb9dEric Ferraiuolo // When we don't specify a `node`,
8201152df05092cc62753b69918225acd386bb9dEric Ferraiuolo // it defaults to the `boundingBox` of this Panel instance.
8201152df05092cc62753b69918225acd386bb9dEric Ferraiuolo eventName: 'clickoutside'
8201152df05092cc62753b69918225acd386bb9dEric Ferraiuolo // Listen to click events on the `node` that was specified.
8201152df05092cc62753b69918225acd386bb9dEric Ferraiuolo node : Y.one('#anotherNode'),
8201152df05092cc62753b69918225acd386bb9dEric Ferraiuolo eventName: 'click'
8201152df05092cc62753b69918225acd386bb9dEric FerraiuoloTo simply get rid of the default behavior, we could just set the `focusOn` and `hideOn` attributes to empty Arrays.
8201152df05092cc62753b69918225acd386bb9dEric Ferraiuolo<h2>Header/Footer Button Support</h2>
8201152df05092cc62753b69918225acd386bb9dEric FerraiuoloPanel supports header/footer buttons through the <a href="{{apiDocs}}/classes/WidgetButtons.html">`WidgetButtons`</a> and <a href="{{apiDocs}}/classes/WidgetStdMod.html">`WidgetStdMod`</a> extensions. By default, it comes with a "close" button represented by the "x" in the top-right corner of the header. As a developer, you can easily add/remove buttons to the header or the footer, change the style of existing buttons, or change the markup that is used to render the buttons.
b314fc1188609ac757efdb7f61cc5882a070a5e7Eric FerraiuoloYUI().use('panel', function (Y) {
b314fc1188609ac757efdb7f61cc5882a070a5e7Eric Ferraiuolo function doSomethingElse() {
a31d4503481b752a9ea058cce3d9b025d040a87cTilo Mitra var panel = new Y.Panel({
8201152df05092cc62753b69918225acd386bb9dEric Ferraiuolo srcNode : '#myPanelContent',
a31d4503481b752a9ea058cce3d9b025d040a87cTilo Mitra centered: true,
8201152df05092cc62753b69918225acd386bb9dEric Ferraiuolo // Make changes to the buttons through the `buttons` attribute,
8201152df05092cc62753b69918225acd386bb9dEric Ferraiuolo // which takes an Array of Objects.
8201152df05092cc62753b69918225acd386bb9dEric Ferraiuolo // Each object has a `value` property,
8201152df05092cc62753b69918225acd386bb9dEric Ferraiuolo // which can be text or an HTML string.
8201152df05092cc62753b69918225acd386bb9dEric Ferraiuolo value: "Okay",
8201152df05092cc62753b69918225acd386bb9dEric Ferraiuolo // The `action` property takes the Function that should be
8201152df05092cc62753b69918225acd386bb9dEric Ferraiuolo // executed on a click event.
b314fc1188609ac757efdb7f61cc5882a070a5e7Eric Ferraiuolo action: function(e) {
8201152df05092cc62753b69918225acd386bb9dEric Ferraiuolo doSomethingElse();
8201152df05092cc62753b69918225acd386bb9dEric Ferraiuolo // The `section` property tells where to render the button and
8201152df05092cc62753b69918225acd386bb9dEric Ferraiuolo // should be `Y.WidgetStdMod.HEADER` or `Y.WidgetStdMod.FOOTER`.
b314fc1188609ac757efdb7f61cc5882a070a5e7Eric Ferraiuolo // Optional `classNames` property to add CSS classes to the
d9e7b0a9660f7ab72b65c085817a152c046472f5Eric Ferraiuolo // button Node.
d9e7b0a9660f7ab72b65c085817a152c046472f5Eric Ferraiuolo // optional `href` property if you are linking to an URL.
8201152df05092cc62753b69918225acd386bb9dEric FerraiuoloIf you want to append buttons to the ones that are already present within the Panel, you can use the `addButton()` method.
b314fc1188609ac757efdb7f61cc5882a070a5e7Eric Ferraiuolovar cancelButton = {
b314fc1188609ac757efdb7f61cc5882a070a5e7Eric Ferraiuolo value : 'Cancel',
b314fc1188609ac757efdb7f61cc5882a070a5e7Eric Ferraiuolo action: function(e) {
b314fc1188609ac757efdb7f61cc5882a070a5e7Eric Ferraiuolo // 'header', 'footer' or Y.WidgetStdMod.HEADER also work here.
8201152df05092cc62753b69918225acd386bb9dEric Ferraiuolo<h2>Notes Regarding Older Browsers</h2>
8201152df05092cc62753b69918225acd386bb9dEric FerraiuoloPanel is tested across the A-grade browser set according to the <a href="http://yuilibrary.com/yui/docs/tutorials/gbs/" alt="Graded Browser Support">GBS Browser Test Baseline</a> as of July 2011.
8201152df05092cc62753b69918225acd386bb9dEric FerraiuoloHowever, developers implementing Panel and other components which rely on `z-index` support in IE6 and IE7 should be aware of the concept of <a href="https://developer.mozilla.org/en/Understanding_CSS_z-index/Stacking_context_example_2" alt="Stacking Context in IE">stacking context</a>. Essentially, when setting the `z-index` of the widget, you should ensure that the Widget's parent does not have a lower `z-index`.