Clear Up
SharpKit Reference

Panel Class

Panel is a container that has specific functionality and structural components that make it the perfect building block for application-oriented user interfaces.

Panels are, by virtue of their inheritance from Ext.container.Container, capable of being configured with a layout, and containing child Components.

When either specifying child items of a Panel, or dynamically adding Components to a Panel, remember to consider how you wish the Panel to arrange those child elements, and whether those child elements need to be sized using one of Ext's built-in layout schemes. By default, Panels use the Auto scheme. This simply renders child components, appending them one after the other inside the Container, and does not apply any sizing at all.

A Panel may also contain bottom and top toolbars, along with separate header, footer and body sections.

Panel also provides built-in collapsible, expandable and closable behavior. Panels can be easily dropped into any Container or layout, and the layout and rendering pipeline is completely managed by the framework.

Note: By default, the close header tool destroys the Panel resulting in removal of the Panel and the destruction of any descendant Components. This makes the Panel object, and all its descendants unusable. To enable the close tool to simply hide a Panel for later re-use, configure the Panel with closeAction: 'hide'.

Usually, Panels are used as constituents within an application, in which case, they would be used as child items of Containers, and would themselves use Ext.Components as child items. However to illustrate simply rendering a Panel into the document, here's how to do it:

  
    Ext.create('Ext.panel.Panel', {
            title: 'Hello',
            width: 200,
            html: '<p>World!</p>',
            renderTo: Ext.getBody()
            });
            

A more realistic scenario is a Panel created to house input fields which will not be rendered, but used as a constituent part of a Container:

  
var filterPanel = Ext.create('Ext.panel.Panel', {
            bodyPadding: 5,  // Don't want content to crunch against the borders
            width: 300,
            title: 'Filters',
            items: [{
            xtype: 'datefield',
            fieldLabel: 'Start date'
            }, {
            xtype: 'datefield',
            fieldLabel: 'End date'
            }],
            renderTo: Ext.getBody()
            });
            

Note that the Panel above is configured to render into the document and assigned a size. In a real world scenario, the Panel will often be added inside a Container which will use a layout to render, size and position its child Components.

Panels will often use specific layouts to provide an application with shape and structure by containing and arranging child Components:

  
var resultsPanel = Ext.create('Ext.panel.Panel', {
            title: 'Results',
            width: 600,
            height: 400,
            renderTo: Ext.getBody(),
            layout: {
            type: 'vbox',       // Arrange child items vertically
            align: 'stretch',    // Each takes up full width
            padding: 5
            },
            items: [{               // Results grid specified as a config object with an xtype of 'grid'
            xtype: 'grid',
            columns: [{header: 'Column One'}],            // One header just for show. There's no data,
            store: Ext.create('Ext.data.ArrayStore', {}), // A dummy empty data store
            flex: 1                                       // Use 1/3 of Container's height (hint to Box layout)
            }, {
            xtype: 'splitter'   // A splitter between the two child items
            }, {                    // Details Panel specified as a config object (no xtype defaults to 'panel').
            title: 'Details',
            bodyPadding: 5,
            items: [{
            fieldLabel: 'Data item',
            xtype: 'textfield'
            }], // An array of form fields
            flex: 2             // Use 2/3 of Container's height (hint to Box layout)
            }]
            });
            

The example illustrates one possible method of displaying search results. The Panel contains a grid with the resulting data arranged in rows. Each selected row may be displayed in detail in the Panel below. The vbox layout is used to arrange the two vertically. It is configured to stretch child items horizontally to full width. Child items may either be configured with a numeric height, or with a flex value to distribute available space proportionately.

This Panel itself may be a child item of, for exaple, a Ext.tab.Panel which will size its child items to fit within its content area.

Using these techniques, as long as the layout is chosen and configured correctly, an application may have any level of nested containment, all dynamically sized according to configuration, the user's preference and available browser size.

Namespace: Ext.panel

Constructors

Methods

Name Description
addTools() Template method to be implemented in subclasses to add their tools after the collapsible tool.

This is a template method. a hook into the functionality of this class. Feel free to override it in child classes.

afterCollapse(bool) Invoked after the Panel is Collapsed.

This is a template method. a hook into the functionality of this class. Feel free to override it in child classes.

afterExpand(bool) Invoked after the Panel is Expanded.

This is a template method. a hook into the functionality of this class. Feel free to override it in child classes.

