Jump to Table of Contents

Panel

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 "Creating Custom Widget Classes" example shows how you can use these extensions to build classes which mix and match some of the above features.

Getting Started

To include the source files for Panel and its dependencies, first load the YUI seed file if you haven't already loaded it. 

<script src="http://yui.yahooapis.com/3.18.1/build/yui/yui-min.js"></script>

Next, create a new YUI instance for your application and populate it with the modules you need by specifying them as arguments to the YUI().use() method. YUI will automatically load any dependencies required by the modules you specify. 

<script>
// Create a new YUI instance and populate it with the required modules.
YUI().use('panel', function (Y) {
    // Panel is available and ready for use. Add implementation
    // code here.
});
</script>

For more information on creating YUI instances and on the use() method, see the documentation for the YUI Global Object.

Note: be sure to add the yui3-skin-sam classname to the page's <body> element or to a parent element of the widget in order to apply the default CSS skin. See Understanding Skinning. 

<body class="yui3-skin-sam"> <!-- You need this skin class -->

Creating a Panel

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 disabled, and will be hidden if the esc key or "close" button is pressed. 

YUI().use('panel', function (Y) {

    var panel = new Y.Panel({
        srcNode : '#myPanelContent',
        width   : 400,
        centered: true,
        render  : true
    });

});

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. 

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);

});

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 WidgetModality extension takes care of nesting behavior so no extra code is required for the implementer. Refer to the examples for more information.

Choosing When to Focus and Hide

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.

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. 

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'
            }
        ]
    });

});

Similarly, the focusOn attribute can be changed to configure the default focus behavior. 

var panel = new Y.Panel({
    srcNode : '#myPanelContent',
    width   : 400,
    centered: true,
    modal   : false,
    render  : true,

    // The `focusOn` Attribute takes an array of objects with a required
    // `eventName` property, and optionally the `node` property.
    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'
        }
    ]
});

});

To simply get rid of the default behavior, we could just set the focusOn and hideOn attributes to empty Arrays.

Header/Footer Button Support

Panel supports header/footer buttons through the WidgetButtons and WidgetStdMod 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. 

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();

});

If you want to append buttons to the ones that are already present within the Panel, you can use the addButton() method. 

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);

Notes Regarding Older Browsers

Panel is tested across the A-grade browser set according to the GBS Browser Test Baseline as of July 2011.

However, developers implementing Panel and other components which rely on z-index support in IE6 and IE7 should be aware of the concept of stacking context. Essentially, when setting the z-index of the widget, you should ensure that the Widget's parent does not have a lower z-index.

Examples