Upgrade to ExtJS 3.3.1 - Released 11/30/2010
[extjs.git] / docs / source / CardLayout.html
1 <html>
2 <head>
3   <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />    
4   <title>The source code</title>
5     <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />
6     <script type="text/javascript" src="../resources/prettify/prettify.js"></script>
7 </head>
8 <body  onload="prettyPrint();">
9     <pre class="prettyprint lang-js">/*!
10  * Ext JS Library 3.3.1
11  * Copyright(c) 2006-2010 Sencha Inc.
12  * licensing@sencha.com
13  * http://www.sencha.com/license
14  */
15 <div id="cls-Ext.layout.CardLayout"></div>/**
16  * @class Ext.layout.CardLayout
17  * @extends Ext.layout.FitLayout
18  * <p>This layout manages multiple child Components, each fitted to the Container, where only a single child Component can be
19  * visible at any given time.  This layout style is most commonly used for wizards, tab implementations, etc.
20  * This class is intended to be extended or created via the layout:'card' {@link Ext.Container#layout} config,
21  * and should generally not need to be created directly via the new keyword.</p>
22  * <p>The CardLayout's focal method is {@link #setActiveItem}.  Since only one panel is displayed at a time,
23  * the only way to move from one Component to the next is by calling setActiveItem, passing the id or index of
24  * the next panel to display.  The layout itself does not provide a user interface for handling this navigation,
25  * so that functionality must be provided by the developer.</p>
26  * <p>In the following example, a simplistic wizard setup is demonstrated.  A button bar is added
27  * to the footer of the containing panel to provide navigation buttons.  The buttons will be handled by a
28  * common navigation routine -- for this example, the implementation of that routine has been ommitted since
29  * it can be any type of custom logic.  Note that other uses of a CardLayout (like a tab control) would require a
30  * completely different implementation.  For serious implementations, a better approach would be to extend
31  * CardLayout to provide the custom functionality needed.  Example usage:</p>
32  * <pre><code>
33 var navHandler = function(direction){
34     // This routine could contain business logic required to manage the navigation steps.
35     // It would call setActiveItem as needed, manage navigation button state, handle any
36     // branching logic that might be required, handle alternate actions like cancellation
37     // or finalization, etc.  A complete wizard implementation could get pretty
38     // sophisticated depending on the complexity required, and should probably be
39     // done as a subclass of CardLayout in a real-world implementation.
40 };
41
42 var card = new Ext.Panel({
43     title: 'Example Wizard',
44     layout:'card',
45     activeItem: 0, // make sure the active item is set on the container config!
46     bodyStyle: 'padding:15px',
47     defaults: {
48         // applied to each contained panel
49         border:false
50     },
51     // just an example of one possible navigation scheme, using buttons
52     bbar: [
53         {
54             id: 'move-prev',
55             text: 'Back',
56             handler: navHandler.createDelegate(this, [-1]),
57             disabled: true
58         },
59         '->', // greedy spacer so that the buttons are aligned to each side
60         {
61             id: 'move-next',
62             text: 'Next',
63             handler: navHandler.createDelegate(this, [1])
64         }
65     ],
66     // the panels (or "cards") within the layout
67     items: [{
68         id: 'card-0',
69         html: '&lt;h1&gt;Welcome to the Wizard!&lt;/h1&gt;&lt;p&gt;Step 1 of 3&lt;/p&gt;'
70     },{
71         id: 'card-1',
72         html: '&lt;p&gt;Step 2 of 3&lt;/p&gt;'
73     },{
74         id: 'card-2',
75         html: '&lt;h1&gt;Congratulations!&lt;/h1&gt;&lt;p&gt;Step 3 of 3 - Complete&lt;/p&gt;'
76     }]
77 });
78 </code></pre>
79  */
80 Ext.layout.CardLayout = Ext.extend(Ext.layout.FitLayout, {
81     <div id="cfg-Ext.layout.CardLayout-deferredRender"></div>/**
82      * @cfg {Boolean} deferredRender
83      * True to render each contained item at the time it becomes active, false to render all contained items
84      * as soon as the layout is rendered (defaults to false).  If there is a significant amount of content or
85      * a lot of heavy controls being rendered into panels that are not displayed by default, setting this to
86      * true might improve performance.
87      */
88     deferredRender : false,
89
90     <div id="cfg-Ext.layout.CardLayout-layoutOnCardChange"></div>/**
91      * @cfg {Boolean} layoutOnCardChange
92      * True to force a layout of the active item when the active card is changed. Defaults to false.
93      */
94     layoutOnCardChange : false,
95
96     <div id="cfg-Ext.layout.CardLayout-renderHidden"></div>/**
97      * @cfg {Boolean} renderHidden @hide
98      */
99     // private
100     renderHidden : true,
101
102     type: 'card',
103
104     <div id="method-Ext.layout.CardLayout-setActiveItem"></div>/**
105      * Sets the active (visible) item in the layout.
106      * @param {String/Number} item The string component id or numeric index of the item to activate
107      */
108     setActiveItem : function(item){
109         var ai = this.activeItem,
110             ct = this.container;
111         item = ct.getComponent(item);
112
113         // Is this a valid, different card?
114         if(item && ai != item){
115
116             // Changing cards, hide the current one
117             if(ai){
118                 ai.hide();
119                 if (ai.hidden !== true) {
120                     return false;
121                 }
122                 ai.fireEvent('deactivate', ai);
123             }
124
125             var layout = item.doLayout && (this.layoutOnCardChange || !item.rendered);
126
127             // Change activeItem reference
128             this.activeItem = item;
129
130             // The container is about to get a recursive layout, remove any deferLayout reference
131             // because it will trigger a redundant layout.
132             delete item.deferLayout;
133
134             // Show the new component
135             item.show();
136
137             this.layout();
138
139             if(layout){
140                 item.doLayout();
141             }
142             item.fireEvent('activate', item);
143         }
144     },
145
146     // private
147     renderAll : function(ct, target){
148         if(this.deferredRender){
149             this.renderItem(this.activeItem, undefined, target);
150         }else{
151             Ext.layout.CardLayout.superclass.renderAll.call(this, ct, target);
152         }
153     }
154 });
155 Ext.Container.LAYOUTS['card'] = Ext.layout.CardLayout;
156 </pre>    
157 </body>
158 </html>