close() Closes the Panel. By default, this method, removes it from the DOM, destroys the Panel object and all its descendant Components. The beforeclose event is fired before the close happens and will cancel the close action if it returns false. Note: This method is also affected by the closeAction setting. For more explicit control use destroy and hide methods.
collapse(object, object) Collapses the panel body so that the body becomes hidden. Docked Components parallel to the border towards which the collapse takes place will remain visible. Fires the beforecollapse event which will cancel the collapse action if it returns false.
expand(object) Expands the panel body so that it becomes visible. Fires the beforeexpand event which will cancel the expand action if it returns false.
getCollapsed() Returns the current collapsed state of the panel.
getHeader() Gets the Header for this panel.
setIcon(JsString) Set the icon for the panel's header. See Ext.panel.Header.icon. It will fire the iconchange event after completion.
setIconCls(JsString) Set the iconCls for the panel's header. See Ext.panel.Header.iconCls. It will fire the iconclschange event after completion.
setTitle(JsString) Set a title for the panel's header. See Ext.panel.Header.title.
toggleCollapse() Shortcut for performing an expand or collapse based on the current state of the panel.

Fields

Name Description
animCollapse true to animate the transition when the panel is collapsed, false to skip the animation (defaults to true if the Ext.fx.Anim class is available, otherwise false). May also be specified as the animation duration in milliseconds.
bbar Convenience config. Short for 'Bottom Bar'.
bbar: [
            { xtype: 'button', text: 'Button 1' }
            ]
            
is equivalent to
dockedItems: [{
            xtype: 'toolbar',
            dock: 'bottom',
            items: [
            { xtype: 'button', text: 'Button 1' }
            ]
            }]
            
buttonAlign The alignment of any buttons added to this panel. Valid values are 'right', 'left' and 'center' (defaults to 'right' for buttons/fbar, 'left' for other toolbar types). NOTE: The prefered way to specify toolbars is to use the dockedItems config. Instead of buttonAlign you would add the layout: { pack: 'start' | 'center' | 'end' } option to the dockedItem config.
buttons Convenience config used for adding buttons docked to the bottom of the panel. This is a synonym for the fbar config.
buttons: [
            { text: 'Button 1' }
            ]
            
is equivalent to
dockedItems: [{
            xtype: 'toolbar',
            dock: 'bottom',
            ui: 'footer',
            defaults: {minWidth: minButtonWidth},
            items: [
            { xtype: 'component', flex: 1 },
            { xtype: 'button', text: 'Button 1' }
            ]
            }]
            
