* @docauthor Jacky Nguyen <jacky@sencha.com>
* @class Ext.Object
*
- * A collection of useful static methods to deal with objects
+ * A collection of useful static methods to deal with objects.
*
* @singleton
*/
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,
},
/**
- * 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 = [],
/**
* 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) {
},
/**
- * 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) {
/**
* 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') {
/**
* 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) {
/**
* 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 = [],
/**
* 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) {
/**
* 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,
/**
- * 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),
};
/**
- * 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);
git.ithinksw.org / extjs.git / blobdiff