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 {@link Ext.container.Container}, capable + * of being configured with a {@link Ext.container.Container#layout layout}, and containing child Components.
+ *When either specifying child {@link Ext.Component#items items} of a Panel, or dynamically {@link Ext.container.Container#add 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 {@link Ext.container.Container#layout layout} schemes. By
+ * default, Panels use the {@link Ext.layout.container.Auto 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 {@link #bbar bottom} and {@link #tbar top} toolbars, along with separate + * {@link #header}, {@link #footer} and {@link #body} sections (see {@link #frame} for additional + * information).
+ *Panel also provides built-in {@link #collapsible collapsible, expandable} and {@link #closable} behavior. + * Panels can be easily dropped into any {@link Ext.container.Container Container} or layout, and the + * layout and rendering pipeline is {@link Ext.container.Container#add completely managed by the framework}.
+ *Note: By default, the {@link #closable 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 {@link #closeAction 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 {@link #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: document.body
+});
+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
+ title: 'Filters',
+ items: [{
+ xtype: 'datefield',
+ fieldLabel: 'Start date'
+ }, {
+ xtype: 'datefield',
+ fieldLabel: 'End date'
+ }]
+});
+Note that the Panel above is not configured to render into the document, nor is it configured with a size or position. In a real world scenario, + * the Container into which the Panel is added will use a {@link #layout} to render, size and position its child Components.
+ *Panels will often use specific {@link #layout}s 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: document.body,
+ 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)
+ }]
+});
+flex value to distribute available space proportionately.
+ * This Panel itself may be a child item of, for exaple, a {@link 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.
+ * @constructor + * @param {Object} config The config object + * @xtype panel + */ +Ext.define('Ext.panel.Panel', { + extend: 'Ext.panel.AbstractPanel', + requires: [ + 'Ext.panel.Header', + 'Ext.fx.Anim', + 'Ext.util.KeyMap', + 'Ext.panel.DD', + 'Ext.XTemplate', + 'Ext.layout.component.Dock' + ], + alias: 'widget.panel', + alternateClassName: 'Ext.Panel', + + /** + * @cfg {String} collapsedCls + * A CSS class to add to the panel's element after it has been collapsed (defaults to + *'collapsed').
+ */
+ collapsedCls: 'collapsed',
+
+ /**
+ * @cfg {Boolean} animCollapse
+ * true to animate the transition when the panel is collapsed, false to skip the
+ * animation (defaults to true if the {@link Ext.fx.Anim} class is available, otherwise false).
+ * May also be specified as the animation duration in milliseconds.
+ */
+ animCollapse: Ext.enableFx,
+
+ /**
+ * @cfg {Number} minButtonWidth
+ * Minimum width of all footer toolbar buttons in pixels (defaults to 75). If set, this will
+ * be used as the default value for the {@link Ext.button.Button#minWidth} config of
+ * each Button added to the footer toolbar via the {@link #fbar} or {@link #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 {@link Ext.container.Container#config-defaults defaults} of their parent container.
+ */
+ minButtonWidth: 75,
+
+ /**
+ * @cfg {Boolean} collapsed
+ * true to render the panel collapsed, false to render it expanded (defaults to
+ * false).
+ */
+ collapsed: false,
+
+ /**
+ * @cfg {Boolean} 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).
+ */
+ collapseFirst: true,
+
+ /**
+ * @cfg {Boolean} hideCollapseTool
+ * true to hide the expand/collapse toggle button when {@link #collapsible} == true,
+ * false to display it (defaults to false).
+ */
+ hideCollapseTool: false,
+
+ /**
+ * @cfg {Boolean} titleCollapse
+ * true to allow expanding and collapsing the panel (when {@link #collapsible} = true)
+ * by clicking anywhere in the header bar, false) to allow it only by clicking to tool button
+ * (defaults to false)).
+ */
+ titleCollapse: false,
+
+ /**
+ * @cfg {String} collapseMode
+ * Important: this config is only effective for {@link #collapsible} Panels which are direct child items of a {@link Ext.layout.container.Border border layout}.
+ *When not a direct child item of a {@link Ext.layout.container.Border 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 {@link #collapseDirection}) will be inserted to show a the title and a re-expand tool.
+ *When a child item of a {@link Ext.layout.container.Border border layout}, this config has two options: + *
undefined/omittedheader : Important: This config is only effective for {@link #collapsible} Panels which are direct child items of a {@link Ext.layout.container.Border border layout}
+ * when not using the 'header' {@link #collapseMode}.
Optional. A Component (or config object for a Component) to show in place of this Panel when this Panel is collapsed by a + * {@link Ext.layout.container.Border border layout}. Defaults to a generated {@link Ext.panel.Header Header} + * containing a {@link Ext.panel.Tool Tool} to re-expand the Panel.
+ */ + + /** + * @cfg {Boolean} floatable + *Important: This config is only effective for {@link #collapsible} Panels which are direct child items of a {@link Ext.layout.container.Border border layout}.
+ * true to allow clicking a collapsed Panel's {@link #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). + */ + floatable: true, + + /** + * @cfg {Boolean} 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 (defaults to false).
+ * See {@link #collapseMode} and {@link #collapseDirection} + */ + collapsible: false, + + /** + * @cfg {Boolean} collapseDirection + *The direction to collapse the Panel when the toggle button is clicked.
+ *Defaults to the {@link #headerPosition}
+ *Important: This config is ignored for {@link #collapsible} Panels which are direct child items of a {@link Ext.layout.container.Border border layout}.
+ *Specify as 'top', 'bottom', 'left' or 'right'.
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 (defaults to false).
By default, when close is requested by clicking the close button in the header, the {@link #close} + * method will be called. This will {@link Ext.Component#destroy 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 + * {@link #closeAction} to 'hide'.
+ */ + closable: false, + + /** + * @cfg {String} closeAction + *The action to take when the close header tool is clicked: + *
'{@link #destroy}' : Default'{@link #hide}' : Note: This behavior has changed! setting *does* affect the {@link #close} method + * which will invoke the approriate closeAction. + */ + closeAction: 'destroy', + + /** + * @cfg {Object/Array} dockedItems + * A component or series of components to be added as docked items to this panel. + * The docked items can be docked to either the top, right, left or bottom of a panel. + * This is typically used for things like toolbars or tab bars: + *
+var panel = new Ext.panel.Panel({
+ dockedItems: [{
+ xtype: 'toolbar',
+ dock: 'top',
+ items: [{
+ text: 'Docked to the top'
+ }]
+ }]
+});'top', 'bottom', 'left' or 'right'. Defaults to 'top'.
+ */
+ headerPosition: 'top',
+
+ /**
+ * @cfg {Boolean} frame
+ * True to apply a frame to the panel.
+ */
+ frame: false,
+
+ /**
+ * @cfg {Boolean} frameHeader
+ * True to apply a frame to the panel panels header (if 'frame' is true).
+ */
+ frameHeader: true,
+
+ /**
+ * @cfg {Array} tools
+ * An array of {@link 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 {@link #down} and {#query}, as well as the other
+ * component methods. The toggle tool is automatically created if {@link #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',
+ qtip: 'Refresh form Data',
+ // hidden:true,
+ handler: function(event, toolEl, panel){
+ // refresh logic
+ }
+},
+{
+ type:'help',
+ qtip: 'Get Help',
+ handler: function(event, toolEl, panel){
+ // show help here
+ }
+}]
+Closes the Panel. By default, this method, removes it from the DOM, {@link Ext.Component#destroy destroy}s + * the Panel object and all its descendant Components. The {@link #beforeclose beforeclose} + * event is fired before the close happens and will cancel the close action if it returns false.
+ *
Note: This method is not affected by the {@link #closeAction} setting which + * only affects the action triggered when clicking the {@link #closable 'close' tool in the header}. + * To hide the Panel without destroying it, call {@link #hide}.
+ */ + close: function() { + if (this.fireEvent('beforeclose', this) !== false) { + this.doClose(); + } + }, + + // private + doClose: function() { + this.fireEvent('close', this); + this[this.closeAction](); + }, + + onRender: function(ct, position) { + var me = this, + topContainer; + + // Add class-specific header tools. + // Panel adds collapsible and closable. + me.initTools(); + + // Dock the header/title + me.updateHeader(); + + // If initially collapsed, collapsed flag must indicate true current state at this point. + // Do collapse after the first time the Panel's structure has been laid out. + if (me.collapsed) { + me.collapsed = false; + topContainer = me.findLayoutController(); + if (!me.hidden && topContainer) { + topContainer.on({ + afterlayout: function() { + me.collapse(null, false, true); + }, + single: true + }); + } else { + me.afterComponentLayout = function() { + delete me.afterComponentLayout; + Ext.getClass(me).prototype.afterComponentLayout.apply(me, arguments); + me.collapse(null, false, true); + }; + } + } + + // Call to super after adding the header, to prevent an unnecessary re-layout + me.callParent(arguments); + }, + + /** + * Create, hide, or show the header component as appropriate based on the current config. + * @private + * @param {Boolean} force True to force the the header to be created + */ + updateHeader: function(force) { + var me = this, + header = me.header, + title = me.title, + tools = me.tools; + + if (!me.preventHeader && (force || title || (tools && tools.length))) { + if (!header) { + header = me.header = Ext.create('Ext.panel.Header', { + title : title, + orientation : (me.headerPosition == 'left' || me.headerPosition == 'right') ? 'vertical' : 'horizontal', + dock : me.headerPosition || 'top', + textCls : me.headerTextCls, + iconCls : me.iconCls, + baseCls : me.baseCls + '-header', + tools : tools, + ui : me.ui, + indicateDrag: me.draggable, + border : me.border, + frame : me.frame && me.frameHeader, + ignoreParentFrame : me.frame || me.overlapHeader, + ignoreBorderManagement: me.frame || me.ignoreHeaderBorderManagement, + listeners : me.collapsible && me.titleCollapse ? { + click: me.toggleCollapse, + scope: me + } : null + }); + me.addDocked(header, 0); + + // Reference the Header's tool array. + // Header injects named references. + me.tools = header.tools; + } + header.show(); + me.initHeaderAria(); + } else if (header) { + header.hide(); + } + }, + + // inherit docs + setUI: function(ui) { + var me = this; + + me.callParent(arguments); + + if (me.header) { + me.header.setUI(ui); + } + }, + + // private + getContentTarget: function() { + return this.body; + }, + + getTargetEl: function() { + return this.body || this.frameBody || this.el; + }, + + addTool: function(tool) { + this.tools.push(tool); + var header = this.header; + if (header) { + header.addTool(tool); + } + this.updateHeader(); + }, + + getOppositeDirection: function(d) { + var c = Ext.Component; + switch (d) { + case c.DIRECTION_TOP: + return c.DIRECTION_BOTTOM; + case c.DIRECTION_RIGHT: + return c.DIRECTION_LEFT; + case c.DIRECTION_BOTTOM: + return c.DIRECTION_TOP; + case c.DIRECTION_LEFT: + return c.DIRECTION_RIGHT; + } + }, + + /** + * 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 {@link #beforecollapse} event which will + * cancel the collapse action if it returns false. + * @param {Number} direction. The direction to collapse towards. Must be one ofIf this Panel is configured {@link #draggable}, this property will contain + * an instance of {@link Ext.dd.DragSource} which handles dragging the Panel.
+ * The developer must provide implementations of the abstract methods of {@link Ext.dd.DragSource} + * in order to supply behaviour for each stage of the drag/drop process. See {@link #draggable}. + * @type Ext.dd.DragSource. + * @property dd + */ + this.dd = Ext.create('Ext.panel.DD', this, Ext.isBoolean(this.draggable) ? null : this.draggable); + }, + + // private - helper function for ghost + ghostTools : function() { + var tools = [], + origTools = this.initialConfig.tools; + + if (origTools) { + Ext.each(origTools, function(tool) { + // Some tools can be full components, and copying them into the ghost + // actually removes them from the owning panel. You could also potentially + // end up with duplicate DOM ids as well. To avoid any issues we just make + // a simple bare-minimum clone of each tool for ghosting purposes. + tools.push({ + type: tool.type + }); + }); + } + else { + tools = [{ + type: 'placeholder' + }]; + } + return tools; + }, + + // private - used for dragging + ghost: function(cls) { + var me = this, + ghostPanel = me.ghostPanel, + box = me.getBox(); + + if (!ghostPanel) { + ghostPanel = Ext.create('Ext.panel.Panel', { + renderTo: document.body, + floating: { + shadow: false + }, + frame: Ext.supports.CSS3BorderRadius ? me.frame : false, + title: me.title, + overlapHeader: me.overlapHeader, + headerPosition: me.headerPosition, + width: me.getWidth(), + height: me.getHeight(), + iconCls: me.iconCls, + baseCls: me.baseCls, + tools: me.ghostTools(), + cls: me.baseCls + '-ghost ' + (cls ||'') + }); + me.ghostPanel = ghostPanel; + } + ghostPanel.floatParent = me.floatParent; + if (me.floating) { + ghostPanel.setZIndex(Ext.Number.from(me.el.getStyle('zIndex'), 0)); + } else { + ghostPanel.toFront(); + } + ghostPanel.el.show(); + ghostPanel.setPosition(box.x, box.y); + ghostPanel.setSize(box.width, box.height); + me.el.hide(); + if (me.floatingItems) { + me.floatingItems.hide(); + } + return ghostPanel; + }, + + // private + unghost: function(show, matchPosition) { + var me = this; + if (!me.ghostPanel) { + return; + } + if (show !== false) { + me.el.show(); + if (matchPosition !== false) { + me.setPosition(me.ghostPanel.getPosition()); + } + if (me.floatingItems) { + me.floatingItems.show(); + } + Ext.defer(me.focus, 10, me); + } + me.ghostPanel.el.hide(); + }, + + initResizable: function(resizable) { + if (this.collapsed) { + resizable.disabled = true; + } + this.callParent([resizable]); + } +});