X-Git-Url: http://git.ithinksw.org/extjs.git/blobdiff_plain/6746dc89c47ed01b165cc1152533605f97eb8e8d..f562e4c6e5fac7bcb445985b99acbea4d706e6f0:/src/core/src/lang/Object.js diff --git a/src/core/src/lang/Object.js b/src/core/src/lang/Object.js index d0b17ebd..075a8859 100644 --- a/src/core/src/lang/Object.js +++ b/src/core/src/lang/Object.js @@ -17,7 +17,7 @@ If you are unsure which license is appropriate for your use, please contact the * @docauthor Jacky Nguyen * @class Ext.Object * - * A collection of useful static methods to deal with objects + * A collection of useful static methods to deal with objects. * * @singleton */ @@ -27,41 +27,41 @@ If you are unsure which license is appropriate for your use, please contact the var ExtObject = Ext.Object = { /** - * Convert a `name` - `value` pair to an array of objects with support for nested structures; useful to construct + * Converts a `name` - `value` pair to an array of objects with support for nested structures. Useful to construct * query strings. For example: - - var objects = Ext.Object.toQueryObjects('hobbies', ['reading', 'cooking', 'swimming']); - - // objects then equals: - [ - { name: 'hobbies', value: 'reading' }, - { name: 'hobbies', value: 'cooking' }, - { name: 'hobbies', value: 'swimming' }, - ]; - - var objects = Ext.Object.toQueryObjects('dateOfBirth', { - day: 3, - month: 8, - year: 1987, - extra: { - hour: 4 - minute: 30 - } - }, true); // Recursive - - // objects then equals: - [ - { name: 'dateOfBirth[day]', value: 3 }, - { name: 'dateOfBirth[month]', value: 8 }, - { name: 'dateOfBirth[year]', value: 1987 }, - { name: 'dateOfBirth[extra][hour]', value: 4 }, - { name: 'dateOfBirth[extra][minute]', value: 30 }, - ]; - + * + * var objects = Ext.Object.toQueryObjects('hobbies', ['reading', 'cooking', 'swimming']); + * + * // objects then equals: + * [ + * { name: 'hobbies', value: 'reading' }, + * { name: 'hobbies', value: 'cooking' }, + * { name: 'hobbies', value: 'swimming' }, + * ]; + * + * var objects = Ext.Object.toQueryObjects('dateOfBirth', { + * day: 3, + * month: 8, + * year: 1987, + * extra: { + * hour: 4 + * minute: 30 + * } + * }, true); // Recursive + * + * // objects then equals: + * [ + * { name: 'dateOfBirth[day]', value: 3 }, + * { name: 'dateOfBirth[month]', value: 8 }, + * { name: 'dateOfBirth[year]', value: 1987 }, + * { name: 'dateOfBirth[extra][hour]', value: 4 }, + * { name: 'dateOfBirth[extra][minute]', value: 30 }, + * ]; + * * @param {String} name - * @param {Mixed} value - * @param {Boolean} recursive - * @markdown + * @param {Object/Array} value + * @param {Boolean} [recursive=false] True to traverse object recursively + * @return {Array} */ toQueryObjects: function(name, value, recursive) { var self = ExtObject.toQueryObjects, @@ -107,37 +107,35 @@ var ExtObject = Ext.Object = { }, /** - * Takes an object and converts it to an encoded query string - -- Non-recursive: - - Ext.Object.toQueryString({foo: 1, bar: 2}); // returns "foo=1&bar=2" - Ext.Object.toQueryString({foo: null, bar: 2}); // returns "foo=&bar=2" - Ext.Object.toQueryString({'some price': '$300'}); // returns "some%20price=%24300" - Ext.Object.toQueryString({date: new Date(2011, 0, 1)}); // returns "date=%222011-01-01T00%3A00%3A00%22" - Ext.Object.toQueryString({colors: ['red', 'green', 'blue']}); // returns "colors=red&colors=green&colors=blue" - -- Recursive: - - Ext.Object.toQueryString({ - username: 'Jacky', - dateOfBirth: { - day: 1, - month: 2, - year: 1911 - }, - hobbies: ['coding', 'eating', 'sleeping', ['nested', 'stuff']] - }, true); // returns the following string (broken down and url-decoded for ease of reading purpose): - // username=Jacky - // &dateOfBirth[day]=1&dateOfBirth[month]=2&dateOfBirth[year]=1911 - // &hobbies[0]=coding&hobbies[1]=eating&hobbies[2]=sleeping&hobbies[3][0]=nested&hobbies[3][1]=stuff - + * Takes an object and converts it to an encoded query string. + * + * Non-recursive: + * + * Ext.Object.toQueryString({foo: 1, bar: 2}); // returns "foo=1&bar=2" + * Ext.Object.toQueryString({foo: null, bar: 2}); // returns "foo=&bar=2" + * Ext.Object.toQueryString({'some price': '$300'}); // returns "some%20price=%24300" + * Ext.Object.toQueryString({date: new Date(2011, 0, 1)}); // returns "date=%222011-01-01T00%3A00%3A00%22" + * Ext.Object.toQueryString({colors: ['red', 'green', 'blue']}); // returns "colors=red&colors=green&colors=blue" + * + * Recursive: + * + * Ext.Object.toQueryString({ + * username: 'Jacky', + * dateOfBirth: { + * day: 1, + * month: 2, + * year: 1911 + * }, + * hobbies: ['coding', 'eating', 'sleeping', ['nested', 'stuff']] + * }, true); // returns the following string (broken down and url-decoded for ease of reading purpose): + * // username=Jacky + * // &dateOfBirth[day]=1&dateOfBirth[month]=2&dateOfBirth[year]=1911 + * // &hobbies[0]=coding&hobbies[1]=eating&hobbies[2]=sleeping&hobbies[3][0]=nested&hobbies[3][1]=stuff * * @param {Object} object The object to encode - * @param {Boolean} recursive (optional) Whether or not to interpret the object in recursive format. - * (PHP / Ruby on Rails servers and similar). Defaults to false + * @param {Boolean} [recursive=false] Whether or not to interpret the object in recursive format. + * (PHP / Ruby on Rails servers and similar). * @return {String} queryString - * @markdown */ toQueryString: function(object, recursive) { var paramObjects = [], @@ -170,31 +168,30 @@ var ExtObject = Ext.Object = { /** * Converts a query string back into an object. * -- Non-recursive: - - Ext.Object.fromQueryString(foo=1&bar=2); // returns {foo: 1, bar: 2} - Ext.Object.fromQueryString(foo=&bar=2); // returns {foo: null, bar: 2} - Ext.Object.fromQueryString(some%20price=%24300); // returns {'some price': '$300'} - Ext.Object.fromQueryString(colors=red&colors=green&colors=blue); // returns {colors: ['red', 'green', 'blue']} - -- Recursive: - - Ext.Object.fromQueryString("username=Jacky&dateOfBirth[day]=1&dateOfBirth[month]=2&dateOfBirth[year]=1911&hobbies[0]=coding&hobbies[1]=eating&hobbies[2]=sleeping&hobbies[3][0]=nested&hobbies[3][1]=stuff", true); - - // returns - { - username: 'Jacky', - dateOfBirth: { - day: '1', - month: '2', - year: '1911' - }, - hobbies: ['coding', 'eating', 'sleeping', ['nested', 'stuff']] - } - + * Non-recursive: + * + * Ext.Object.fromQueryString(foo=1&bar=2); // returns {foo: 1, bar: 2} + * Ext.Object.fromQueryString(foo=&bar=2); // returns {foo: null, bar: 2} + * Ext.Object.fromQueryString(some%20price=%24300); // returns {'some price': '$300'} + * Ext.Object.fromQueryString(colors=red&colors=green&colors=blue); // returns {colors: ['red', 'green', 'blue']} + * + * Recursive: + * + * Ext.Object.fromQueryString("username=Jacky&dateOfBirth[day]=1&dateOfBirth[month]=2&dateOfBirth[year]=1911&hobbies[0]=coding&hobbies[1]=eating&hobbies[2]=sleeping&hobbies[3][0]=nested&hobbies[3][1]=stuff", true); + * // returns + * { + * username: 'Jacky', + * dateOfBirth: { + * day: '1', + * month: '2', + * year: '1911' + * }, + * hobbies: ['coding', 'eating', 'sleeping', ['nested', 'stuff']] + * } + * * @param {String} queryString The query string to decode - * @param {Boolean} recursive (Optional) Whether or not to recursively decode the string. This format is supported by - * PHP / Ruby on Rails servers and similar. Defaults to false + * @param {Boolean} [recursive=false] Whether or not to recursively decode the string. This format is supported by + * PHP / Ruby on Rails servers and similar. * @return {Object} */ fromQueryString: function(queryString, recursive) { @@ -287,32 +284,29 @@ var ExtObject = Ext.Object = { }, /** - * Iterate through an object and invoke the given callback function for each iteration. The iteration can be stop - * by returning `false` in the callback function. For example: - - var person = { - name: 'Jacky' - hairColor: 'black' - loves: ['food', 'sleeping', 'wife'] - }; - - Ext.Object.each(person, function(key, value, myself) { - console.log(key + ":" + value); - - if (key === 'hairColor') { - return false; // stop the iteration - } - }); - + * Iterates through an object and invokes the given callback function for each iteration. + * The iteration can be stopped by returning `false` in the callback function. For example: + * + * var person = { + * name: 'Jacky' + * hairColor: 'black' + * loves: ['food', 'sleeping', 'wife'] + * }; + * + * Ext.Object.each(person, function(key, value, myself) { + * console.log(key + ":" + value); + * + * if (key === 'hairColor') { + * return false; // stop the iteration + * } + * }); + * * @param {Object} object The object to iterate - * @param {Function} fn The callback function. Passed arguments for each iteration are: - -- {String} `key` -- {Mixed} `value` -- {Object} `object` The object itself - - * @param {Object} scope (Optional) The execution scope (`this`) of the callback function - * @markdown + * @param {Function} fn The callback function. + * @param {String} fn.key + * @param {Object} fn.value + * @param {Object} fn.object The object itself + * @param {Object} [scope] The execution scope (`this`) of the callback function */ each: function(object, fn, scope) { for (var property in object) { @@ -326,44 +320,43 @@ var ExtObject = Ext.Object = { /** * Merges any number of objects recursively without referencing them or their children. - - var extjs = { - companyName: 'Ext JS', - products: ['Ext JS', 'Ext GWT', 'Ext Designer'], - isSuperCool: true - office: { - size: 2000, - location: 'Palo Alto', - isFun: true - } - }; - - var newStuff = { - companyName: 'Sencha Inc.', - products: ['Ext JS', 'Ext GWT', 'Ext Designer', 'Sencha Touch', 'Sencha Animator'], - office: { - size: 40000, - location: 'Redwood City' - } - }; - - var sencha = Ext.Object.merge(extjs, newStuff); - - // extjs and sencha then equals to - { - companyName: 'Sencha Inc.', - products: ['Ext JS', 'Ext GWT', 'Ext Designer', 'Sencha Touch', 'Sencha Animator'], - isSuperCool: true - office: { - size: 30000, - location: 'Redwood City' - isFun: true - } - } - - * @param {Object} object,... + * + * var extjs = { + * companyName: 'Ext JS', + * products: ['Ext JS', 'Ext GWT', 'Ext Designer'], + * isSuperCool: true + * office: { + * size: 2000, + * location: 'Palo Alto', + * isFun: true + * } + * }; + * + * var newStuff = { + * companyName: 'Sencha Inc.', + * products: ['Ext JS', 'Ext GWT', 'Ext Designer', 'Sencha Touch', 'Sencha Animator'], + * office: { + * size: 40000, + * location: 'Redwood City' + * } + * }; + * + * var sencha = Ext.Object.merge(extjs, newStuff); + * + * // extjs and sencha then equals to + * { + * companyName: 'Sencha Inc.', + * products: ['Ext JS', 'Ext GWT', 'Ext Designer', 'Sencha Touch', 'Sencha Animator'], + * isSuperCool: true + * office: { + * size: 30000, + * location: 'Redwood City' + * isFun: true + * } + * } + * + * @param {Object...} object Any number of objects to merge. * @return {Object} merged The object that is created as a result of merging all the objects passed in. - * @markdown */ merge: function(source, key, value) { if (typeof key === 'string') { @@ -402,17 +395,16 @@ var ExtObject = Ext.Object = { /** * Returns the first matching key corresponding to the given value. * If no matching value is found, null is returned. - - var person = { - name: 'Jacky', - loves: 'food' - }; - - alert(Ext.Object.getKey(sencha, 'loves')); // alerts 'food' - + * + * var person = { + * name: 'Jacky', + * loves: 'food' + * }; + * + * alert(Ext.Object.getKey(person, 'food')); // alerts 'loves' + * * @param {Object} object * @param {Object} value The value to find - * @markdown */ getKey: function(object, value) { for (var property in object) { @@ -426,15 +418,14 @@ var ExtObject = Ext.Object = { /** * Gets all values of the given object as an array. - - var values = Ext.Object.getValues({ - name: 'Jacky', - loves: 'food' - }); // ['Jacky', 'food'] - + * + * var values = Ext.Object.getValues({ + * name: 'Jacky', + * loves: 'food' + * }); // ['Jacky', 'food'] + * * @param {Object} object * @return {Array} An array of values from the object - * @markdown */ getValues: function(object) { var values = [], @@ -451,14 +442,14 @@ var ExtObject = Ext.Object = { /** * Gets all keys of the given object as an array. - - var values = Ext.Object.getKeys({ - name: 'Jacky', - loves: 'food' - }); // ['name', 'loves'] - + * + * var values = Ext.Object.getKeys({ + * name: 'Jacky', + * loves: 'food' + * }); // ['name', 'loves'] + * * @param {Object} object - * @return {Array} An array of keys from the object + * @return {String[]} An array of keys from the object * @method */ getKeys: ('keys' in Object.prototype) ? Object.keys : function(object) { @@ -476,15 +467,14 @@ var ExtObject = Ext.Object = { /** * Gets the total number of this object's own properties - - var size = Ext.Object.getSize({ - name: 'Jacky', - loves: 'food' - }); // size equals 2 - + * + * var size = Ext.Object.getSize({ + * name: 'Jacky', + * loves: 'food' + * }); // size equals 2 + * * @param {Object} object * @return {Number} size - * @markdown */ getSize: function(object) { var size = 0, @@ -502,19 +492,21 @@ var ExtObject = Ext.Object = { /** - * A convenient alias method for {@link Ext.Object#merge} + * A convenient alias method for {@link Ext.Object#merge}. * * @member Ext * @method merge + * @alias Ext.Object#merge */ Ext.merge = Ext.Object.merge; /** - * A convenient alias method for {@link Ext.Object#toQueryString} + * Alias for {@link Ext.Object#toQueryString}. * * @member Ext * @method urlEncode - * @deprecated 4.0.0 Use {@link Ext.Object#toQueryString Ext.Object.toQueryString} instead + * @alias Ext.Object#toQueryString + * @deprecated 4.0.0 Use {@link Ext.Object#toQueryString} instead */ Ext.urlEncode = function() { var args = Ext.Array.from(arguments), @@ -530,11 +522,12 @@ Ext.urlEncode = function() { }; /** - * A convenient alias method for {@link Ext.Object#fromQueryString} + * Alias for {@link Ext.Object#fromQueryString}. * * @member Ext * @method urlDecode - * @deprecated 4.0.0 Use {@link Ext.Object#fromQueryString Ext.Object.fromQueryString} instead + * @alias Ext.Object#fromQueryString + * @deprecated 4.0.0 Use {@link Ext.Object#fromQueryString} instead */ Ext.urlDecode = function() { return Ext.Object.fromQueryString.apply(Ext.Object, arguments);