Upgrade to ExtJS 4.0.0 - Released 04/26/2011
[extjs.git] / docs / source / Container.html
1 <!DOCTYPE html><html><head><title>Sencha Documentation Project</title><link rel="stylesheet" href="../reset.css" type="text/css"><link rel="stylesheet" href="../prettify.css" type="text/css"><link rel="stylesheet" href="../prettify_sa.css" type="text/css"><script type="text/javascript" src="../prettify.js"></script></head><body onload="prettyPrint()"><pre class="prettyprint"><pre><span id='Ext-container.Container'>/**
2 </span> * @class Ext.container.Container
3  * @extends Ext.container.AbstractContainer
4  * &lt;p&gt;Base class for any {@link Ext.Component} that may contain other Components. Containers handle the
5  * basic behavior of containing items, namely adding, inserting and removing items.&lt;/p&gt;
6  *
7  * &lt;p&gt;The most commonly used Container classes are {@link Ext.panel.Panel}, {@link Ext.window.Window} and {@link Ext.tab.Panel}.
8  * If you do not need the capabilities offered by the aforementioned classes you can create a lightweight
9  * Container to be encapsulated by an HTML element to your specifications by using the
10  * &lt;code&gt;&lt;b&gt;{@link Ext.Component#autoEl autoEl}&lt;/b&gt;&lt;/code&gt; config option.&lt;/p&gt;
11  *
12  * {@img Ext.Container/Ext.Container.png Ext.Container component} 
13  * &lt;p&gt;The code below illustrates how to explicitly create a Container:&lt;pre&gt;&lt;code&gt;
14 // explicitly create a Container
15 Ext.create('Ext.container.Container', {
16     layout: {
17         type: 'hbox'
18     },
19     width: 400,
20     renderTo: Ext.getBody(),
21     border: 1,
22     style: {borderColor:'#000000', borderStyle:'solid', borderWidth:'1px'},
23     defaults: {
24         labelWidth: 80,
25         // implicitly create Container by specifying xtype
26         xtype: 'datefield',
27         flex: 1,
28         style: {
29             padding: '10px'
30         }
31     },
32     items: [{
33         xtype: 'datefield',
34         name: 'startDate',
35         fieldLabel: 'Start date'
36     },{
37         xtype: 'datefield',
38         name: 'endDate',
39         fieldLabel: 'End date'
40     }]
41 });
42 &lt;/code&gt;&lt;/pre&gt;&lt;/p&gt;
43  *
44  * &lt;p&gt;&lt;u&gt;&lt;b&gt;Layout&lt;/b&gt;&lt;/u&gt;&lt;/p&gt;
45  * &lt;p&gt;Container classes delegate the rendering of child Components to a layout
46  * manager class which must be configured into the Container using the
47  * &lt;code&gt;&lt;b&gt;{@link #layout}&lt;/b&gt;&lt;/code&gt; configuration property.&lt;/p&gt;
48  * &lt;p&gt;When either specifying child &lt;code&gt;{@link #items}&lt;/code&gt; of a Container,
49  * or dynamically {@link #add adding} Components to a Container, remember to
50  * consider how you wish the Container to arrange those child elements, and
51  * whether those child elements need to be sized using one of Ext's built-in
52  * &lt;b&gt;&lt;code&gt;{@link #layout}&lt;/code&gt;&lt;/b&gt; schemes. By default, Containers use the
53  * {@link Ext.layout.container.Auto Auto} scheme which only
54  * renders child components, appending them one after the other inside the
55  * Container, and &lt;b&gt;does not apply any sizing&lt;/b&gt; at all.&lt;/p&gt;
56  * &lt;p&gt;A common mistake is when a developer neglects to specify a
57  * &lt;b&gt;&lt;code&gt;{@link #layout}&lt;/code&gt;&lt;/b&gt; (e.g. widgets like GridPanels or
58  * TreePanels are added to Containers for which no &lt;code&gt;&lt;b&gt;{@link #layout}&lt;/b&gt;&lt;/code&gt;
59  * has been specified). If a Container is left to use the default
60  * {Ext.layout.container.Auto Auto} scheme, none of its
61  * child components will be resized, or changed in any way when the Container
62  * is resized.&lt;/p&gt;
63  * &lt;p&gt;Certain layout managers allow dynamic addition of child components.
64  * Those that do include {@link Ext.layout.container.Card},
65  * {@link Ext.layout.container.Anchor}, {@link Ext.layout.container.VBox}, {@link Ext.layout.container.HBox}, and
66  * {@link Ext.layout.container.Table}. For example:&lt;pre&gt;&lt;code&gt;
67 //  Create the GridPanel.
68 var myNewGrid = new Ext.grid.Panel({
69     store: myStore,
70     headers: myHeaders,
71     title: 'Results', // the title becomes the title of the tab
72 });
73
74 myTabPanel.add(myNewGrid); // {@link Ext.tab.Panel} implicitly uses {@link Ext.layout.container.Card Card}
75 myTabPanel.{@link Ext.tab.Panel#setActiveTab setActiveTab}(myNewGrid);
76  * &lt;/code&gt;&lt;/pre&gt;&lt;/p&gt;
77  * &lt;p&gt;The example above adds a newly created GridPanel to a TabPanel. Note that
78  * a TabPanel uses {@link Ext.layout.container.Card} as its layout manager which
79  * means all its child items are sized to {@link Ext.layout.container.Fit fit}
80  * exactly into its client area.
81  * &lt;p&gt;&lt;b&gt;&lt;u&gt;Overnesting is a common problem&lt;/u&gt;&lt;/b&gt;.
82  * An example of overnesting occurs when a GridPanel is added to a TabPanel
83  * by wrapping the GridPanel &lt;i&gt;inside&lt;/i&gt; a wrapping Panel (that has no
84  * &lt;code&gt;&lt;b&gt;{@link #layout}&lt;/b&gt;&lt;/code&gt; specified) and then add that wrapping Panel
85  * to the TabPanel. The point to realize is that a GridPanel &lt;b&gt;is&lt;/b&gt; a
86  * Component which can be added directly to a Container. If the wrapping Panel
87  * has no &lt;code&gt;&lt;b&gt;{@link #layout}&lt;/b&gt;&lt;/code&gt; configuration, then the overnested
88  * GridPanel will not be sized as expected.&lt;p&gt;
89  *
90  * &lt;p&gt;&lt;u&gt;&lt;b&gt;Adding via remote configuration&lt;/b&gt;&lt;/u&gt;&lt;/p&gt;
91  *
92  * &lt;p&gt;A server side script can be used to add Components which are generated dynamically on the server.
93  * An example of adding a GridPanel to a TabPanel where the GridPanel is generated by the server
94  * based on certain parameters:
95  * &lt;/p&gt;&lt;pre&gt;&lt;code&gt;
96 // execute an Ajax request to invoke server side script:
97 Ext.Ajax.request({
98     url: 'gen-invoice-grid.php',
99     // send additional parameters to instruct server script
100     params: {
101         startDate: Ext.getCmp('start-date').getValue(),
102         endDate: Ext.getCmp('end-date').getValue()
103     },
104     // process the response object to add it to the TabPanel:
105     success: function(xhr) {
106         var newComponent = eval(xhr.responseText); // see discussion below
107         myTabPanel.add(newComponent); // add the component to the TabPanel
108         myTabPanel.setActiveTab(newComponent);
109     },
110     failure: function() {
111         Ext.Msg.alert(&quot;Grid create failed&quot;, &quot;Server communication failure&quot;);
112     }
113 });
114 &lt;/code&gt;&lt;/pre&gt;
115  * &lt;p&gt;The server script needs to return a JSON representation of a configuration object, which, when decoded
116  * will return a config object with an {@link Ext.Component#xtype xtype}. The server might return the following
117  * JSON:&lt;/p&gt;&lt;pre&gt;&lt;code&gt;
118 {
119     &quot;xtype&quot;: 'grid',
120     &quot;title&quot;: 'Invoice Report',
121     &quot;store&quot;: {
122         &quot;model&quot;: 'Invoice',
123         &quot;proxy&quot;: {
124             &quot;type&quot;: 'ajax',
125             &quot;url&quot;: 'get-invoice-data.php',
126             &quot;reader&quot;: {
127                 &quot;type&quot;: 'json'
128                 &quot;record&quot;: 'transaction',
129                 &quot;idProperty&quot;: 'id',
130                 &quot;totalRecords&quot;: 'total'
131             })
132         },
133         &quot;autoLoad&quot;: {
134             &quot;params&quot;: {
135                 &quot;startDate&quot;: '01/01/2008',
136                 &quot;endDate&quot;: '01/31/2008'
137             }
138         }
139     },
140     &quot;headers&quot;: [
141         {&quot;header&quot;: &quot;Customer&quot;, &quot;width&quot;: 250, &quot;dataIndex&quot;: 'customer', &quot;sortable&quot;: true},
142         {&quot;header&quot;: &quot;Invoice Number&quot;, &quot;width&quot;: 120, &quot;dataIndex&quot;: 'invNo', &quot;sortable&quot;: true},
143         {&quot;header&quot;: &quot;Invoice Date&quot;, &quot;width&quot;: 100, &quot;dataIndex&quot;: 'date', &quot;renderer&quot;: Ext.util.Format.dateRenderer('M d, y'), &quot;sortable&quot;: true},
144         {&quot;header&quot;: &quot;Value&quot;, &quot;width&quot;: 120, &quot;dataIndex&quot;: 'value', &quot;renderer&quot;: 'usMoney', &quot;sortable&quot;: true}
145     ]
146 }
147 &lt;/code&gt;&lt;/pre&gt;
148  * &lt;p&gt;When the above code fragment is passed through the &lt;code&gt;eval&lt;/code&gt; function in the success handler
149  * of the Ajax request, the result will be a config object which, when added to a Container, will cause instantiation
150  * of a GridPanel. &lt;b&gt;Be sure that the Container is configured with a layout which sizes and positions the child items to your requirements.&lt;/b&gt;&lt;/p&gt;
151  * &lt;p&gt;Note: since the code above is &lt;i&gt;generated&lt;/i&gt; by a server script, the &lt;code&gt;autoLoad&lt;/code&gt; params for
152  * the Store, the user's preferred date format, the metadata to allow generation of the Model layout, and the ColumnModel
153  * can all be generated into the code since these are all known on the server.&lt;/p&gt;
154  *
155  * @xtype container
156  */
157 Ext.define('Ext.container.Container', {
158     extend: 'Ext.container.AbstractContainer',
159     alias: 'widget.container',
160     alternateClassName: 'Ext.Container',
161
162 <span id='Ext-container.Container-method-getChildByElement'>    /**
163 </span>     * Return the immediate child Component in which the passed element is located.
164      * @param el The element to test.
165      * @return {Component} The child item which contains the passed element.
166      */
167     getChildByElement: function(el) {
168         var item,
169             itemEl,
170             i = 0,
171             it = this.items.items,
172             ln = it.length;
173
174         el = Ext.getDom(el);
175         for (; i &lt; ln; i++) {
176             item = it[i];
177             itemEl = item.getEl();
178             if ((itemEl.dom === el) || itemEl.contains(el)) {
179                 return item;
180             }
181         }
182         return null;
183     }
184 });
185 </pre></pre></body></html>