index.mustache revision d9e7b0a9660f7ab72b65c085817a152c046472f5
71704748bda66fdb9dedfd86d6b0d5bd3e84e9c2Markus Gross<div class="intro">
71704748bda66fdb9dedfd86d6b0d5bd3e84e9c2Markus Gross 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.
71704748bda66fdb9dedfd86d6b0d5bd3e84e9c2Markus Gross{{>getting-started}}
71704748bda66fdb9dedfd86d6b0d5bd3e84e9c2Markus Gross<h2>Creating a Panel</h2>
71704748bda66fdb9dedfd86d6b0d5bd3e84e9c2Markus GrossThis 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.
71704748bda66fdb9dedfd86d6b0d5bd3e84e9c2Markus GrossYUI().use('panel', function(Y) {
54ea981a0503c396c2923a1c06421c6235baf27fChristian Maeder var panel = new Y.Panel({
cb677b28797cf29452620f58606e174ab93ac426Christian Maeder srcNode : '#myPanelContent',
6f449482b2ca9189ac5fe5d3b2e1cb8de6e10cbcMarkus Gross centered: true,
cb677b28797cf29452620f58606e174ab93ac426Christian Maeder render : true
55c5e901b5c3466300009135585bc70bd576dcb6Christian Maeder<h2>Modal Panel</h2>
cb677b28797cf29452620f58606e174ab93ac426Christian MaederA Panel is not modal by default. This functionality can be changed through the `modal` attribute, either during instantiation or later through the `set()` method.
71704748bda66fdb9dedfd86d6b0d5bd3e84e9c2Markus Gross```javascript
cb677b28797cf29452620f58606e174ab93ac426Christian MaederYUI().use('panel', function(Y) {
71704748bda66fdb9dedfd86d6b0d5bd3e84e9c2Markus Gross var panel = new Y.Panel({
71704748bda66fdb9dedfd86d6b0d5bd3e84e9c2Markus Gross srcNode: '#myPanelContent',
71704748bda66fdb9dedfd86d6b0d5bd3e84e9c2Markus Gross width : 400,
71704748bda66fdb9dedfd86d6b0d5bd3e84e9c2Markus Gross modal : true // Make the Panel modal
71704748bda66fdb9dedfd86d6b0d5bd3e84e9c2Markus Gross // Optionally, we could have written:
71704748bda66fdb9dedfd86d6b0d5bd3e84e9c2Markus Gross // panel.set('modal', true);
71704748bda66fdb9dedfd86d6b0d5bd3e84e9c2Markus GrossPanels 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.
71704748bda66fdb9dedfd86d6b0d5bd3e84e9c2Markus Gross<h2>Choosing When to Focus and Hide</h2>
71704748bda66fdb9dedfd86d6b0d5bd3e84e9c2Markus GrossBy 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.
71704748bda66fdb9dedfd86d6b0d5bd3e84e9c2Markus GrossThe 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.
71704748bda66fdb9dedfd86d6b0d5bd3e84e9c2Markus Gross```javascript
71704748bda66fdb9dedfd86d6b0d5bd3e84e9c2Markus GrossYUI().use('panel', function(Y) {
71704748bda66fdb9dedfd86d6b0d5bd3e84e9c2Markus Gross var panel = new Y.Panel({
71704748bda66fdb9dedfd86d6b0d5bd3e84e9c2Markus Gross srcNode : '#myPanelContent',
71704748bda66fdb9dedfd86d6b0d5bd3e84e9c2Markus Gross width : 400,
e49fd57c63845c7806860a9736ad09f6d44dbaedChristian Maeder centered: true,
cd6354cc2af5958c304c84e65707435293c5ccc7Markus Gross modal : false,
71704748bda66fdb9dedfd86d6b0d5bd3e84e9c2Markus Gross render : true,
cb677b28797cf29452620f58606e174ab93ac426Christian Maeder // The `hideOn` Attribute takes an array of objects with a required
cb677b28797cf29452620f58606e174ab93ac426Christian Maeder // `eventName` property, and two optional properties:
cb677b28797cf29452620f58606e174ab93ac426Christian Maeder // `node` and `keyCode`.
cb677b28797cf29452620f58606e174ab93ac426Christian Maeder // When we don't specify a `node`,
cb677b28797cf29452620f58606e174ab93ac426Christian Maeder // it defaults to the `boundingBox` of this Panel instance.
cb677b28797cf29452620f58606e174ab93ac426Christian Maeder eventName: 'clickoutside'
a74c301a1777a7c11f8d2e027cdbbab56e6fea10Markus Gross // Listen to click events on the `node` that was specified.
a74c301a1777a7c11f8d2e027cdbbab56e6fea10Markus Gross node : Y.one('#anotherNode'),
71704748bda66fdb9dedfd86d6b0d5bd3e84e9c2Markus Gross eventName: 'click'
cb677b28797cf29452620f58606e174ab93ac426Christian MaederSimilarly, the `focusOn` attribute can be changed to configure the default focus behavior.
cb677b28797cf29452620f58606e174ab93ac426Christian Maeder var panel = new Y.Panel({
71704748bda66fdb9dedfd86d6b0d5bd3e84e9c2Markus Gross srcNode : '#myPanelContent',
40f116697627649720a9d7bd456025925e799408Markus Gross width : 400,
cb677b28797cf29452620f58606e174ab93ac426Christian Maeder centered: true,
cb677b28797cf29452620f58606e174ab93ac426Christian Maeder modal : false,
cb677b28797cf29452620f58606e174ab93ac426Christian Maeder render : true,
71704748bda66fdb9dedfd86d6b0d5bd3e84e9c2Markus Gross // The `hideOn` Attribute takes an array of objects with a required
cb677b28797cf29452620f58606e174ab93ac426Christian Maeder // `eventName` property, and two optional properties:
cb677b28797cf29452620f58606e174ab93ac426Christian Maeder // `node` and `keyCode`.
71704748bda66fdb9dedfd86d6b0d5bd3e84e9c2Markus Gross // When we don't specify a `node`,
a74c301a1777a7c11f8d2e027cdbbab56e6fea10Markus Gross // it defaults to the `boundingBox` of this Panel instance.
a74c301a1777a7c11f8d2e027cdbbab56e6fea10Markus Gross eventName: 'clickoutside'
71704748bda66fdb9dedfd86d6b0d5bd3e84e9c2Markus Gross // Listen to click events on the `node` that was specified.
cb677b28797cf29452620f58606e174ab93ac426Christian Maeder node : Y.one('#anotherNode'),
f8eff59ab34565ab064b86ac7edc2d8bab498e1aMarkus Gross eventName: 'click'
71704748bda66fdb9dedfd86d6b0d5bd3e84e9c2Markus GrossTo simply get rid of the default behavior, we could just set the `focusOn` and `hideOn` attributes to empty Arrays.
cb677b28797cf29452620f58606e174ab93ac426Christian Maeder<h2>Header/Footer Button Support</h2>
cb677b28797cf29452620f58606e174ab93ac426Christian MaederPanel 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.
40f116697627649720a9d7bd456025925e799408Markus Gross```javascript
71704748bda66fdb9dedfd86d6b0d5bd3e84e9c2Markus GrossYUI().use('panel', function(Y) {
cb677b28797cf29452620f58606e174ab93ac426Christian Maeder function doSomethingElse () {
0cdab57df750111cbff2e399fbcd6d75b29d952bChristian Maeder var panel = new Y.Panel({
71704748bda66fdb9dedfd86d6b0d5bd3e84e9c2Markus Gross srcNode : '#myPanelContent',
cb677b28797cf29452620f58606e174ab93ac426Christian Maeder centered: true,
71704748bda66fdb9dedfd86d6b0d5bd3e84e9c2Markus Gross // Make changes to the buttons through the `buttons` attribute,
a74c301a1777a7c11f8d2e027cdbbab56e6fea10Markus Gross // which takes an Array of Objects.
71704748bda66fdb9dedfd86d6b0d5bd3e84e9c2Markus Gross // Each object has a `value` property,
cb677b28797cf29452620f58606e174ab93ac426Christian Maeder // which can be text or an HTML string.
cb677b28797cf29452620f58606e174ab93ac426Christian Maeder value: "Okay",
a74c301a1777a7c11f8d2e027cdbbab56e6fea10Markus Gross // The `action` property takes the Function that should be
a74c301a1777a7c11f8d2e027cdbbab56e6fea10Markus Gross // executed on a click event.
a74c301a1777a7c11f8d2e027cdbbab56e6fea10Markus Gross action: function (e) {
f8eff59ab34565ab064b86ac7edc2d8bab498e1aMarkus Gross doSomethingElse();
f8eff59ab34565ab064b86ac7edc2d8bab498e1aMarkus Gross // The `section` property tells where to render the button and
cd6354cc2af5958c304c84e65707435293c5ccc7Markus Gross // should be `Y.WidgetStdMod.HEADER` or `Y.WidgetStdMod.FOOTER`.
f8eff59ab34565ab064b86ac7edc2d8bab498e1aMarkus Gross // Optional `classNames` property to add CSS classes to the
f8eff59ab34565ab064b86ac7edc2d8bab498e1aMarkus Gross // button Node.
f8eff59ab34565ab064b86ac7edc2d8bab498e1aMarkus Gross // optional `href` property if you are linking to an URL.
cd6354cc2af5958c304c84e65707435293c5ccc7Markus GrossIf you want to append buttons to the ones that are already present within the Panel, you can use the `addButton()` method.
7bb4a5dbdc5e29315aaa89fbeb7e41f6946cadd9Markus Gross```javascript
d24317c8197e565e60c8f41309de246249c1e57eChristian Maeder var cancelButton = {
cd6354cc2af5958c304c84e65707435293c5ccc7Markus Gross value : 'Cancel',
cd6354cc2af5958c304c84e65707435293c5ccc7Markus Gross action: function (e) {
cd6354cc2af5958c304c84e65707435293c5ccc7Markus Gross // 'header', 'footer' or Y.WidgetStdMod.HEADER also work here.
cd6354cc2af5958c304c84e65707435293c5ccc7Markus Gross<h2>Notes Regarding Older Browsers</h2>
cd6354cc2af5958c304c84e65707435293c5ccc7Markus GrossPanel 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.
cd6354cc2af5958c304c84e65707435293c5ccc7Markus GrossHowever, 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`.