Upgrade to ExtJS 4.0.0 - Released 04/26/2011
[extjs.git] / docs / api / Ext.Object.html
1 <!DOCTYPE html><html><head><title>Ext.Object | Ext JS 4.0 Documentation</title><script type="text/javascript" src="../ext-all.js"></script><link rel="stylesheet" href="../reset.css" type="text/css"><link rel="stylesheet" href="../scrollbars.css" type="text/css"><link rel="stylesheet" href="../docs.css" type="text/css"><link id="styleCss" rel="stylesheet" href="../style.css" type="text/css"><script type="text/javascript" src="../prettify.js"></script><link rel="stylesheet" href="../prettify.css" type="text/css"><!-- link(rel: 'stylesheet', href: req.baseURL + '/css/ext4.css', type: 'text/css')--><link rel="shortcut icon" type="image/ico" href="../favicon.ico"><!--[if IE]>
2 <style type="text/css">.head-band { display: none; }
3 .header { border: 0; top: 0; left: 0px; background: url(../header.gif) repeat-x; }
4 .doc-tab .members .member a.more { background-color: #efefef; }
5 </style><link rel="stylesheet" href="/new/css/ie.css" type="text/css"><![endif]-->
6 </head><body id="ext-body" class="iScroll"><div id="notice" class="notice">For up to date documentation and features, visit 
7 <a href="http://docs.sencha.com/ext-js/4-0">http://docs.sencha.com/ext-js/4-0</a></div><div class="wrapper"><div class="head-band"></div><div class="header"><h2><a href="../index.html">Sencha Documentation</a></h2></div><div id="search"><form><input type="text" placeholder="Search" id="search-field" autocomplete="off" name="q"></form><div id="search-box"></div></div><div id="treePanel"></div><div id="container"><script type="text/javascript">
8
9     req = {
10         liveURL: '.',
11         standAloneMode: true,
12         origDocClass: 'Ext.Object',
13         docClass: 'Ext.Object',
14         docReq: 'Ext.Object',
15         version: '4.0',
16         baseURL: '.',
17         baseDocURL: '.',
18         baseProdURL: '.'
19     };
20
21     clsInfo = {};
22
23
24
25 </script>
26
27 <script type="text/javascript" src="../search.js"></script>
28 <!--script type="text/javascript" src="/new/javascripts/app/examples.js"></script-->
29 <script type="text/javascript" src="../class_tree.js"></script>
30 <script type="text/javascript" src="../class_doc.js"></script>
31 <script type="text/javascript">
32     req.source = 'Object.html#Ext-Object';
33     clsInfo = {"methods":["each","fromQueryString","getKey","getSize","getValues","merge","toQueryObjects","toQueryString"],"cfgs":[],"properties":["getKeys"],"events":[],"subclasses":[]};
34     Ext.onReady(function() {
35         Ext.create('Docs.classPanel');
36     });
37 </script><div id="top-block" class="top-block"><h1 id="clsTitle" class="cls"><a href="../source/Object.html#Ext-Object" target="_blank">Ext.Object</a></h1></div><div id="docContent"><div id="doc-overview-content"><div class="lft"><p>A collection of useful static methods to deal with objects</p>
38 <div class="members"><div class="m-properties"><a name="properties"></a><div class="definedBy">Defined By</div><h3 class="prp p">Properties</h3><div id="property-getKeys" class="member f ni"><a href="Ext.Object.html#property-getKeys" rel="property-getKeys" class="expand more ar"><span>&nbsp;</span></a><div class="title"><div class="meta"><a href="Ext.Object.html" class="definedIn docClass">Ext.Object</a><br/><a href="../source/Object.html#Ext-Object-property-getKeys" class="viewSource">view source</a></div><a name="getKeys"></a><a name="property-getKeys"></a><a href="Ext.Object.html#" rel="property-getKeys" class="cls expand">getKeys</a><span> : Object</span></div><div class="description"><div class="short">Gets all keys of the given object as an array.
39
40 var values = Ext.Object.getKeys({
41     name: 'Jacky',
42     loves: 'food...</div><div class="long"><p>Gets all keys of the given object as an array.</p>
43
44 <pre><code>var values = Ext.Object.getKeys({
45     name: 'Jacky',
46     loves: 'food'
47 }); // ['name', 'loves']
48 </code></pre>
49 </div></div></div></div><div class="m-methods"><a name="methods"></a><div class="definedBy">Defined By</div><h3 class="mth p">Methods</h3><div id="method-each" class="member f ni"><a href="Ext.Object.html#method-each" rel="method-each" class="expand more ar"><span>&nbsp;</span></a><div class="title"><div class="meta"><a href="Ext.Object.html" class="definedIn docClass">Ext.Object</a><br/><a href="../source/Object.html#Ext-Object-method-each" class="viewSource">view source</a></div><a name="each"></a><a name="method-each"></a><a href="Ext.Object.html#" rel="method-each" class="cls expand">each</a>(
50 <span class="pre">Object object, Function fn, Object scope</span>)
51  : void</div><div class="description"><div class="short">Iterate through an object and invoke the given callback function for each iteration. The iteration can be stop
52 by ret...</div><div class="long"><p>Iterate through an object and invoke the given callback function for each iteration. The iteration can be stop
53 by returning <code>false</code> in the callback function. For example:</p>
54
55 <pre><code>var person = {
56     name: 'Jacky'
57     hairColor: 'black'
58     loves: ['food', 'sleeping', 'wife']
59 };
60
61 Ext.Object.each(person, function(key, value, myself) {
62     console.log(key + ":" + value);
63
64     if (key === 'hairColor') {
65         return false; // stop the iteration
66     }
67 });
68 </code></pre>
69 <h3 class="pa">Parameters</h3><ul><li><span class="pre">object</span> : Object<div class="sub-desc"><p>The object to iterate</p>
70 </div></li><li><span class="pre">fn</span> : Function<div class="sub-desc"><p>The callback function. Passed arguments for each iteration are:</p>
71
72 <ul>
73 <li>{String} <code>key</code></li>
74 <li>{Mixed} <code>value</code></li>
75 <li>{Object} <code>object</code> The object itself</li>
76 </ul>
77
78 </div></li><li><span class="pre">scope</span> : Object<div class="sub-desc"><p>(Optional) The execution scope (<code>this</code>) of the callback function</p>
79 </div></li></ul><h3 class="pa">Returns</h3><ul><li><span class="pre">void</span>&nbsp; &nbsp;
80 </li></ul></div></div></div><div id="method-fromQueryString" class="member ni"><a href="Ext.Object.html#method-fromQueryString" rel="method-fromQueryString" class="expand more ar"><span>&nbsp;</span></a><div class="title"><div class="meta"><a href="Ext.Object.html" class="definedIn docClass">Ext.Object</a><br/><a href="../source/Object.html#Ext-Object-method-fromQueryString" class="viewSource">view source</a></div><a name="fromQueryString"></a><a name="method-fromQueryString"></a><a href="Ext.Object.html#" rel="method-fromQueryString" class="cls expand">fromQueryString</a>(
81 <span class="pre">String queryString, Boolean recursive</span>)
82  : Object</div><div class="description"><div class="short">Converts a query string back into an object.
83
84
85 Non-recursive:
86
87   Ext.Object.fromQueryString(foo=1&amp;bar=2); // retu...</div><div class="long"><p>Converts a query string back into an object.</p>
88
89 <ul>
90 <li><p>Non-recursive:</p>
91
92 <p>  Ext.Object.fromQueryString(foo=1&amp;bar=2); // returns {foo: 1, bar: 2}
93   Ext.Object.fromQueryString(foo=&amp;bar=2); // returns {foo: null, bar: 2}
94   Ext.Object.fromQueryString(some%20price=%24300); // returns {'some price': '$300'}
95   Ext.Object.fromQueryString(colors=red&amp;colors=green&amp;colors=blue); // returns {colors: ['red', 'green', 'blue']}</p></li>
96 <li><p>Recursive:</p>
97
98 <p>  Ext.Object.fromQueryString("username=Jacky&amp;dateOfBirth[day]=1&amp;dateOfBirth[month]=2&amp;dateOfBirth[year]=1911&amp;hobbies[0]=coding&amp;hobbies[1]=eating&amp;hobbies[2]=sleeping&amp;hobbies[3][0]=nested&amp;hobbies[3][1]=stuff", true);</p>
99
100 <p>  // returns
101   {</p>
102
103 <pre><code>  username: 'Jacky',
104   dateOfBirth: {
105       day: '1',
106       month: '2',
107       year: '1911'
108   },
109   hobbies: ['coding', 'eating', 'sleeping', ['nested', 'stuff']]
110 </code></pre>
111
112 <p>  }</p></li>
113 </ul>
114
115 <h3 class="pa">Parameters</h3><ul><li><span class="pre">queryString</span> : String<div class="sub-desc"><p>The query string to decode</p>
116 </div></li><li><span class="pre">recursive</span> : Boolean<div class="sub-desc"><p>(Optional) Whether or not to recursively decode the string. This format is supported by
117 PHP / Ruby on Rails servers and similar. Defaults to false</p>
118 </div></li></ul><h3 class="pa">Returns</h3><ul><li><span class="pre">Object</span>&nbsp; &nbsp;
119 </li></ul></div></div></div><div id="method-getKey" class="member ni"><a href="Ext.Object.html#method-getKey" rel="method-getKey" class="expand more ar"><span>&nbsp;</span></a><div class="title"><div class="meta"><a href="Ext.Object.html" class="definedIn docClass">Ext.Object</a><br/><a href="../source/Object.html#Ext-Object-method-getKey" class="viewSource">view source</a></div><a name="getKey"></a><a name="method-getKey"></a><a href="Ext.Object.html#" rel="method-getKey" class="cls expand">getKey</a>(
120 <span class="pre">Object object, Object value</span>)
121  : void</div><div class="description"><div class="short">Returns the first matching key corresponding to the given value.
122 If no matching value is found, null is returned.
123
124 va...</div><div class="long"><p>Returns the first matching key corresponding to the given value.
125 If no matching value is found, null is returned.</p>
126
127 <pre><code>var person = {
128     name: 'Jacky',
129     loves: 'food'
130 };
131
132 alert(Ext.Object.getKey(sencha, 'loves')); // alerts 'food'
133 </code></pre>
134 <h3 class="pa">Parameters</h3><ul><li><span class="pre">object</span> : Object<div class="sub-desc">
135 </div></li><li><span class="pre">value</span> : Object<div class="sub-desc"><p>The value to find</p>
136 </div></li></ul><h3 class="pa">Returns</h3><ul><li><span class="pre">void</span>&nbsp; &nbsp;
137 </li></ul></div></div></div><div id="method-getSize" class="member ni"><a href="Ext.Object.html#method-getSize" rel="method-getSize" class="expand more ar"><span>&nbsp;</span></a><div class="title"><div class="meta"><a href="Ext.Object.html" class="definedIn docClass">Ext.Object</a><br/><a href="../source/Object.html#Ext-Object-method-getSize" class="viewSource">view source</a></div><a name="getSize"></a><a name="method-getSize"></a><a href="Ext.Object.html#" rel="method-getSize" class="cls expand">getSize</a>(
138 <span class="pre">Object object</span>)
139  : Number</div><div class="description"><div class="short">Gets the total number of this object's own properties
140
141 var size = Ext.Object.getSize({
142     name: 'Jacky',
143     loves: ...</div><div class="long"><p>Gets the total number of this object's own properties</p>
144
145 <pre><code>var size = Ext.Object.getSize({
146     name: 'Jacky',
147     loves: 'food'
148 }); // size equals 2
149 </code></pre>
150 <h3 class="pa">Parameters</h3><ul><li><span class="pre">object</span> : Object<div class="sub-desc">
151 </div></li></ul><h3 class="pa">Returns</h3><ul><li><span class="pre">Number</span>&nbsp; &nbsp;<p>size</p>
152 </li></ul></div></div></div><div id="method-getValues" class="member ni"><a href="Ext.Object.html#method-getValues" rel="method-getValues" class="expand more ar"><span>&nbsp;</span></a><div class="title"><div class="meta"><a href="Ext.Object.html" class="definedIn docClass">Ext.Object</a><br/><a href="../source/Object.html#Ext-Object-method-getValues" class="viewSource">view source</a></div><a name="getValues"></a><a name="method-getValues"></a><a href="Ext.Object.html#" rel="method-getValues" class="cls expand">getValues</a>(
153 <span class="pre">Object object</span>)
154  : Array</div><div class="description"><div class="short">Gets all values of the given object as an array.
155
156 var values = Ext.Object.getValues({
157     name: 'Jacky',
158     loves: '...</div><div class="long"><p>Gets all values of the given object as an array.</p>
159
160 <pre><code>var values = Ext.Object.getValues({
161     name: 'Jacky',
162     loves: 'food'
163 }); // ['Jacky', 'food']
164 </code></pre>
165 <h3 class="pa">Parameters</h3><ul><li><span class="pre">object</span> : Object<div class="sub-desc">
166 </div></li></ul><h3 class="pa">Returns</h3><ul><li><span class="pre">Array</span>&nbsp; &nbsp;<p>An array of values from the object</p>
167 </li></ul></div></div></div><div id="method-merge" class="member ni"><a href="Ext.Object.html#method-merge" rel="method-merge" class="expand more ar"><span>&nbsp;</span></a><div class="title"><div class="meta"><a href="Ext.Object.html" class="definedIn docClass">Ext.Object</a><br/><a href="../source/Object.html#Ext-Object-method-merge" class="viewSource">view source</a></div><a name="merge"></a><a name="method-merge"></a><a href="Ext.Object.html#" rel="method-merge" class="cls expand">merge</a>(
168 <span class="pre">Object object, Object key, Object value</span>)
169  : Object</div><div class="description"><div class="short">Merges any number of objects recursively without referencing them or their children.
170
171 var extjs = {
172     companyName: ...</div><div class="long"><p>Merges any number of objects recursively without referencing them or their children.</p>
173
174 <pre><code>var extjs = {
175     companyName: 'Ext JS',
176     products: ['Ext JS', 'Ext GWT', 'Ext Designer'],
177     isSuperCool: true
178     office: {
179         size: 2000,
180         location: 'Palo Alto',
181         isFun: true
182     }
183 };
184
185 var newStuff = {
186     companyName: 'Sencha Inc.',
187     products: ['Ext JS', 'Ext GWT', 'Ext Designer', 'Sencha Touch', 'Sencha Animator'],
188     office: {
189         size: 40000,
190         location: 'Redwood City'
191     }
192 };
193
194 var sencha = Ext.Object.merge(extjs, newStuff);
195
196 // extjs and sencha then equals to
197 {
198     companyName: 'Sencha Inc.',
199     products: ['Ext JS', 'Ext GWT', 'Ext Designer', 'Sencha Touch', 'Sencha Animator'],
200     isSuperCool: true
201     office: {
202         size: 30000,
203         location: 'Redwood City'
204         isFun: true
205     }
206 }
207 </code></pre>
208 <h3 class="pa">Parameters</h3><ul><li><span class="pre">object</span> : Object<div class="sub-desc"><p>,...</p>
209 </div></li><li><span class="pre">key</span> : Object<div class="sub-desc">
210 </div></li><li><span class="pre">value</span> : Object<div class="sub-desc">
211 </div></li></ul><h3 class="pa">Returns</h3><ul><li><span class="pre">Object</span>&nbsp; &nbsp;<p>merged The object that is created as a result of merging all the objects passed in.</p>
212 </li></ul></div></div></div><div id="method-toQueryObjects" class="member ni"><a href="Ext.Object.html#method-toQueryObjects" rel="method-toQueryObjects" class="expand more ar"><span>&nbsp;</span></a><div class="title"><div class="meta"><a href="Ext.Object.html" class="definedIn docClass">Ext.Object</a><br/><a href="../source/Object.html#Ext-Object-method-toQueryObjects" class="viewSource">view source</a></div><a name="toQueryObjects"></a><a name="method-toQueryObjects"></a><a href="Ext.Object.html#" rel="method-toQueryObjects" class="cls expand">toQueryObjects</a>(
213 <span class="pre">String name, Mixed value, Boolean recursive</span>)
214  : void</div><div class="description"><div class="short">Convert a name - value pair to an array of objects with support for nested structures; useful to construct
215 query stri...</div><div class="long"><p>Convert a <code>name</code> - <code>value</code> pair to an array of objects with support for nested structures; useful to construct
216 query strings. For example:</p>
217
218 <pre><code>var objects = Ext.Object.toQueryObjects('hobbies', ['reading', 'cooking', 'swimming']);
219
220 // objects then equals:
221 [
222     { name: 'hobbies', value: 'reading' },
223     { name: 'hobbies', value: 'cooking' },
224     { name: 'hobbies', value: 'swimming' },
225 ];
226
227 var objects = Ext.Object.toQueryObjects('dateOfBirth', {
228     day: 3,
229     month: 8,
230     year: 1987,
231     extra: {
232         hour: 4
233         minute: 30
234     }
235 }, true); // Recursive
236
237 // objects then equals:
238 [
239     { name: 'dateOfBirth[day]', value: 3 },
240     { name: 'dateOfBirth[month]', value: 8 },
241     { name: 'dateOfBirth[year]', value: 1987 },
242     { name: 'dateOfBirth[extra][hour]', value: 4 },
243     { name: 'dateOfBirth[extra][minute]', value: 30 },
244 ];
245 </code></pre>
246 <h3 class="pa">Parameters</h3><ul><li><span class="pre">name</span> : String<div class="sub-desc">
247 </div></li><li><span class="pre">value</span> : Mixed<div class="sub-desc">
248 </div></li><li><span class="pre">recursive</span> : Boolean<div class="sub-desc">
249 </div></li></ul><h3 class="pa">Returns</h3><ul><li><span class="pre">void</span>&nbsp; &nbsp;
250 </li></ul></div></div></div><div id="method-toQueryString" class="member ni"><a href="Ext.Object.html#method-toQueryString" rel="method-toQueryString" class="expand more ar"><span>&nbsp;</span></a><div class="title"><div class="meta"><a href="Ext.Object.html" class="definedIn docClass">Ext.Object</a><br/><a href="../source/Object.html#Ext-Object-method-toQueryString" class="viewSource">view source</a></div><a name="toQueryString"></a><a name="method-toQueryString"></a><a href="Ext.Object.html#" rel="method-toQueryString" class="cls expand">toQueryString</a>(
251 <span class="pre">Object object, [Boolean recursive]</span>)
252  : String</div><div class="description"><div class="short">Takes an object and converts it to an encoded query string
253
254
255 Non-recursive:
256
257   Ext.Object.toQueryString({foo: 1, bar:...</div><div class="long"><p>Takes an object and converts it to an encoded query string</p>
258
259 <ul>
260 <li><p>Non-recursive:</p>
261
262 <p>  Ext.Object.toQueryString({foo: 1, bar: 2}); // returns "foo=1&amp;bar=2"
263   Ext.Object.toQueryString({foo: null, bar: 2}); // returns "foo=&amp;bar=2"
264   Ext.Object.toQueryString({'some price': '$300'}); // returns "some%20price=%24300"
265   Ext.Object.toQueryString({date: new Date(2011, 0, 1)}); // returns "date=%222011-01-01T00%3A00%3A00%22"
266   Ext.Object.toQueryString({colors: ['red', 'green', 'blue']}); // returns "colors=red&amp;colors=green&amp;colors=blue"</p></li>
267 <li><p>Recursive:</p>
268
269 <p>  Ext.Object.toQueryString({</p>
270
271 <pre><code>  username: 'Jacky',
272   dateOfBirth: {
273       day: 1,
274       month: 2,
275       year: 1911
276   },
277   hobbies: ['coding', 'eating', 'sleeping', ['nested', 'stuff']]
278 </code></pre>
279
280   }, true); // returns the following string (broken down and url-decoded for ease of reading purpose):
281
282 <pre><code>        // username=Jacky
283         //    &amp;dateOfBirth[day]=1&amp;dateOfBirth[month]=2&amp;dateOfBirth[year]=1911
284         //    &amp;hobbies[0]=coding&amp;hobbies[1]=eating&amp;hobbies[2]=sleeping&amp;hobbies[3][0]=nested&amp;hobbies[3][1]=stuff
285 </code></pre></li>
286 </ul>
287
288 <h3 class="pa">Parameters</h3><ul><li><span class="pre">object</span> : Object<div class="sub-desc"><p>The object to encode</p>
289 </div></li><li><span class="pre">recursive</span> : Boolean<div class="sub-desc"><p>(optional) Whether or not to interpret the object in recursive format.
290 (PHP / Ruby on Rails servers and similar). Defaults to false</p>
291 </div></li></ul><h3 class="pa">Returns</h3><ul><li><span class="pre">String</span>&nbsp; &nbsp;<p>queryString</p>
292 </li></ul></div></div></div></div></div></div></div><div id="pageContent"></div></div></div></div></body></html>