<div class="intro">

<p>

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.

</p>

</div>

{{>getting-started}}

<h2>Creating a Panel</h2>

<p>

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

</p>

```javascript

YUI().use('panel', function (Y) {

var panel = new Y.Panel({

srcNode : '#myPanelContent',

width : 400,

centered: true,

render : true

});

});

```

<h2>Modal Panel</h2>

<p>

A Panel is not modal by default. This functionality can be changed through the `modal` attribute, either during instantiation or later through the `set()` method.

</p>

```javascript

YUI().use('panel', function (Y) {

var panel = new Y.Panel({

srcNode: '#myPanelContent',

width : 400,

modal : true // Make the Panel modal

});

panel.render();

// Optionally, we could have written:

// panel.set('modal', true);

});

```

<p>

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

</p>

<h2>Choosing When to Focus and Hide</h2>

<p>

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

</p>

<p>

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

</p>

```javascript

YUI().use('panel', function (Y) {

var panel = new Y.Panel({

srcNode : '#myPanelContent',

width : 400,

centered: true,

modal : false,

render : true,

// The `hideOn` Attribute takes an array of objects with a required

// `eventName` property, and two optional properties:

// `node` and `keyCode`.

hideOn: [

{

// When we don't specify a `node`,

// it defaults to the `boundingBox` of this Panel instance.

eventName: 'clickoutside'

},

{

// Listen to click events on the `node` that was specified.

node : Y.one('#anotherNode'),

eventName: 'click'

}

]

});

});

```

<p>

Similarly, the `focusOn` attribute can be changed to configure the default focus behavior.

</p>

```javascript

var panel = new Y.Panel({

srcNode : '#myPanelContent',

width : 400,

centered: true,

modal : false,

render : true,

// The `focusOn` Attribute takes an array of objects with a required

// `eventName` property, and optionally the `node` property.

focusOn: [

{

// When we don't specify a `node`,

// it defaults to the `boundingBox` of this Panel instance.

eventName: 'clickoutside'

},

{

// Listen to click events on the `node` that was specified.

node : Y.one('#anotherNode'),

eventName: 'click'

}

]

});

});

```

<p>

To simply get rid of the default behavior, we could just set the `focusOn` and `hideOn` attributes to empty Arrays.

</p>

<h2>Header/Footer Button Support</h2>

<p>

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

</p>

```javascript

YUI().use('panel', function (Y) {

function doSomethingElse() {

// ...

}

var panel = new Y.Panel({

srcNode : '#myPanelContent',

width : 400,

centered: true,

// Make changes to the buttons through the `buttons` attribute,

// which takes an Array of Objects.

buttons: [

{

// Each object has a `value` property,

// which can be text or an HTML string.

value: "Okay",

// The `action` property takes the Function that should be

// executed on a click event.

action: function(e) {

e.preventDefault();

panel.hide();

doSomethingElse();

},

// The `section` property tells where to render the button and

// should be `Y.WidgetStdMod.HEADER` or `Y.WidgetStdMod.FOOTER`.

section: Y.WidgetStdMod.FOOTER

// Optional `classNames` property to add CSS classes to the

// button Node.

// optional `href` property if you are linking to an URL.

}

]

});

panel.render();

});

```

<p>

If you want to append buttons to the ones that are already present within the Panel, you can use the `addButton()` method.

</p>

```javascript

var cancelButton = {

value : 'Cancel',

action: function(e) {

e.preventDefault();

// ...

},

// 'header', 'footer' or Y.WidgetStdMod.HEADER also work here.

section: Y.WidgetStdMod.FOOTER

};

panel.addButton(cancelButton);

```

<h2>Notes Regarding Older Browsers</h2>

<p>

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

</p>

<p>

However, 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`.

</p>