index.mustache revision 8f0dc35284b10842ef7c44ffc3d410227804fced
1b94590fd02ca19669dfb4b5deb563a290459d81Tilo Mitra<div class="intro">
a31d4503481b752a9ea058cce3d9b025d040a87cTilo Mitra <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>
84765788c559bfdead67172a79759ac60c77231bTilo Mitra{{>getting-started}}
8f0dc35284b10842ef7c44ffc3d410227804fcedTilo Mitra<h2 id="default">Creating a Panel</h2>
a31d4503481b752a9ea058cce3d9b025d040a87cTilo Mitra<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>
a31d4503481b752a9ea058cce3d9b025d040a87cTilo MitraYUI().use('panel', function(Y) {
a31d4503481b752a9ea058cce3d9b025d040a87cTilo Mitra var panel = new Y.Panel({
a31d4503481b752a9ea058cce3d9b025d040a87cTilo Mitra srcNode: "#myPanelContent",
a31d4503481b752a9ea058cce3d9b025d040a87cTilo Mitra centered: true
8f0dc35284b10842ef7c44ffc3d410227804fcedTilo Mitra<h2 id="modality">Modal Panel</h2>
84765788c559bfdead67172a79759ac60c77231bTilo Mitra<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>
a31d4503481b752a9ea058cce3d9b025d040a87cTilo MitraYUI().use('panel', function(Y) {
a31d4503481b752a9ea058cce3d9b025d040a87cTilo Mitra var panel = new Y.Panel({
a31d4503481b752a9ea058cce3d9b025d040a87cTilo Mitra srcNode: "#myPanelContent",
84765788c559bfdead67172a79759ac60c77231bTilo Mitra modal: true //make a modal panel
84765788c559bfdead67172a79759ac60c77231bTilo Mitra //optionally, we could have written panel.set('modal', true);
a31d4503481b752a9ea058cce3d9b025d040a87cTilo Mitra<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>
8f0dc35284b10842ef7c44ffc3d410227804fcedTilo Mitra<h2 id="events">Choosing when to focus and hide</h2>
a31d4503481b752a9ea058cce3d9b025d040a87cTilo Mitra<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>
a31d4503481b752a9ea058cce3d9b025d040a87cTilo Mitra<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>
a31d4503481b752a9ea058cce3d9b025d040a87cTilo MitraYUI().use('panel', function(Y) {
a31d4503481b752a9ea058cce3d9b025d040a87cTilo Mitra var panel = new Y.Panel({
a31d4503481b752a9ea058cce3d9b025d040a87cTilo Mitra srcNode: "#myPanelContent",
a31d4503481b752a9ea058cce3d9b025d040a87cTilo Mitra centered: true,
a31d4503481b752a9ea058cce3d9b025d040a87cTilo Mitra modal:false,
a31d4503481b752a9ea058cce3d9b025d040a87cTilo Mitra //The hideOn Attribute takes an array of objects, with a required property "eventName"
a31d4503481b752a9ea058cce3d9b025d040a87cTilo Mitra //and two optional properties "node", and "keyCode"
a31d4503481b752a9ea058cce3d9b025d040a87cTilo Mitra //When we don't specify a node, it defaults to the boundingbox of this panel instance
a31d4503481b752a9ea058cce3d9b025d040a87cTilo Mitra eventName: "clickoutside"
a31d4503481b752a9ea058cce3d9b025d040a87cTilo Mitra //This listens to click events on the node that was specified
a31d4503481b752a9ea058cce3d9b025d040a87cTilo Mitra node: Y.one("#anotherNode"),
a31d4503481b752a9ea058cce3d9b025d040a87cTilo Mitra eventName:"click"
a31d4503481b752a9ea058cce3d9b025d040a87cTilo Mitra<p>Similarly, the "focusOn" attribute can be changed to configure the default focus behavior</p>
a31d4503481b752a9ea058cce3d9b025d040a87cTilo Mitra var panel = new Y.Panel({
a31d4503481b752a9ea058cce3d9b025d040a87cTilo Mitra srcNode: "#myPanelContent",
a31d4503481b752a9ea058cce3d9b025d040a87cTilo Mitra centered: true,
a31d4503481b752a9ea058cce3d9b025d040a87cTilo Mitra modal:false,
a31d4503481b752a9ea058cce3d9b025d040a87cTilo Mitra //The focusOn Attribute takes an array of objects, with a required property "eventName"
a31d4503481b752a9ea058cce3d9b025d040a87cTilo Mitra //and two optional properties "node", and "keyCode"
a31d4503481b752a9ea058cce3d9b025d040a87cTilo Mitra //When we don't specify a node, it defaults to the boundingbox of this panel instance
a31d4503481b752a9ea058cce3d9b025d040a87cTilo Mitra eventName: "clickoutside"
a31d4503481b752a9ea058cce3d9b025d040a87cTilo Mitra //This listens to click events on the node that was specified
a31d4503481b752a9ea058cce3d9b025d040a87cTilo Mitra node: Y.one("#anotherNode"),
a31d4503481b752a9ea058cce3d9b025d040a87cTilo Mitra eventName:"click"
a31d4503481b752a9ea058cce3d9b025d040a87cTilo Mitra<p>To simply get rid of the default behavior, we could just set the "focusOn" and "hideOn" attributes to empty arrays.</p>
8f0dc35284b10842ef7c44ffc3d410227804fcedTilo Mitra<h2 id="buttons">Header/Footer Button Support</h2>
a31d4503481b752a9ea058cce3d9b025d040a87cTilo Mitra<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>
a31d4503481b752a9ea058cce3d9b025d040a87cTilo MitraYUI().use('panel', function(Y) {
a31d4503481b752a9ea058cce3d9b025d040a87cTilo Mitra var doSomethingElse = function() { ... };
a31d4503481b752a9ea058cce3d9b025d040a87cTilo Mitra var panel = new Y.Panel({
a31d4503481b752a9ea058cce3d9b025d040a87cTilo Mitra srcNode: "#myPanelContent",
a31d4503481b752a9ea058cce3d9b025d040a87cTilo Mitra centered: true,
a31d4503481b752a9ea058cce3d9b025d040a87cTilo Mitra //make changes to the buttons through the "buttons" attribute, which takes an array of objects
a31d4503481b752a9ea058cce3d9b025d040a87cTilo Mitra //each object has a "value" property, which can be text or an HTML string,
a31d4503481b752a9ea058cce3d9b025d040a87cTilo Mitra value: "Okay",
a31d4503481b752a9ea058cce3d9b025d040a87cTilo Mitra // "defaultFn" which takes the function that should be executed on a click event
a31d4503481b752a9ea058cce3d9b025d040a87cTilo Mitra defaultFn: function(e) {
a31d4503481b752a9ea058cce3d9b025d040a87cTilo Mitra doSomethingElse();
a31d4503481b752a9ea058cce3d9b025d040a87cTilo Mitra // "section" which tells where to render the button and should be Y.WidgetStdMod.HEADER, or Y.WidgetStdMod.FOOTER
a31d4503481b752a9ea058cce3d9b025d040a87cTilo Mitra //plus an optional "href" property if you are linking to an URL
a31d4503481b752a9ea058cce3d9b025d040a87cTilo Mitra<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.
a31d4503481b752a9ea058cce3d9b025d040a87cTilo Mitra var cancelButton = {
a31d4503481b752a9ea058cce3d9b025d040a87cTilo Mitra value: "Cancel",
a31d4503481b752a9ea058cce3d9b025d040a87cTilo Mitra defaultFn: function(e) {
a31d4503481b752a9ea058cce3d9b025d040a87cTilo Mitra cancelActions();
84765788c559bfdead67172a79759ac60c77231bTilo Mitra section: Y.WidgetStdMod.FOOTER //we could also write "header", "footer" or Y.WidgetStdMod.HEADER here.