12N/A<div class="intro">

12N/A <p>

12N/A 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.

12N/A </p>

12N/A</div>

12N/A

12N/A{{>getting-started}}

12N/A

12N/A<h2>Creating a Panel</h2>

12N/A

12N/A<p>

12N/AThis 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.

12N/A</p>

12N/A

12N/A```javascript

12N/AYUI().use('panel', function (Y) {

12N/A

12N/A var panel = new Y.Panel({

12N/A srcNode : '#myPanelContent',

12N/A width : 400,

12N/A centered: true,

12N/A render : true

12N/A });

12N/A

12N/A});

12N/A```

12N/A

12N/A<h2>Modal Panel</h2>

12N/A

12N/A<p>

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

12N/A</p>

135N/A

30N/A```javascript

30N/AYUI().use('panel', function (Y) {

12N/A

12N/A var panel = new Y.Panel({

12N/A srcNode: '#myPanelContent',

114N/A width : 400,

114N/A modal : true // Make the Panel modal

12N/A });

12N/A

12N/A panel.render();

114N/A // Optionally, we could have written:

114N/A // panel.set('modal', true);

164N/A

12N/A});

30N/A```

30N/A

29N/A<p>

29N/APanels 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.

29N/A</p>

29N/A

59N/A<h2>Choosing When to Focus and Hide</h2>

29N/A

29N/A<p>

59N/ABy 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.

59N/A</p>

114N/A

114N/A<p>

114N/AThe 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.

114N/A</p>

164N/A

164N/A```javascript

12N/AYUI().use('panel', function (Y) {

12N/A

59N/A var panel = new Y.Panel({

12N/A srcNode : '#myPanelContent',

12N/A width : 400,

12N/A centered: true,

12N/A modal : false,

12N/A render : true,

12N/A

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

98N/A // `eventName` property, and two optional properties:

33N/A // `node` and `keyCode`.

34N/A hideOn: [

33N/A {

59N/A // When we don't specify a `node`,

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

33N/A eventName: 'clickoutside'

33N/A },

59N/A {

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

127N/A node : Y.one('#anotherNode'),

98N/A eventName: 'click'

33N/A }

33N/A ]

124N/A });

22N/A

59N/A});

59N/A```

59N/A

59N/A<p>

59N/ASimilarly, the `focusOn` attribute can be changed to configure the default focus behavior.

98N/A</p>

59N/A

59N/A```javascript

59N/A var panel = new Y.Panel({

136N/A srcNode : '#myPanelContent',

59N/A width : 400,

59N/A centered: true,

124N/A modal : false,

59N/A render : true,

24N/A

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

33N/A // `eventName` property, and optionally the `node` property.

117N/A focusOn: [

33N/A {

124N/A // When we don't specify a `node`,

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

29N/A eventName: 'clickoutside'

33N/A },

119N/A {

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

59N/A node : Y.one('#anotherNode'),

104N/A eventName: 'click'

59N/A }

59N/A ]

59N/A });

124N/A

29N/A});

29N/A```

33N/A

34N/A<p>

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

29N/A</p>

59N/A

59N/A<h2>Header/Footer Button Support</h2>

59N/A

59N/A<p>

59N/APanel 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.

124N/A</p>

59N/A

33N/A```javascript

59N/AYUI().use('panel', function (Y) {

59N/A

24N/A function doSomethingElse() {

33N/A // ...

29N/A }

33N/A

29N/A var panel = new Y.Panel({

33N/A srcNode : '#myPanelContent',

59N/A width : 400,

59N/A centered: true,

59N/A

124N/A // Make changes to the buttons through the `buttons` attribute,

124N/A // which takes an Array of Objects.

124N/A buttons: [

124N/A {

124N/A // Each object has a `value` property,

124N/A // which can be text or an HTML string.

124N/A value: "Okay",

124N/A

114N/A // The `action` property takes the Function that should be

114N/A // executed on a click event.

114N/A action: function(e) {

114N/A e.preventDefault();

59N/A panel.hide();

59N/A doSomethingElse();

59N/A },

59N/A

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

59N/A // should be `Y.WidgetStdMod.HEADER` or `Y.WidgetStdMod.FOOTER`.

59N/A section: Y.WidgetStdMod.FOOTER

59N/A

59N/A // Optional `classNames` property to add CSS classes to the

124N/A // button Node.

124N/A

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

12N/A }

30N/A ]

97N/A });

98N/A

120N/A panel.render();

124N/A

124N/A});

30N/A```

33N/A

12N/A<p>

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

20N/A</p>

124N/A

124N/A```javascript

124N/Avar cancelButton = {

20N/A value : 'Cancel',

33N/A action: function(e) {

33N/A e.preventDefault();

124N/A // ...

124N/A },

124N/A

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

124N/A section: Y.WidgetStdMod.FOOTER

33N/A};

114N/A

98N/Apanel.addButton(cancelButton);

114N/A```

114N/A

98N/A<h2>Notes Regarding Older Browsers</h2>

30N/A

124N/A<p>

124N/APanel 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.

124N/A</p>

33N/A

33N/A<p>

12N/AHowever, 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`.

22N/A</p>

114N/A