index.mustache revision 30e909133d7ef44012f23d818227ad801d5cfa4f
e59faf65ce864fe95dc00f5d52b8323cdbd0608aTimo Sirainen<div class="intro">
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo Sirainen <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 autohide and autofocus, header/footer button support and a custom stylesheet. 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>
fdc557286bc9f92c5f3bb49096ff6e2bcec0ea79Timo Sirainen{{>getting-started}}
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo Sirainen<h2 id="default">Creating a Panel</h2>
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo Sirainen<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 enabled, and will be hidden if the "esc" key or "Close" button is pressed. Clicking anywhere outside the panel will bring back focus to the panel.</p>
e05a4c4136fec723f019bee8383103080203f127Timo SirainenYUI().use('panel', function(Y) {
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo Sirainen var panel = new Y.Panel({
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo Sirainen srcNode: "#myPanelContent",
eb0816090cf5a549280ad783b9aa6fec199d36baTimo Sirainen centered: true
eb0816090cf5a549280ad783b9aa6fec199d36baTimo Sirainen<h2 id="modality">Modal Panel</h2>
eb0816090cf5a549280ad783b9aa6fec199d36baTimo Sirainen<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>
eb0816090cf5a549280ad783b9aa6fec199d36baTimo SirainenYUI().use('panel', function(Y) {
eb0816090cf5a549280ad783b9aa6fec199d36baTimo Sirainen var panel = new Y.Panel({
01937f71b3ae0d5b30b813372f44a3e7e86c89dcTimo Sirainen srcNode: "#myPanelContent",
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo Sirainen modal: true //make a modal panel
ca98d6a1bbe73499da758a36bfab2963375c8d06Timo Sirainen //optionally, we could have written panel.set('modal', true);
eb0816090cf5a549280ad783b9aa6fec199d36baTimo Sirainen<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}}/Widget.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>
eb0816090cf5a549280ad783b9aa6fec199d36baTimo Sirainen<h2 id="events">Choosing when to focus and hide</h2>
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo Sirainen<p>By default, a 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>
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo Sirainen<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 it's bounding box is pressed, or when a certain element on the page (with an id of <code>anotherNode</code>) is clicked.</p>
eb0816090cf5a549280ad783b9aa6fec199d36baTimo SirainenYUI().use('panel', function(Y) {
d22301419109ed4a38351715e6760011421dadecTimo Sirainen var panel = new Y.Panel({
eb0816090cf5a549280ad783b9aa6fec199d36baTimo Sirainen srcNode: "#myPanelContent",
eb0816090cf5a549280ad783b9aa6fec199d36baTimo Sirainen centered: true,
eb0816090cf5a549280ad783b9aa6fec199d36baTimo Sirainen //The hideOn Attribute takes an array of objects, with a required property "eventName"
d6badc27cd6e8d3398877b6766cb0aaeef3a7800Timo Sirainen //and two optional properties "node", and "keyCode"
eb0816090cf5a549280ad783b9aa6fec199d36baTimo Sirainen //When we don't specify a node, it defaults to the boundingbox of this panel instance
d6badc27cd6e8d3398877b6766cb0aaeef3a7800Timo Sirainen eventName: "clickoutside"
a341c4cdbd4b93ba479f465ad3f569dc82f57312Timo Sirainen //This listens to click events on the node that was specified
013e3b3942e9550fde619a0b3ce6bdd04edc4268Timo Sirainen node: Y.one("#anotherNode"),
a2f250a332dfc1e6cd4ffd196c621eb9dbf7b8a1Timo Sirainen eventName:"click"
eb0816090cf5a549280ad783b9aa6fec199d36baTimo Sirainen<p>Similarly, the "focusOn" attribute can be changed to configure the default focus behavior</p>
eb0816090cf5a549280ad783b9aa6fec199d36baTimo Sirainen var panel = new Y.Panel({
eb0816090cf5a549280ad783b9aa6fec199d36baTimo Sirainen srcNode: "#myPanelContent",
ca98d6a1bbe73499da758a36bfab2963375c8d06Timo Sirainen centered: true,
eb0816090cf5a549280ad783b9aa6fec199d36baTimo Sirainen //The focusOn Attribute takes an array of objects, with a required property "eventName"
eb0816090cf5a549280ad783b9aa6fec199d36baTimo Sirainen //and two optional properties "node", and "keyCode"
eb0816090cf5a549280ad783b9aa6fec199d36baTimo Sirainen //When we don't specify a node, it defaults to the boundingbox of this panel instance
eb0816090cf5a549280ad783b9aa6fec199d36baTimo Sirainen eventName: "clickoutside"
eb0816090cf5a549280ad783b9aa6fec199d36baTimo Sirainen //This listens to click events on the node that was specified
eb0816090cf5a549280ad783b9aa6fec199d36baTimo Sirainen node: Y.one("#anotherNode"),
eb0816090cf5a549280ad783b9aa6fec199d36baTimo Sirainen eventName:"click"
d6badc27cd6e8d3398877b6766cb0aaeef3a7800Timo Sirainen<p>To simply get rid of the default behavior, we could just set the "focusOn" and "hideOn" attributes to empty arrays.</p>
d6badc27cd6e8d3398877b6766cb0aaeef3a7800Timo Sirainen<h2 id="buttons">Header/Footer Button Support</h2>
d6badc27cd6e8d3398877b6766cb0aaeef3a7800Timo Sirainen<p>Panel supports header/footer buttons through the <a href="{{apiDocs}}/WidgetButtons.html">`WidgetButtons`</a> and <a href="{{apiDocs}}/Widget-StdMod.html">`Widget-StdMod`</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>
d6badc27cd6e8d3398877b6766cb0aaeef3a7800Timo SirainenYUI().use('panel', function(Y) {
6d931bbce16786df431e9ae8201a78a95084316dTimo Sirainen var doSomethingElse = function() { ... };
96308127e006bb3b1108093bcf4cc1fd9481cb7aTimo Sirainen var panel = new Y.Panel({
96308127e006bb3b1108093bcf4cc1fd9481cb7aTimo Sirainen srcNode: "#myPanelContent",
9f19a50d5966643c4d1c5ca06868ac2ad31bc4d5Timo Sirainen centered: true,
61b0637759146621cbb7edcbd0b03a71cfd66dfeTimo Sirainen //make changes to the buttons through the "buttons" attribute, which takes an array of objects
9f19a50d5966643c4d1c5ca06868ac2ad31bc4d5Timo Sirainen //each object has a "value" property, which can be text or an HTML string,
9f19a50d5966643c4d1c5ca06868ac2ad31bc4d5Timo Sirainen value: "Okay",
ca98d6a1bbe73499da758a36bfab2963375c8d06Timo Sirainen // "defaultFn" which takes the function that should be executed on a click event
741d705983e10046f07ef372b760bcdd169b068aTimo Sirainen defaultFn: function(e) {
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo Sirainen doSomethingElse();
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo Sirainen // "section" which tells where to render the button and should be Y.WidgetStdMod.HEADER, or Y.WidgetStdMod.FOOTER
0cb2e8eb55e70f8ebe1e8349bdf49e4cbe5d8834Timo Sirainen //plus an optional "href" property if you are linking to an URL
48270badadd82279bfe50ae3d187aea8b0b2b30eTimo Sirainen<p>If you want to append buttons to the ones that are already present within the panel, you can use the <code>addButton()</code> method.
48270badadd82279bfe50ae3d187aea8b0b2b30eTimo Sirainen var cancelButton = {
48270badadd82279bfe50ae3d187aea8b0b2b30eTimo Sirainen value: "Cancel",
48270badadd82279bfe50ae3d187aea8b0b2b30eTimo Sirainen defaultFn: function(e) {
section: Y.WidgetStdMod.FOOTER //we could also write "header", "footer" or Y.WidgetStdMod.HEADER here.
panel.addButton(cancelButton);
<p>Panel is tested across the A-grade browser set according to the <a href="http://developer.yahoo.com/yui/articles/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>