The minButtonWidth is used as the default minWidth for each of the buttons in the buttons toolbar.
closable True to display the 'close' tool button and allow the user to close the window, false to hide the button and disallow closing the window. By default, when close is requested by clicking the close button in the header, the close method will be called. This will destroy the Panel and its content meaning that it may not be reused. To make closing a Panel hide the Panel so that it may be reused, set closeAction to 'hide'. Defaults to: false
closeAction The action to take when the close header tool is clicked:
  • 'destroy' :

    remove the window from the DOM and destroy it and all descendant Components. The window will not be available to be redisplayed via the show method.

  • 'hide' :

    hide the window by setting visibility to hidden and applying negative offsets. The window will be available to be redisplayed via the show method.

  • Note: This behavior has changed! setting does affect the close method which will invoke the approriate closeAction. Defaults to: "destroy"
    collapsed true to render the panel collapsed, false to render it expanded. Defaults to: false
    collapsedCls A CSS class to add to the panel's element after it has been collapsed. Defaults to: "collapsed"
    collapseDirection The direction to collapse the Panel when the toggle button is clicked. Defaults to the headerPositionImportant: This config is ignored for collapsible Panels which are direct child items of a border layout. Specify as 'top', 'bottom', 'left' or 'right'.
    collapseFirst true to make sure the collapse/expand toggle button always renders first (to the left of) any other tools in the panel's title bar, false to render it last. Defaults to: true
    collapseMode Important: this config is only effective for collapsible Panels which are direct child items of a border layout. When not a direct child item of a border layout, then the Panel's header remains visible, and the body is collapsed to zero dimensions. If the Panel has no header, then a new header (orientated correctly depending on the collapseDirection) will be inserted to show a the title and a re- expand tool. When a child item of a border layout, this config has three possible values:
  • undefined - When collapsed, a placeholder Header is injected into the layout to represent the Panel and to provide a UI with a Tool to allow the user to re-expand the Panel.

  • "header" - The Panel collapses to leave its header visible as when not inside a border layout.

  • "mini" - The Panel collapses without a visible header.

  • collapsible True to make the panel collapsible and have an expand/collapse toggle Tool added into the header tool button area. False to keep the panel sized either statically, or by an owning layout manager, with no toggle Tool. See collapseMode and collapseDirection Defaults to: false
    fbar Convenience config used for adding items to the bottom of the panel. Short for Footer Bar.
    fbar: [
                { type: 'button', text: 'Button 1' }
                ]
                
    is equivalent to
    dockedItems: [{
                xtype: 'toolbar',
                dock: 'bottom',
                ui: 'footer',
                defaults: {minWidth: minButtonWidth},
                items: [
                { xtype: 'component', flex: 1 },
                { xtype: 'button', text: 'Button 1' }
                ]
                }]
                
    The minButtonWidth is used as the default minWidth for each of the buttons in the fbar.
    floatable Important: This config is only effective for collapsible Panels which are direct child items of a border layout. true to allow clicking a collapsed Panel's placeholder to display the Panel floated above the layout, false to force the user to fully expand a collapsed region by clicking the expand button to see it again. Defaults to: true
    frameHeader True to apply a frame to the panel panels header (if 'frame' is true). Defaults to: true
    header Pass as false to prevent a Header from being created and shown. Pass as a config object (optionally containing an xtype) to custom-configure this Panel's header.
    headerPosition Specify as 'top', 'bottom', 'left' or 'right'. Defaults to: "top"
    hideCollapseTool true to hide the expand/collapse toggle button when collapsible == true, false to display it. Defaults to: false
    icon Path to image for an icon in the header. Used for displaying an icon to the left of a title.
    iconCls CSS class for an icon in the header. Used for displaying an icon to the left of a title.
    lbar Convenience config. Short for 'Left Bar' (left-docked, vertical toolbar).
    lbar: [
                { xtype: 'button', text: 'Button 1' }
                ]
                
    is equivalent to
    dockedItems: [{
                xtype: 'toolbar',
                dock: 'left',
                items: [
                { xtype: 'button', text: 'Button 1' }
                ]
                }]
                
    manageHeight : When true, the dock component layout writes height information to the panel's DOM elements based on its shrink wrap height calculation. This ensures that the browser respects the calculated height. When false, the dock component layout will not write heights on the panel or its body element. In some simple layout cases, not writing the heights to the DOM may be desired because this allows the browser to respond to direct DOM manipulations (like animations). Defaults to: true
    minButtonWidth Minimum width of all footer toolbar buttons in pixels. If set, this will be used as the default value for the Ext.button.Button.minWidth config of each Button added to the footer toolbar via the fbar or buttons configurations. It will be ignored for buttons that have a minWidth configured some other way, e.g. in their own config object or via the defaults of their parent container. Defaults to: 75
    overlapHeader True to overlap the header in a panel over the framing of the panel itself. This is needed when frame:true (and is done automatically for you). Otherwise it is undefined. If you manually add rounded corners to a panel header which does not have frame:true, this will need to be set to true.
    placeholder Important: This config is only effective for collapsible Panels which are direct child items of a border layout when not using the 'header' collapseMode. Optional. A Component (or config object for a Component) to show in place of this Panel when this Panel is collapsed by a border layout. Defaults to a generated Header containing a Tool to re-expand the Panel.
    placeholderCollapseHideMode The mode for hiding collapsed panels when using collapseMode "placeholder".
    preventHeader Defaults to: false

    This cfg has been deprecated

    4.1.0 Use header instead. Prevent a Header from being created and shown.

    rbar Convenience config. Short for 'Right Bar' (right-docked, vertical toolbar).
    rbar: [
                { xtype: 'button', text: 'Button 1' }
                ]
                
    is equivalent to
    dockedItems: [{
                xtype: 'toolbar',
                dock: 'right',
                items: [
                { xtype: 'button', text: 'Button 1' }
                ]
                }]
                
    tbar Convenience config. Short for 'Top Bar'.
    tbar: [
                { xtype: 'button', text: 'Button 1' }
                ]
                
    is equivalent to
    dockedItems: [{
                xtype: 'toolbar',
                dock: 'top',
                items: [
                { xtype: 'button', text: 'Button 1' }
                ]
                }]
                
    title The title text to be used to display in the panel header. When a title is specified the Ext.panel.Header will automatically be created and displayed unless header is set to false. Defaults to: ""
    titleAlign May be "left", "right" or "center". The alignment of the title text within the available space between the icon and the tools. Defaults to: "left"
    titleCollapse true to allow expanding and collapsing the panel (when collapsible = true) by clicking anywhere in the header bar, false) to allow it only by clicking to tool button). Defaults to: false
    tools An array of Ext.panel.Tool configs/instances to be added to the header tool area. The tools are stored as child components of the header container. They can be accessed using down and {query}, as well as the other component methods. The toggle tool is automatically created if collapsible is set to true. Note that, apart from the toggle tool which is provided when a panel is collapsible, these tools only provide the visual button. Any required functionality must be provided by adding handlers that implement the necessary behavior. Example usage:
    tools:[{
                type:'refresh',
                tooltip: 'Refresh form Data',
                // hidden:true,
                handler: function(event, toolEl, panel){
                // refresh logic
                }
                },
                {
                type:'help',
                tooltip: 'Get Help',
                handler: function(event, toolEl, panel){
                // show help here
                }
                }]
                

    Properties

    Name Description
    dd If this Panel is configured draggable, this property will contain an instance of Ext.dd.DragSource which handles dragging the Panel. The developer must provide implementations of the abstract methods of Ext.dd.DragSource in order to supply behaviour for each stage of the drag/drop process. See draggable.
    © Copyright 2005-2011 SharpKit. All rights reserved.