index.mustache revision ff8b03787b79f0f9ab8c1a7fac736c5e47d02648
c45eda9efe7eb59595c39710b8446429f6e6e2d7omebold<div class="intro">
1ffe4d4351009d316898d7e79e3114b6d88a469aomebold <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>
c45eda9efe7eb59595c39710b8446429f6e6e2d7omebold<h4 id="default">Creating a Panel</h4>
c45eda9efe7eb59595c39710b8446429f6e6e2d7omebold<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>
c45eda9efe7eb59595c39710b8446429f6e6e2d7omeboldYUI().use('panel', function(Y) {
c45eda9efe7eb59595c39710b8446429f6e6e2d7omebold var panel = new Y.Panel({
c45eda9efe7eb59595c39710b8446429f6e6e2d7omebold srcNode: "#myPanelContent",
c45eda9efe7eb59595c39710b8446429f6e6e2d7omebold width: 400,
c45eda9efe7eb59595c39710b8446429f6e6e2d7omebold centered: true
c45eda9efe7eb59595c39710b8446429f6e6e2d7omebold<h4 id="modality">Modal Panel</h4>
c45eda9efe7eb59595c39710b8446429f6e6e2d7omebold<p>A Panel is modal by default. This functionality can be changed through the "modal" attribute, either during instantiation or later through the set() method.</p>
c45eda9efe7eb59595c39710b8446429f6e6e2d7omeboldYUI().use('panel', function(Y) {
c45eda9efe7eb59595c39710b8446429f6e6e2d7omebold var panel = new Y.Panel({
c45eda9efe7eb59595c39710b8446429f6e6e2d7omebold srcNode: "#myPanelContent",
c45eda9efe7eb59595c39710b8446429f6e6e2d7omebold width: 400,
c45eda9efe7eb59595c39710b8446429f6e6e2d7omebold centered: true,
c45eda9efe7eb59595c39710b8446429f6e6e2d7omebold // Don't make the panel modal
c45eda9efe7eb59595c39710b8446429f6e6e2d7omebold modal: false
c45eda9efe7eb59595c39710b8446429f6e6e2d7omebold //optionally, we could have written panel.set('modal', false);
c45eda9efe7eb59595c39710b8446429f6e6e2d7omebold<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>
4b3769ce483ece06f60f983193712492b920144fJake Feasel<h4 id="events">Choosing when to focus and hide</h4>
e7c81bf3e1adb954c93bb6cd884ec370d3c19292omebold<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>
c45eda9efe7eb59595c39710b8446429f6e6e2d7omebold<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>
c45eda9efe7eb59595c39710b8446429f6e6e2d7omeboldYUI().use('panel', function(Y) {
c45eda9efe7eb59595c39710b8446429f6e6e2d7omebold var panel = new Y.Panel({
c45eda9efe7eb59595c39710b8446429f6e6e2d7omebold srcNode: "#myPanelContent",
c45eda9efe7eb59595c39710b8446429f6e6e2d7omebold width: 400,
4bdbfccf9a86f2e46d0aa1e89c88fb6f017082a6Lana centered: true,
4bdbfccf9a86f2e46d0aa1e89c88fb6f017082a6Lana modal:false,
4bdbfccf9a86f2e46d0aa1e89c88fb6f017082a6Lana //The hideOn Attribute takes an array of objects, with a required property "eventName"
4bdbfccf9a86f2e46d0aa1e89c88fb6f017082a6Lana //and two optional properties "node", and "keyCode"
35d5aee48705598166a6bdf9185894a73f172bbbLaurent Bristiel //When we don't specify a node, it defaults to the boundingbox of this panel instance
35d5aee48705598166a6bdf9185894a73f172bbbLaurent Bristiel eventName: "clickoutside"
35d5aee48705598166a6bdf9185894a73f172bbbLaurent Bristiel //This listens to click events on the node that was specified
4bdbfccf9a86f2e46d0aa1e89c88fb6f017082a6Lana node: Y.one("#anotherNode"),
4bdbfccf9a86f2e46d0aa1e89c88fb6f017082a6Lana eventName:"click"
4bdbfccf9a86f2e46d0aa1e89c88fb6f017082a6Lana<p>Similarly, the "focusOn" attribute can be changed to configure the default focus behavior</p>
c45eda9efe7eb59595c39710b8446429f6e6e2d7omebold var panel = new Y.Panel({
c45eda9efe7eb59595c39710b8446429f6e6e2d7omebold srcNode: "#myPanelContent",
c45eda9efe7eb59595c39710b8446429f6e6e2d7omebold width: 400,
c45eda9efe7eb59595c39710b8446429f6e6e2d7omebold centered: true,
c45eda9efe7eb59595c39710b8446429f6e6e2d7omebold modal:false,
c45eda9efe7eb59595c39710b8446429f6e6e2d7omebold //The focusOn Attribute takes an array of objects, with a required property "eventName"
c45eda9efe7eb59595c39710b8446429f6e6e2d7omebold //and two optional properties "node", and "keyCode"
c45eda9efe7eb59595c39710b8446429f6e6e2d7omebold //When we don't specify a node, it defaults to the boundingbox of this panel instance
c45eda9efe7eb59595c39710b8446429f6e6e2d7omebold eventName: "clickoutside"
c45eda9efe7eb59595c39710b8446429f6e6e2d7omebold //This listens to click events on the node that was specified
c45eda9efe7eb59595c39710b8446429f6e6e2d7omebold node: Y.one("#anotherNode"),
c45eda9efe7eb59595c39710b8446429f6e6e2d7omebold eventName:"click"
c45eda9efe7eb59595c39710b8446429f6e6e2d7omebold<p>To simply get rid of the default behavior, we could just set the "focusOn" and "hideOn" attributes to empty arrays.</p>
c45eda9efe7eb59595c39710b8446429f6e6e2d7omebold<h4 id="buttons">Header/Footer Button Support</h4>
c45eda9efe7eb59595c39710b8446429f6e6e2d7omebold<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>
c45eda9efe7eb59595c39710b8446429f6e6e2d7omeboldYUI().use('panel', function(Y) {
c45eda9efe7eb59595c39710b8446429f6e6e2d7omebold var doSomethingElse = function() { ... };
c45eda9efe7eb59595c39710b8446429f6e6e2d7omebold var panel = new Y.Panel({
c45eda9efe7eb59595c39710b8446429f6e6e2d7omebold srcNode: "#myPanelContent",
c45eda9efe7eb59595c39710b8446429f6e6e2d7omebold width: 400,
c45eda9efe7eb59595c39710b8446429f6e6e2d7omebold centered: true,
c45eda9efe7eb59595c39710b8446429f6e6e2d7omebold //make changes to the buttons through the "buttons" attribute, which takes an array of objects
c45eda9efe7eb59595c39710b8446429f6e6e2d7omebold //each object has a "value" property, which can be text or an HTML string,
c45eda9efe7eb59595c39710b8446429f6e6e2d7omebold value: "Okay",
c45eda9efe7eb59595c39710b8446429f6e6e2d7omebold // "defaultFn" which takes the function that should be executed on a click event
c45eda9efe7eb59595c39710b8446429f6e6e2d7omebold defaultFn: function(e) {
c45eda9efe7eb59595c39710b8446429f6e6e2d7omebold doSomethingElse();
c45eda9efe7eb59595c39710b8446429f6e6e2d7omebold // "section" which tells where to render the button and should be Y.WidgetStdMod.HEADER, or Y.WidgetStdMod.FOOTER
c45eda9efe7eb59595c39710b8446429f6e6e2d7omebold //plus an optional "href" property if you are linking to an URL
c45eda9efe7eb59595c39710b8446429f6e6e2d7omebold<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.
c45eda9efe7eb59595c39710b8446429f6e6e2d7omebold var cancelButton = {
c45eda9efe7eb59595c39710b8446429f6e6e2d7omebold value: "Cancel",
c45eda9efe7eb59595c39710b8446429f6e6e2d7omebold defaultFn: function(e) {
c45eda9efe7eb59595c39710b8446429f6e6e2d7omebold cancelActions();
c45eda9efe7eb59595c39710b8446429f6e6e2d7omebold panel.addButton(cancelButton);