index.mustache revision d9e7b0a9660f7ab72b65c085817a152c046472f5
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra<div class="intro">
a31d4503481b752a9ea058cce3d9b025d040a87cTilo Mitra <p>
a31d4503481b752a9ea058cce3d9b025d040a87cTilo Mitra 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.
a31d4503481b752a9ea058cce3d9b025d040a87cTilo Mitra </p>
a31d4503481b752a9ea058cce3d9b025d040a87cTilo Mitra</div>
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra
a31d4503481b752a9ea058cce3d9b025d040a87cTilo Mitra{{>getting-started}}
a31d4503481b752a9ea058cce3d9b025d040a87cTilo Mitra
a31d4503481b752a9ea058cce3d9b025d040a87cTilo Mitra<h2>Creating a Panel</h2>
84765788c559bfdead67172a79759ac60c77231bTilo Mitra
84765788c559bfdead67172a79759ac60c77231bTilo Mitra<p>
84765788c559bfdead67172a79759ac60c77231bTilo MitraThis 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.
84765788c559bfdead67172a79759ac60c77231bTilo Mitra</p>
84765788c559bfdead67172a79759ac60c77231bTilo Mitra
84765788c559bfdead67172a79759ac60c77231bTilo Mitra```javascript
84765788c559bfdead67172a79759ac60c77231bTilo MitraYUI().use('panel', function(Y) {
84765788c559bfdead67172a79759ac60c77231bTilo Mitra
84765788c559bfdead67172a79759ac60c77231bTilo Mitra var panel = new Y.Panel({
84765788c559bfdead67172a79759ac60c77231bTilo Mitra srcNode : '#myPanelContent',
84765788c559bfdead67172a79759ac60c77231bTilo Mitra width : 400,
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra 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 `hideOn` Attribute takes an array of objects with a required
// `eventName` property, and two optional properties:
// `node` and `keyCode`.
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>