3 * Copyright(c) 2006-2010 Ext JS, Inc.
5 * http://www.extjs.com/license
8 * @class Ext.layout.CardLayout
9 * @extends Ext.layout.FitLayout
10 * <p>This layout manages multiple child Components, each fitted to the Container, where only a single child Component can be
11 * visible at any given time. This layout style is most commonly used for wizards, tab implementations, etc.
12 * This class is intended to be extended or created via the layout:'card' {@link Ext.Container#layout} config,
13 * and should generally not need to be created directly via the new keyword.</p>
14 * <p>The CardLayout's focal method is {@link #setActiveItem}. Since only one panel is displayed at a time,
15 * the only way to move from one Component to the next is by calling setActiveItem, passing the id or index of
16 * the next panel to display. The layout itself does not provide a user interface for handling this navigation,
17 * so that functionality must be provided by the developer.</p>
18 * <p>In the following example, a simplistic wizard setup is demonstrated. A button bar is added
19 * to the footer of the containing panel to provide navigation buttons. The buttons will be handled by a
20 * common navigation routine -- for this example, the implementation of that routine has been ommitted since
21 * it can be any type of custom logic. Note that other uses of a CardLayout (like a tab control) would require a
22 * completely different implementation. For serious implementations, a better approach would be to extend
23 * CardLayout to provide the custom functionality needed. Example usage:</p>
25 var navHandler = function(direction){
26 // This routine could contain business logic required to manage the navigation steps.
27 // It would call setActiveItem as needed, manage navigation button state, handle any
28 // branching logic that might be required, handle alternate actions like cancellation
29 // or finalization, etc. A complete wizard implementation could get pretty
30 // sophisticated depending on the complexity required, and should probably be
31 // done as a subclass of CardLayout in a real-world implementation.
34 var card = new Ext.Panel({
35 title: 'Example Wizard',
37 activeItem: 0, // make sure the active item is set on the container config!
38 bodyStyle: 'padding:15px',
40 // applied to each contained panel
43 // just an example of one possible navigation scheme, using buttons
48 handler: navHandler.createDelegate(this, [-1]),
51 '->', // greedy spacer so that the buttons are aligned to each side
55 handler: navHandler.createDelegate(this, [1])
58 // the panels (or "cards") within the layout
61 html: '<h1>Welcome to the Wizard!</h1><p>Step 1 of 3</p>'
64 html: '<p>Step 2 of 3</p>'
67 html: '<h1>Congratulations!</h1><p>Step 3 of 3 - Complete</p>'
72 Ext.layout.CardLayout = Ext.extend(Ext.layout.FitLayout, {
74 * @cfg {Boolean} deferredRender
75 * True to render each contained item at the time it becomes active, false to render all contained items
76 * as soon as the layout is rendered (defaults to false). If there is a significant amount of content or
77 * a lot of heavy controls being rendered into panels that are not displayed by default, setting this to
78 * true might improve performance.
80 deferredRender : false,
83 * @cfg {Boolean} layoutOnCardChange
84 * True to force a layout of the active item when the active card is changed. Defaults to false.
86 layoutOnCardChange : false,
89 * @cfg {Boolean} renderHidden @hide
97 * Sets the active (visible) item in the layout.
98 * @param {String/Number} item The string component id or numeric index of the item to activate
100 setActiveItem : function(item){
101 var ai = this.activeItem,
103 item = ct.getComponent(item);
105 // Is this a valid, different card?
106 if(item && ai != item){
108 // Changing cards, hide the current one
111 if (ai.hidden !== true) {
114 ai.fireEvent('deactivate', ai);
117 var layout = item.doLayout && (this.layoutOnCardChange || !item.rendered);
119 // Change activeItem reference
120 this.activeItem = item;
122 // The container is about to get a recursive layout, remove any deferLayout reference
123 // because it will trigger a redundant layout.
124 delete item.deferLayout;
126 // Show the new component
134 item.fireEvent('activate', item);
139 renderAll : function(ct, target){
140 if(this.deferredRender){
141 this.renderItem(this.activeItem, undefined, target);
143 Ext.layout.CardLayout.superclass.renderAll.call(this, ct, target);
147 Ext.Container.LAYOUTS['card'] = Ext.layout.CardLayout;