Upgrade to ExtJS 4.0.7 - Released 10/19/2011
[extjs.git] / docs / source / Card.html
1 <!DOCTYPE html>
2 <html>
3 <head>
4   <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
5   <title>The source code</title>
6   <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />
7   <script type="text/javascript" src="../resources/prettify/prettify.js"></script>
8   <style type="text/css">
9     .highlight { display: block; background-color: #ddd; }
10   </style>
11   <script type="text/javascript">
12     function highlight() {
13       document.getElementById(location.hash.replace(/#/, "")).className = "highlight";
14     }
15   </script>
16 </head>
17 <body onload="prettyPrint(); highlight();">
18   <pre class="prettyprint lang-js"><span id='Ext-layout-container-Card'>/**
19 </span> * This layout manages multiple child Components, each fitted to the Container, where only a single child Component can be
20  * visible at any given time.  This layout style is most commonly used for wizards, tab implementations, etc.
21  * This class is intended to be extended or created via the layout:'card' {@link Ext.container.Container#layout} config,
22  * and should generally not need to be created directly via the new keyword.
23  *
24  * The CardLayout's focal method is {@link #setActiveItem}.  Since only one panel is displayed at a time,
25  * the only way to move from one Component to the next is by calling setActiveItem, passing the next panel to display
26  * (or its id or index).  The layout itself does not provide a user interface for handling this navigation,
27  * so that functionality must be provided by the developer.
28  *
29  * To change the active card of a container, call the setActiveItem method of its layout:
30  *
31  *     Ext.create('Ext.panel.Panel', {
32  *         layout: 'card',
33  *         items: [
34  *             { html: 'Card 1' },
35  *             { html: 'Card 2' }
36  *         ],
37  *         renderTo: Ext.getBody()
38  *     });
39  *
40  *     p.getLayout().setActiveItem(1);
41  *
42  * In the following example, a simplistic wizard setup is demonstrated.  A button bar is added
43  * to the footer of the containing panel to provide navigation buttons.  The buttons will be handled by a
44  * common navigation routine.  Note that other uses of a CardLayout (like a tab control) would require a
45  * completely different implementation.  For serious implementations, a better approach would be to extend
46  * CardLayout to provide the custom functionality needed.
47  *
48  *     @example
49  *     var navigate = function(panel, direction){
50  *         // This routine could contain business logic required to manage the navigation steps.
51  *         // It would call setActiveItem as needed, manage navigation button state, handle any
52  *         // branching logic that might be required, handle alternate actions like cancellation
53  *         // or finalization, etc.  A complete wizard implementation could get pretty
54  *         // sophisticated depending on the complexity required, and should probably be
55  *         // done as a subclass of CardLayout in a real-world implementation.
56  *         var layout = panel.getLayout();
57  *         layout[direction]();
58  *         Ext.getCmp('move-prev').setDisabled(!layout.getPrev());
59  *         Ext.getCmp('move-next').setDisabled(!layout.getNext());
60  *     };
61  *
62  *     Ext.create('Ext.panel.Panel', {
63  *         title: 'Example Wizard',
64  *         width: 300,
65  *         height: 200,
66  *         layout: 'card',
67  *         bodyStyle: 'padding:15px',
68  *         defaults: {
69  *             // applied to each contained panel
70  *             border: false
71  *         },
72  *         // just an example of one possible navigation scheme, using buttons
73  *         bbar: [
74  *             {
75  *                 id: 'move-prev',
76  *                 text: 'Back',
77  *                 handler: function(btn) {
78  *                     navigate(btn.up(&quot;panel&quot;), &quot;prev&quot;);
79  *                 },
80  *                 disabled: true
81  *             },
82  *             '-&gt;', // greedy spacer so that the buttons are aligned to each side
83  *             {
84  *                 id: 'move-next',
85  *                 text: 'Next',
86  *                 handler: function(btn) {
87  *                     navigate(btn.up(&quot;panel&quot;), &quot;next&quot;);
88  *                 }
89  *             }
90  *         ],
91  *         // the panels (or &quot;cards&quot;) within the layout
92  *         items: [{
93  *             id: 'card-0',
94  *             html: '&lt;h1&gt;Welcome to the Wizard!&lt;/h1&gt;&lt;p&gt;Step 1 of 3&lt;/p&gt;'
95  *         },{
96  *             id: 'card-1',
97  *             html: '&lt;p&gt;Step 2 of 3&lt;/p&gt;'
98  *         },{
99  *             id: 'card-2',
100  *             html: '&lt;h1&gt;Congratulations!&lt;/h1&gt;&lt;p&gt;Step 3 of 3 - Complete&lt;/p&gt;'
101  *         }],
102  *         renderTo: Ext.getBody()
103  *     });
104  */
105 Ext.define('Ext.layout.container.Card', {
106
107     /* Begin Definitions */
108
109     alias: ['layout.card'],
110     alternateClassName: 'Ext.layout.CardLayout',
111
112     extend: 'Ext.layout.container.AbstractCard',
113
114     /* End Definitions */
115
116 <span id='Ext-layout-container-Card-method-setActiveItem'>    /**
117 </span>     * Makes the given card active.
118      *
119      *     var card1 = Ext.create('Ext.panel.Panel', {itemId: 'card-1'});
120      *     var card2 = Ext.create('Ext.panel.Panel', {itemId: 'card-2'});
121      *     var panel = Ext.create('Ext.panel.Panel', {
122      *         layout: 'card',
123      *         activeItem: 0,
124      *         items: [card1, card2]
125      *     });
126      *     // These are all equivalent
127      *     panel.getLayout().setActiveItem(card2);
128      *     panel.getLayout().setActiveItem('card-2');
129      *     panel.getLayout().setActiveItem(1);
130      *
131      * @param {Ext.Component/Number/String} newCard  The component, component {@link Ext.Component#id id},
132      * {@link Ext.Component#itemId itemId}, or index of component.
133      * @return {Ext.Component} the activated component or false when nothing activated.
134      * False is returned also when trying to activate an already active card.
135      */
136     setActiveItem: function(newCard) {
137         var me = this,
138             owner = me.owner,
139             oldCard = me.activeItem,
140             newIndex;
141
142         newCard = me.parseActiveItem(newCard);
143         newIndex = owner.items.indexOf(newCard);
144
145         // If the card is not a child of the owner, then add it
146         if (newIndex == -1) {
147             newIndex = owner.items.items.length;
148             owner.add(newCard);
149         }
150
151         // Is this a valid, different card?
152         if (newCard &amp;&amp; oldCard != newCard) {
153             // If the card has not been rendered yet, now is the time to do so.
154             if (!newCard.rendered) {
155                 me.renderItem(newCard, me.getRenderTarget(), owner.items.length);
156                 me.configureItem(newCard, 0);
157             }
158
159             me.activeItem = newCard;
160
161             // Fire the beforeactivate and beforedeactivate events on the cards
162             if (newCard.fireEvent('beforeactivate', newCard, oldCard) === false) {
163                 return false;
164             }
165             if (oldCard &amp;&amp; oldCard.fireEvent('beforedeactivate', oldCard, newCard) === false) {
166                 return false;
167             }
168
169             // If the card hasnt been sized yet, do it now
170             if (me.sizeAllCards) {
171                 // onLayout calls setItemBox
172                 me.onLayout();
173             }
174             else {
175                 me.setItemBox(newCard, me.getTargetBox());
176             }
177
178             me.owner.suspendLayout = true;
179
180             if (oldCard) {
181                 if (me.hideInactive) {
182                     oldCard.hide();
183                 }
184                 oldCard.fireEvent('deactivate', oldCard, newCard);
185             }
186
187             // Make sure the new card is shown
188             me.owner.suspendLayout = false;
189             if (newCard.hidden) {
190                 newCard.show();
191             } else {
192                 me.onLayout();
193             }
194
195             newCard.fireEvent('activate', newCard, oldCard);
196
197             return newCard;
198         }
199         return false;
200     },
201
202     configureItem: function(item) {
203         // Card layout only controls dimensions which IT has controlled.
204         // That calculation has to be determined at run time by examining the ownerCt's isFixedWidth()/isFixedHeight() methods
205         item.layoutManagedHeight = 0;
206         item.layoutManagedWidth = 0;
207
208         this.callParent(arguments);
209     }});</pre>
210 </body>
211 </html>