/*
-Ext JS - JavaScript Library
-Copyright (c) 2006-2011, Sencha Inc.
-All rights reserved.
-licensing@sencha.com
+
+This file is part of Ext JS 4
+
+Copyright (c) 2011 Sencha Inc
+
+Contact: http://www.sencha.com/contact
+
+GNU General Public License Usage
+This file may be used under the terms of the GNU General Public License version 3.0 as published by the Free Software Foundation and appearing in the file LICENSE included in the packaging of this file. Please review the following information to ensure the GNU General Public License version 3.0 requirements will be met: http://www.gnu.org/copyleft/gpl.html.
+
+If you are unsure which license is appropriate for your use, please contact the sales department at http://www.sencha.com/contact.
+
*/
/**
* @class Ext
(function() {
var global = this,
objectPrototype = Object.prototype,
- toString = Object.prototype.toString,
+ toString = objectPrototype.toString,
enumerables = true,
enumerablesTest = { toString: 1 },
i;
/**
* An array containing extra enumerables for old browsers
- * @type Array
+ * @property {String[]}
*/
Ext.enumerables = enumerables;
/**
* Copies all the properties of config to object if they don't already exist.
- * @function
* @param {Object} object The receiver of the properties
* @param {Object} config The source of the properties
* @return {Object} returns obj
/**
* This method deprecated. Use {@link Ext#define Ext.define} instead.
- * @function
+ * @method
* @param {Function} superclass
* @param {Object} overrides
* @return {Function} The subclass constructor from the <tt>overrides</tt> parameter, or a generated one if not provided.
* Returns the given value itself if it's not empty, as described in {@link Ext#isEmpty}; returns the default
* value (second argument) otherwise.
*
- * @param {Mixed} value The value to test
- * @param {Mixed} defaultValue The value to return if the original value is empty
+ * @param {Object} value The value to test
+ * @param {Object} defaultValue The value to return if the original value is empty
* @param {Boolean} allowBlank (optional) true to allow zero length strings to qualify as non-empty (defaults to false)
- * @return {Mixed} value, if non-empty, else defaultValue
+ * @return {Object} value, if non-empty, else defaultValue
*/
valueFrom: function(value, defaultValue, allowBlank){
return Ext.isEmpty(value, allowBlank) ? defaultValue : value;
* - `textnode`: If the given value is a DOM text node and contains something other than whitespace
* - `whitespace`: If the given value is a DOM text node and contains only whitespace
*
- * @param {Mixed} value
+ * @param {Object} value
* @return {String}
* @markdown
*/
* - a zero-length array
* - a zero-length string (Unless the `allowEmptyString` parameter is set to `true`)
*
- * @param {Mixed} value The value to test
+ * @param {Object} value The value to test
* @param {Boolean} allowEmptyString (optional) true to allow empty strings (defaults to false)
* @return {Boolean}
* @markdown
/**
* Returns true if the passed value is a JavaScript Array, false otherwise.
*
- * @param {Mixed} target The target to test
+ * @param {Object} target The target to test
* @return {Boolean}
+ * @method
*/
isArray: ('isArray' in Array) ? Array.isArray : function(value) {
return toString.call(value) === '[object Array]';
/**
* Returns true if the passed value is a JavaScript Object, false otherwise.
- * @param {Mixed} value The value to test
+ * @param {Object} value The value to test
* @return {Boolean}
+ * @method
*/
isObject: (toString.call(null) === '[object Object]') ?
function(value) {
- return value !== null && value !== undefined && toString.call(value) === '[object Object]' && value.nodeType === undefined;
+ // check ownerDocument here as well to exclude DOM nodes
+ return value !== null && value !== undefined && toString.call(value) === '[object Object]' && value.ownerDocument === undefined;
} :
function(value) {
return toString.call(value) === '[object Object]';
/**
* Returns true if the passed value is a JavaScript 'primitive', a string, number or boolean.
- * @param {Mixed} value The value to test
+ * @param {Object} value The value to test
* @return {Boolean}
*/
isPrimitive: function(value) {
/**
* Returns true if the passed value is a JavaScript Function, false otherwise.
- * @param {Mixed} value The value to test
+ * @param {Object} value The value to test
* @return {Boolean}
+ * @method
*/
isFunction:
// Safari 3.x and 4.x returns 'function' for typeof <NodeList>, hence we need to fall back to using
/**
* Returns true if the passed value is a number. Returns false for non-finite numbers.
- * @param {Mixed} value The value to test
+ * @param {Object} value The value to test
* @return {Boolean}
*/
isNumber: function(value) {
/**
* Validates that a value is numeric.
- * @param {Mixed} value Examples: 1, '1', '2.34'
+ * @param {Object} value Examples: 1, '1', '2.34'
* @return {Boolean} True if numeric, false otherwise
*/
isNumeric: function(value) {
/**
* Returns true if the passed value is a string.
- * @param {Mixed} value The value to test
+ * @param {Object} value The value to test
* @return {Boolean}
*/
isString: function(value) {
/**
* Returns true if the passed value is a boolean.
*
- * @param {Mixed} value The value to test
+ * @param {Object} value The value to test
* @return {Boolean}
*/
isBoolean: function(value) {
/**
* Returns true if the passed value is an HTMLElement
- * @param {Mixed} value The value to test
+ * @param {Object} value The value to test
* @return {Boolean}
*/
isElement: function(value) {
- return value ? value.nodeType !== undefined : false;
+ return value ? value.nodeType === 1 : false;
},
/**
* Returns true if the passed value is a TextNode
- * @param {Mixed} value The value to test
+ * @param {Object} value The value to test
* @return {Boolean}
*/
isTextNode: function(value) {
/**
* Returns true if the passed value is defined.
- * @param {Mixed} value The value to test
+ * @param {Object} value The value to test
* @return {Boolean}
*/
isDefined: function(value) {
/**
* Returns true if the passed value is iterable, false otherwise
- * @param {Mixed} value The value to test
+ * @param {Object} value The value to test
* @return {Boolean}
*/
isIterable: function(value) {
/**
* Clone almost any type of variable including array, object, DOM nodes and Date without keeping the old reference
- * @param {Mixed} item The variable to clone
- * @return {Mixed} clone
+ * @param {Object} item The variable to clone
+ * @return {Object} clone
*/
clone: function(item) {
if (item === null || item === undefined) {
var i = 0;
do {
- uniqueGlobalNamespace = 'ExtSandbox' + (++i);
+ uniqueGlobalNamespace = 'ExtBox' + (++i);
} while (Ext.global[uniqueGlobalNamespace] !== undefined);
Ext.global[uniqueGlobalNamespace] = Ext;
/**
* Old alias to {@link Ext#typeOf}
* @deprecated 4.0.0 Use {@link Ext#typeOf} instead
+ * @method
+ * @alias Ext#typeOf
*/
Ext.type = Ext.typeOf;
(function() {
// Current core version
-var version = '4.0.0', Version;
+var version = '4.0.7', Version;
Ext.Version = Version = Ext.extend(Object, {
/**
- * @constructor
* @param {String/Number} version The version number in the follow standard format: major[.minor[.patch[.build[release]]]]
* Examples: 1.0 or 1.2.3beta or 1.2.3.4RC
* @return {Ext.Version} this
- * @param version
*/
constructor: function(version) {
var parts, releaseStartIndex;
/**
* Returns this format: [major, minor, patch, build, release]. Useful for comparison
- * @return {Array}
+ * @return {Number[]}
*/
toArray: function() {
return [this.getMajor(), this.getMinor(), this.getPatch(), this.getBuild(), this.getRelease()];
* Converts a version component to a comparable value
*
* @static
- * @param {Mixed} value The value to convert
- * @return {Mixed}
+ * @param {Object} value The value to convert
+ * @return {Object}
*/
getComponentValue: function(value) {
return !value ? 0 : (isNaN(value) ? this.releaseValueMap[value] || value : parseInt(value, 10));
escapeRegexRe: /([-.*+?^${}()|[\]\/\\])/g,
/**
- * Convert certain characters (&, <, >, and ') to their HTML character equivalents for literal display in web pages.
+ * Convert certain characters (&, <, >, and ") to their HTML character equivalents for literal display in web pages.
* @param {String} value The string to encode
* @return {String} The encoded text
+ * @method
*/
htmlEncode: (function() {
var entities = {
})(),
/**
- * Convert certain characters (&, <, >, and ') from their HTML character equivalents.
+ * Convert certain characters (&, <, >, and ") from their HTML character equivalents.
* @param {String} value The string to decode
* @return {String} The decoded text
+ * @method
*/
htmlDecode: (function() {
var entities = {
return format.replace(Ext.String.formatRe, function(m, i) {
return args[i];
});
+ },
+
+ /**
+ * Returns a string with a specified number of repititions a given string pattern.
+ * The pattern be separated by a different string.
+ *
+ * var s = Ext.String.repeat('---', 4); // = '------------'
+ * var t = Ext.String.repeat('--', 3, '/'); // = '--/--/--'
+ *
+ * @param {String} pattern The pattern to repeat.
+ * @param {Number} count The number of times to repeat the pattern (may be 0).
+ * @param {String} sep An option string to separate each pattern.
+ */
+ repeat: function(pattern, count, sep) {
+ for (var buf = [], i = count; i--; ) {
+ buf.push(pattern);
+ }
+ return buf.join(sep || '');
}
};
Ext.Number = {
/**
- * Checks whether or not the current number is within a desired range. If the number is already within the
+ * Checks whether or not the passed number is within a desired range. If the number is already within the
* range it is returned, otherwise the min or max value is returned depending on which side of the range is
* exceeded. Note that this method returns the constrained value but does not change the current number.
* @param {Number} number The number to check
return number;
},
+ /**
+ * Snaps the passed number between stopping points based upon a passed increment value.
+ * @param {Number} value The unsnapped value.
+ * @param {Number} increment The increment by which the value must move.
+ * @param {Number} minValue The minimum value to which the returned value must be constrained. Overrides the increment..
+ * @param {Number} maxValue The maximum value to which the returned value must be constrained. Overrides the increment..
+ * @return {Number} The value of the nearest snap target.
+ */
+ snap : function(value, increment, minValue, maxValue) {
+ var newValue = value,
+ m;
+
+ if (!(increment && value)) {
+ return value;
+ }
+ m = value % increment;
+ if (m !== 0) {
+ newValue -= m;
+ if (m * 2 >= increment) {
+ newValue += increment;
+ } else if (m * 2 < -increment) {
+ newValue -= increment;
+ }
+ }
+ return Ext.Number.constrain(newValue, minValue, maxValue);
+ },
+
/**
* Formats a number using fixed-point notation
* @param {Number} value The number to format
Ext.Number.from('1.23', 1); // returns 1.23
Ext.Number.from('abc', 1); // returns 1
- * @param {Mixed} value
+ * @param {Object} value
* @param {Number} defaultValue The value to return if the original value is non-numeric
* @return {Number} value, if numeric, defaultValue otherwise
*/
})();
/**
- * This method is deprecated, please use {@link Ext.Number#from Ext.Number.from} instead
- *
- * @deprecated 4.0.0 Replaced by Ext.Number.from
+ * @deprecated 4.0.0 Please use {@link Ext.Number#from} instead.
* @member Ext
* @method num
+ * @alias Ext.Number#from
*/
Ext.num = function() {
return Ext.Number.from.apply(this, arguments);
};
/**
+ * @class Ext.Array
+ * @singleton
* @author Jacky Nguyen <jacky@sencha.com>
* @docauthor Jacky Nguyen <jacky@sencha.com>
- * @class Ext.Array
*
* A set of useful static methods to deal with arrays; provide missing methods for older browsers.
-
- * @singleton
- * @markdown
*/
(function() {
var arrayPrototype = Array.prototype,
slice = arrayPrototype.slice,
+ supportsSplice = function () {
+ var array = [],
+ lengthBefore,
+ j = 20;
+
+ if (!array.splice) {
+ return false;
+ }
+
+ // This detects a bug in IE8 splice method:
+ // see http://social.msdn.microsoft.com/Forums/en-US/iewebdevelopment/thread/6e946d03-e09f-4b22-a4dd-cd5e276bf05a/
+
+ while (j--) {
+ array.push("A");
+ }
+
+ array.splice(15, 0, "F", "F", "F", "F", "F","F","F","F","F","F","F","F","F","F","F","F","F","F","F","F","F");
+
+ lengthBefore = array.length; //41
+ array.splice(13, 0, "XXX"); // add one element
+
+ if (lengthBefore+1 != array.length) {
+ return false;
+ }
+ // end IE8 bug
+
+ return true;
+ }(),
supportsForEach = 'forEach' in arrayPrototype,
supportsMap = 'map' in arrayPrototype,
supportsIndexOf = 'indexOf' in arrayPrototype,
}(),
supportsSliceOnNodeList = true,
ExtArray;
+
try {
// IE 6 - 8 will throw an error when using Array.prototype.slice on NodeList
if (typeof document !== 'undefined') {
supportsSliceOnNodeList = false;
}
- ExtArray = Ext.Array = {
- /*
- * Iterates an array or an iterable value and invoke the given callback function for each item.
+ function fixArrayIndex (array, index) {
+ return (index < 0) ? Math.max(0, array.length + index)
+ : Math.min(array.length, index);
+ }
+
+ /*
+ Does the same work as splice, but with a slightly more convenient signature. The splice
+ method has bugs in IE8, so this is the implementation we use on that platform.
+
+ The rippling of items in the array can be tricky. Consider two use cases:
+
+ index=2
+ removeCount=2
+ /=====\
+ +---+---+---+---+---+---+---+---+
+ | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 |
+ +---+---+---+---+---+---+---+---+
+ / \/ \/ \/ \
+ / /\ /\ /\ \
+ / / \/ \/ \ +--------------------------+
+ / / /\ /\ +--------------------------+ \
+ / / / \/ +--------------------------+ \ \
+ / / / /+--------------------------+ \ \ \
+ / / / / \ \ \ \
+ v v v v v v v v
+ +---+---+---+---+---+---+ +---+---+---+---+---+---+---+---+---+
+ | 0 | 1 | 4 | 5 | 6 | 7 | | 0 | 1 | a | b | c | 4 | 5 | 6 | 7 |
+ +---+---+---+---+---+---+ +---+---+---+---+---+---+---+---+---+
+ A B \=========/
+ insert=[a,b,c]
+
+ In case A, it is obvious that copying of [4,5,6,7] must be left-to-right so
+ that we don't end up with [0,1,6,7,6,7]. In case B, we have the opposite; we
+ must go right-to-left or else we would end up with [0,1,a,b,c,4,4,4,4].
+ */
+ function replaceSim (array, index, removeCount, insert) {
+ var add = insert ? insert.length : 0,
+ length = array.length,
+ pos = fixArrayIndex(array, index);
+
+ // we try to use Array.push when we can for efficiency...
+ if (pos === length) {
+ if (add) {
+ array.push.apply(array, insert);
+ }
+ } else {
+ var remove = Math.min(removeCount, length - pos),
+ tailOldPos = pos + remove,
+ tailNewPos = tailOldPos + add - remove,
+ tailCount = length - tailOldPos,
+ lengthAfterRemove = length - remove,
+ i;
- var countries = ['Vietnam', 'Singapore', 'United States', 'Russia'];
+ if (tailNewPos < tailOldPos) { // case A
+ for (i = 0; i < tailCount; ++i) {
+ array[tailNewPos+i] = array[tailOldPos+i];
+ }
+ } else if (tailNewPos > tailOldPos) { // case B
+ for (i = tailCount; i--; ) {
+ array[tailNewPos+i] = array[tailOldPos+i];
+ }
+ } // else, add == remove (nothing to do)
- Ext.Array.each(countries, function(name, index, countriesItSelf) {
- console.log(name);
- });
+ if (add && pos === lengthAfterRemove) {
+ array.length = lengthAfterRemove; // truncate array
+ array.push.apply(array, insert);
+ } else {
+ array.length = lengthAfterRemove + add; // reserves space
+ for (i = 0; i < add; ++i) {
+ array[pos+i] = insert[i];
+ }
+ }
+ }
- var sum = function() {
- var sum = 0;
+ return array;
+ }
- Ext.Array.each(arguments, function(value) {
- sum += value;
- });
+ function replaceNative (array, index, removeCount, insert) {
+ if (insert && insert.length) {
+ if (index < array.length) {
+ array.splice.apply(array, [index, removeCount].concat(insert));
+ } else {
+ array.push.apply(array, insert);
+ }
+ } else {
+ array.splice(index, removeCount);
+ }
+ return array;
+ }
- return sum;
- };
+ function eraseSim (array, index, removeCount) {
+ return replaceSim(array, index, removeCount);
+ }
- sum(1, 2, 3); // returns 6
+ function eraseNative (array, index, removeCount) {
+ array.splice(index, removeCount);
+ return array;
+ }
- * The iteration can be stopped by returning false in the function callback.
+ function spliceSim (array, index, removeCount) {
+ var pos = fixArrayIndex(array, index),
+ removed = array.slice(index, fixArrayIndex(array, pos+removeCount));
- Ext.Array.each(countries, function(name, index, countriesItSelf) {
- if (name === 'Singapore') {
- return false; // break here
+ if (arguments.length < 4) {
+ replaceSim(array, pos, removeCount);
+ } else {
+ replaceSim(array, pos, removeCount, slice.call(arguments, 3));
}
- });
- * @param {Array/NodeList/Mixed} iterable The value to be iterated. If this
- * argument is not iterable, the callback function is called once.
- * @param {Function} fn The callback function. If it returns false, the iteration stops and this method returns
- * the current `index`. Arguments passed to this callback function are:
+ return removed;
+ }
+
+ function spliceNative (array) {
+ return array.splice.apply(array, slice.call(arguments, 1));
+ }
+
+ var erase = supportsSplice ? eraseNative : eraseSim,
+ replace = supportsSplice ? replaceNative : replaceSim,
+ splice = supportsSplice ? spliceNative : spliceSim;
-- `item`: {Mixed} The item at the current `index` in the passed `array`
-- `index`: {Number} The current `index` within the `array`
-- `allItems`: {Array/NodeList/Mixed} The `array` passed as the first argument to `Ext.Array.each`
+ // NOTE: from here on, use erase, replace or splice (not native methods)...
+ ExtArray = Ext.Array = {
+ /**
+ * Iterates an array or an iterable value and invoke the given callback function for each item.
+ *
+ * var countries = ['Vietnam', 'Singapore', 'United States', 'Russia'];
+ *
+ * Ext.Array.each(countries, function(name, index, countriesItSelf) {
+ * console.log(name);
+ * });
+ *
+ * var sum = function() {
+ * var sum = 0;
+ *
+ * Ext.Array.each(arguments, function(value) {
+ * sum += value;
+ * });
+ *
+ * return sum;
+ * };
+ *
+ * sum(1, 2, 3); // returns 6
+ *
+ * The iteration can be stopped by returning false in the function callback.
+ *
+ * Ext.Array.each(countries, function(name, index, countriesItSelf) {
+ * if (name === 'Singapore') {
+ * return false; // break here
+ * }
+ * });
+ *
+ * {@link Ext#each Ext.each} is alias for {@link Ext.Array#each Ext.Array.each}
+ *
+ * @param {Array/NodeList/Object} iterable The value to be iterated. If this
+ * argument is not iterable, the callback function is called once.
+ * @param {Function} fn The callback function. If it returns false, the iteration stops and this method returns
+ * the current `index`.
+ * @param {Object} fn.item The item at the current `index` in the passed `array`
+ * @param {Number} fn.index The current `index` within the `array`
+ * @param {Array} fn.allItems The `array` itself which was passed as the first argument
+ * @param {Boolean} fn.return Return false to stop iteration.
* @param {Object} scope (Optional) The scope (`this` reference) in which the specified function is executed.
* @param {Boolean} reverse (Optional) Reverse the iteration order (loop from the end to the beginning)
* Defaults false
* @return {Boolean} See description for the `fn` parameter.
- * @markdown
*/
each: function(array, fn, scope, reverse) {
array = ExtArray.from(array);
/**
* Iterates an array and invoke the given callback function for each item. Note that this will simply
- * delegate to the native Array.prototype.forEach method if supported.
- * It doesn't support stopping the iteration by returning false in the callback function like
- * {@link Ext.Array#each}. However, performance could be much better in modern browsers comparing with
- * {@link Ext.Array#each}
+ * delegate to the native Array.prototype.forEach method if supported. It doesn't support stopping the
+ * iteration by returning false in the callback function like {@link Ext.Array#each}. However, performance
+ * could be much better in modern browsers comparing with {@link Ext.Array#each}
*
* @param {Array} array The array to iterate
- * @param {Function} fn The function callback, to be invoked these arguments:
- *
-- `item`: {Mixed} The item at the current `index` in the passed `array`
-- `index`: {Number} The current `index` within the `array`
-- `allItems`: {Array} The `array` itself which was passed as the first argument
-
+ * @param {Function} fn The callback function.
+ * @param {Object} fn.item The item at the current `index` in the passed `array`
+ * @param {Number} fn.index The current `index` within the `array`
+ * @param {Array} fn.allItems The `array` itself which was passed as the first argument
* @param {Object} scope (Optional) The execution scope (`this`) in which the specified function is executed.
- * @markdown
*/
forEach: function(array, fn, scope) {
if (supportsForEach) {
* missing arrayPrototype.indexOf in Internet Explorer.
*
* @param {Array} array The array to check
- * @param {Mixed} item The item to look for
+ * @param {Object} item The item to look for
* @param {Number} from (Optional) The index at which to begin the search
* @return {Number} The index of item in the array (or -1 if it is not found)
- * @markdown
*/
indexOf: function(array, item, from) {
if (supportsIndexOf) {
* Checks whether or not the given `array` contains the specified `item`
*
* @param {Array} array The array to check
- * @param {Mixed} item The item to look for
+ * @param {Object} item The item to look for
* @return {Boolean} True if the array contains the item, false otherwise
- * @markdown
*/
contains: function(array, item) {
if (supportsIndexOf) {
/**
* Converts any iterable (numeric indices and a length property) into a true array.
-
-function test() {
- var args = Ext.Array.toArray(arguments),
- fromSecondToLastArgs = Ext.Array.toArray(arguments, 1);
-
- alert(args.join(' '));
- alert(fromSecondToLastArgs.join(' '));
-}
-
-test('just', 'testing', 'here'); // alerts 'just testing here';
- // alerts 'testing here';
-
-Ext.Array.toArray(document.getElementsByTagName('div')); // will convert the NodeList into an array
-Ext.Array.toArray('splitted'); // returns ['s', 'p', 'l', 'i', 't', 't', 'e', 'd']
-Ext.Array.toArray('splitted', 0, 3); // returns ['s', 'p', 'l', 'i']
-
- * @param {Mixed} iterable the iterable object to be turned into a true Array.
+ *
+ * function test() {
+ * var args = Ext.Array.toArray(arguments),
+ * fromSecondToLastArgs = Ext.Array.toArray(arguments, 1);
+ *
+ * alert(args.join(' '));
+ * alert(fromSecondToLastArgs.join(' '));
+ * }
+ *
+ * test('just', 'testing', 'here'); // alerts 'just testing here';
+ * // alerts 'testing here';
+ *
+ * Ext.Array.toArray(document.getElementsByTagName('div')); // will convert the NodeList into an array
+ * Ext.Array.toArray('splitted'); // returns ['s', 'p', 'l', 'i', 't', 't', 'e', 'd']
+ * Ext.Array.toArray('splitted', 0, 3); // returns ['s', 'p', 'l', 'i']
+ *
+ * {@link Ext#toArray Ext.toArray} is alias for {@link Ext.Array#toArray Ext.Array.toArray}
+ *
+ * @param {Object} iterable the iterable object to be turned into a true Array.
* @param {Number} start (Optional) a zero-based index that specifies the start of extraction. Defaults to 0
* @param {Number} end (Optional) a zero-based index that specifies the end of extraction. Defaults to the last
* index of the iterable value
* @return {Array} array
- * @markdown
*/
toArray: function(iterable, start, end){
if (!iterable || !iterable.length) {
/**
* Plucks the value of a property from each item in the Array. Example:
*
- Ext.Array.pluck(Ext.query("p"), "className"); // [el1.className, el2.className, ..., elN.className]
-
- * @param {Array|NodeList} array The Array of items to pluck the value from.
+ * Ext.Array.pluck(Ext.query("p"), "className"); // [el1.className, el2.className, ..., elN.className]
+ *
+ * @param {Array/NodeList} array The Array of items to pluck the value from.
* @param {String} propertyName The property name to pluck from each element.
* @return {Array} The value from each item in the Array.
*/
/**
* Creates a new array with the results of calling a provided function on every element in this array.
+ *
* @param {Array} array
* @param {Function} fn Callback function for each item
* @param {Object} scope Callback function scope
/**
* Filter through an array and remove empty item as defined in {@link Ext#isEmpty Ext.isEmpty}
*
- * @see Ext.Array.filter
+ * See {@link Ext.Array#filter}
+ *
* @param {Array} array
* @return {Array} results
*/
/**
* Creates a new array with all of the elements of this array for which
* the provided filtering function returns true.
+ *
* @param {Array} array
* @param {Function} fn Callback function for each item
* @param {Object} scope Callback function scope
* - An array copy if given value is {@link Ext#isIterable iterable} (arguments, NodeList and alike)
* - An array with one item which is the given value, otherwise
*
- * @param {Array/Mixed} value The value to convert to an array if it's not already is an array
- * @param {Boolean} (Optional) newReference True to clone the given array and return a new reference if necessary,
+ * @param {Object} value The value to convert to an array if it's not already is an array
+ * @param {Boolean} newReference (Optional) True to clone the given array and return a new reference if necessary,
* defaults to false
* @return {Array} array
- * @markdown
*/
from: function(value, newReference) {
if (value === undefined || value === null) {
* Removes the specified item from the array if it exists
*
* @param {Array} array The array
- * @param {Mixed} item The item to remove
+ * @param {Object} item The item to remove
* @return {Array} The passed array itself
*/
remove: function(array, item) {
var index = ExtArray.indexOf(array, item);
if (index !== -1) {
- array.splice(index, 1);
+ erase(array, index, 1);
}
return array;
* Push an item into the array only if the array doesn't contain it yet
*
* @param {Array} array The array
- * @param {Mixed} item The item to include
- * @return {Array} The passed array itself
+ * @param {Object} item The item to include
*/
include: function(array, item) {
if (!ExtArray.contains(array, item)) {
},
/**
- * Merge multiple arrays into one with unique items. Alias to {@link Ext.Array#union}.
+ * Merge multiple arrays into one with unique items.
*
- * @param {Array} array,...
+ * {@link Ext.Array#union} is alias for {@link Ext.Array#merge}
+ *
+ * @param {Array} array1
+ * @param {Array} array2
+ * @param {Array} etc
* @return {Array} merged
*/
merge: function() {
/**
* Merge multiple arrays into one with unique items that exist in all of the arrays.
*
- * @param {Array} array,...
+ * @param {Array} array1
+ * @param {Array} array2
+ * @param {Array} etc
* @return {Array} intersect
*/
intersect: function() {
}
}
- minArray = Ext.Array.unique(minArray);
- arrays.splice(x, 1);
+ minArray = ExtArray.unique(minArray);
+ erase(arrays, x, 1);
// Use the smallest unique'd array as the anchor loop. If the other array(s) do contain
// an item in the small array, we're likely to find it before reaching the end
/**
* Perform a set difference A-B by subtracting all items in array B from array A.
*
- * @param {Array} array A
- * @param {Array} array B
+ * @param {Array} arrayA
+ * @param {Array} arrayB
* @return {Array} difference
*/
difference: function(arrayA, arrayB) {
for (i = 0,lnB = arrayB.length; i < lnB; i++) {
for (j = 0; j < ln; j++) {
if (clone[j] === arrayB[i]) {
- clone.splice(j, 1);
+ erase(clone, j, 1);
j--;
ln--;
}
return clone;
},
+ /**
+ * Returns a shallow copy of a part of an array. This is equivalent to the native
+ * call "Array.prototype.slice.call(array, begin, end)". This is often used when "array"
+ * is "arguments" since the arguments object does not supply a slice method but can
+ * be the context object to Array.prototype.slice.
+ *
+ * @param {Array} array The array (or arguments object).
+ * @param {Number} begin The index at which to begin. Negative values are offsets from
+ * the end of the array.
+ * @param {Number} end The index at which to end. The copied items do not include
+ * end. Negative values are offsets from the end of the array. If end is omitted,
+ * all items up to the end of the array are copied.
+ * @return {Array} The copied piece of the array.
+ */
+ // Note: IE6 will return [] on slice.call(x, undefined).
+ slice: ([1,2].slice(1, undefined).length ?
+ function (array, begin, end) {
+ return slice.call(array, begin, end);
+ } :
+ // at least IE6 uses arguments.length for variadic signature
+ function (array, begin, end) {
+ // After tested for IE 6, the one below is of the best performance
+ // see http://jsperf.com/slice-fix
+ if (typeof begin === 'undefined') {
+ return slice.call(array);
+ }
+ if (typeof end === 'undefined') {
+ return slice.call(array, begin);
+ }
+ return slice.call(array, begin, end);
+ }
+ ),
+
/**
* Sorts the elements of an Array.
* By default, this method sorts the elements alphabetically and ascending.
/**
* Recursively flattens into 1-d Array. Injects Arrays inline.
+ *
* @param {Array} array The array to flatten
- * @return {Array} The new, flattened array.
+ * @return {Array} The 1-d array.
*/
flatten: function(array) {
var worker = [];
/**
* Returns the minimum value in the Array.
- * @param {Array|NodeList} array The Array from which to select the minimum value.
+ *
+ * @param {Array/NodeList} array The Array from which to select the minimum value.
* @param {Function} comparisonFn (optional) a function to perform the comparision which determines minimization.
- * If omitted the "<" operator will be used. Note: gt = 1; eq = 0; lt = -1
- * @return {Mixed} minValue The minimum value
+ * If omitted the "<" operator will be used. Note: gt = 1; eq = 0; lt = -1
+ * @return {Object} minValue The minimum value
*/
min: function(array, comparisonFn) {
var min = array[0],
},
/**
- * Returns the maximum value in the Array
- * @param {Array|NodeList} array The Array from which to select the maximum value.
+ * Returns the maximum value in the Array.
+ *
+ * @param {Array/NodeList} array The Array from which to select the maximum value.
* @param {Function} comparisonFn (optional) a function to perform the comparision which determines maximization.
- * If omitted the ">" operator will be used. Note: gt = 1; eq = 0; lt = -1
- * @return {Mixed} maxValue The maximum value
+ * If omitted the ">" operator will be used. Note: gt = 1; eq = 0; lt = -1
+ * @return {Object} maxValue The maximum value
*/
max: function(array, comparisonFn) {
var max = array[0],
},
/**
- * Calculates the mean of all items in the array
+ * Calculates the mean of all items in the array.
+ *
* @param {Array} array The Array to calculate the mean value of.
* @return {Number} The mean.
*/
},
/**
- * Calculates the sum of all items in the given array
+ * Calculates the sum of all items in the given array.
+ *
* @param {Array} array The Array to calculate the sum value of.
* @return {Number} The sum.
*/
}
return sum;
- }
+ },
+
+ //<debug>
+ _replaceSim: replaceSim, // for unit testing
+ _spliceSim: spliceSim,
+ //</debug>
+
+ /**
+ * Removes items from an array. This is functionally equivalent to the splice method
+ * of Array, but works around bugs in IE8's splice method and does not copy the
+ * removed elements in order to return them (because very often they are ignored).
+ *
+ * @param {Array} array The Array on which to replace.
+ * @param {Number} index The index in the array at which to operate.
+ * @param {Number} removeCount The number of items to remove at index.
+ * @return {Array} The array passed.
+ * @method
+ */
+ erase: erase,
+
+ /**
+ * Inserts items in to an array.
+ *
+ * @param {Array} array The Array on which to replace.
+ * @param {Number} index The index in the array at which to operate.
+ * @param {Array} items The array of items to insert at index.
+ * @return {Array} The array passed.
+ */
+ insert: function (array, index, items) {
+ return replace(array, index, 0, items);
+ },
+
+ /**
+ * Replaces items in an array. This is functionally equivalent to the splice method
+ * of Array, but works around bugs in IE8's splice method and is often more convenient
+ * to call because it accepts an array of items to insert rather than use a variadic
+ * argument list.
+ *
+ * @param {Array} array The Array on which to replace.
+ * @param {Number} index The index in the array at which to operate.
+ * @param {Number} removeCount The number of items to remove at index (can be 0).
+ * @param {Array} insert (optional) An array of items to insert at index.
+ * @return {Array} The array passed.
+ * @method
+ */
+ replace: replace,
+ /**
+ * Replaces items in an array. This is equivalent to the splice method of Array, but
+ * works around bugs in IE8's splice method. The signature is exactly the same as the
+ * splice method except that the array is the first argument. All arguments following
+ * removeCount are inserted in the array at index.
+ *
+ * @param {Array} array The Array on which to replace.
+ * @param {Number} index The index in the array at which to operate.
+ * @param {Number} removeCount The number of items to remove at index (can be 0).
+ * @return {Array} An array containing the removed items.
+ * @method
+ */
+ splice: splice
};
/**
- * Convenient alias to {@link Ext.Array#each}
+ * @method
* @member Ext
- * @method each
+ * @alias Ext.Array#each
*/
- Ext.each = Ext.Array.each;
+ Ext.each = ExtArray.each;
/**
- * Alias to {@link Ext.Array#merge}.
+ * @method
* @member Ext.Array
- * @method union
+ * @alias Ext.Array#merge
*/
- Ext.Array.union = Ext.Array.merge;
+ ExtArray.union = ExtArray.merge;
/**
* Old alias to {@link Ext.Array#min}
* @deprecated 4.0.0 Use {@link Ext.Array#min} instead
+ * @method
* @member Ext
- * @method min
+ * @alias Ext.Array#min
*/
- Ext.min = Ext.Array.min;
+ Ext.min = ExtArray.min;
/**
* Old alias to {@link Ext.Array#max}
* @deprecated 4.0.0 Use {@link Ext.Array#max} instead
+ * @method
* @member Ext
- * @method max
+ * @alias Ext.Array#max
*/
- Ext.max = Ext.Array.max;
+ Ext.max = ExtArray.max;
/**
* Old alias to {@link Ext.Array#sum}
* @deprecated 4.0.0 Use {@link Ext.Array#sum} instead
+ * @method
* @member Ext
- * @method sum
+ * @alias Ext.Array#sum
*/
- Ext.sum = Ext.Array.sum;
+ Ext.sum = ExtArray.sum;
/**
* Old alias to {@link Ext.Array#mean}
* @deprecated 4.0.0 Use {@link Ext.Array#mean} instead
+ * @method
* @member Ext
- * @method mean
+ * @alias Ext.Array#mean
*/
- Ext.mean = Ext.Array.mean;
+ Ext.mean = ExtArray.mean;
/**
* Old alias to {@link Ext.Array#flatten}
* @deprecated 4.0.0 Use {@link Ext.Array#flatten} instead
+ * @method
* @member Ext
- * @method flatten
+ * @alias Ext.Array#flatten
*/
- Ext.flatten = Ext.Array.flatten;
+ Ext.flatten = ExtArray.flatten;
/**
- * Old alias to {@link Ext.Array#clean Ext.Array.clean}
- * @deprecated 4.0.0 Use {@link Ext.Array.clean} instead
+ * Old alias to {@link Ext.Array#clean}
+ * @deprecated 4.0.0 Use {@link Ext.Array#clean} instead
+ * @method
* @member Ext
- * @method clean
+ * @alias Ext.Array#clean
*/
- Ext.clean = Ext.Array.clean;
+ Ext.clean = ExtArray.clean;
/**
- * Old alias to {@link Ext.Array#unique Ext.Array.unique}
- * @deprecated 4.0.0 Use {@link Ext.Array.unique} instead
+ * Old alias to {@link Ext.Array#unique}
+ * @deprecated 4.0.0 Use {@link Ext.Array#unique} instead
+ * @method
* @member Ext
- * @method unique
+ * @alias Ext.Array#unique
*/
- Ext.unique = Ext.Array.unique;
+ Ext.unique = ExtArray.unique;
/**
* Old alias to {@link Ext.Array#pluck Ext.Array.pluck}
* @deprecated 4.0.0 Use {@link Ext.Array#pluck Ext.Array.pluck} instead
+ * @method
* @member Ext
- * @method pluck
+ * @alias Ext.Array#pluck
*/
- Ext.pluck = Ext.Array.pluck;
+ Ext.pluck = ExtArray.pluck;
/**
- * Convenient alias to {@link Ext.Array#toArray Ext.Array.toArray}
- * @param {Iterable} the iterable object to be turned into a true Array.
+ * @method
* @member Ext
- * @method toArray
- * @return {Array} array
+ * @alias Ext.Array#toArray
*/
Ext.toArray = function() {
return ExtArray.toArray.apply(ExtArray, arguments);
- }
+ };
})();
/**
* A collection of useful static methods to deal with function callbacks
* @singleton
*/
-
Ext.Function = {
/**
* A very commonly used method throughout the framework. It acts as a wrapper around another method
- * which originally accepts 2 arguments for <code>name</code> and <code>value</code>.
+ * which originally accepts 2 arguments for `name` and `value`.
* The wrapped function then allows "flexible" value setting of either:
*
- * <ul>
- * <li><code>name</code> and <code>value</code> as 2 arguments</li>
- * <li>one single object argument with multiple key - value pairs</li>
- * </ul>
+ * - `name` and `value` as 2 arguments
+ * - one single object argument with multiple key - value pairs
*
* For example:
- * <pre><code>
-var setValue = Ext.Function.flexSetter(function(name, value) {
- this[name] = value;
-});
-
-// Afterwards
-// Setting a single name - value
-setValue('name1', 'value1');
-
-// Settings multiple name - value pairs
-setValue({
- name1: 'value1',
- name2: 'value2',
- name3: 'value3'
-});
- * </code></pre>
+ *
+ * var setValue = Ext.Function.flexSetter(function(name, value) {
+ * this[name] = value;
+ * });
+ *
+ * // Afterwards
+ * // Setting a single name - value
+ * setValue('name1', 'value1');
+ *
+ * // Settings multiple name - value pairs
+ * setValue({
+ * name1: 'value1',
+ * name2: 'value2',
+ * name3: 'value3'
+ * });
+ *
* @param {Function} setter
* @returns {Function} flexSetter
*/
};
},
- /**
- * Create a new function from the provided <code>fn</code>, change <code>this</code> to the provided scope, optionally
+ /**
+ * Create a new function from the provided `fn`, change `this` to the provided scope, optionally
* overrides arguments for the call. (Defaults to the arguments passed by the caller)
*
+ * {@link Ext#bind Ext.bind} is alias for {@link Ext.Function#bind Ext.Function.bind}
+ *
* @param {Function} fn The function to delegate.
- * @param {Object} scope (optional) The scope (<code><b>this</b></code> reference) in which the function is executed.
- * <b>If omitted, defaults to the browser window.</b>
+ * @param {Object} scope (optional) The scope (`this` reference) in which the function is executed.
+ * **If omitted, defaults to the browser window.**
* @param {Array} args (optional) Overrides arguments for the call. (Defaults to the arguments passed by the caller)
* @param {Boolean/Number} appendArgs (optional) if True args are appended to call args instead of overriding,
* if a number the args are inserted at the specified position
* @return {Function} The new function
*/
bind: function(fn, scope, args, appendArgs) {
+ if (arguments.length === 2) {
+ return function() {
+ return fn.apply(scope, arguments);
+ }
+ }
+
var method = fn,
- applyArgs;
+ slice = Array.prototype.slice;
return function() {
var callArgs = args || arguments;
if (appendArgs === true) {
- callArgs = Array.prototype.slice.call(arguments, 0);
+ callArgs = slice.call(arguments, 0);
callArgs = callArgs.concat(args);
}
- else if (Ext.isNumber(appendArgs)) {
- callArgs = Array.prototype.slice.call(arguments, 0); // copy arguments first
- applyArgs = [appendArgs, 0].concat(args); // create method call params
- Array.prototype.splice.apply(callArgs, applyArgs); // splice them in
+ else if (typeof appendArgs == 'number') {
+ callArgs = slice.call(arguments, 0); // copy arguments first
+ Ext.Array.insert(callArgs, appendArgs, args);
}
return method.apply(scope || window, callArgs);
},
/**
- * Create a new function from the provided <code>fn</code>, the arguments of which are pre-set to `args`.
+ * Create a new function from the provided `fn`, the arguments of which are pre-set to `args`.
* New arguments passed to the newly created callback when it's invoked are appended after the pre-set ones.
* This is especially useful when creating callbacks.
+ *
* For example:
*
- var originalFunction = function(){
- alert(Ext.Array.from(arguments).join(' '));
- };
-
- var callback = Ext.Function.pass(originalFunction, ['Hello', 'World']);
-
- callback(); // alerts 'Hello World'
- callback('by Me'); // alerts 'Hello World by Me'
-
+ * var originalFunction = function(){
+ * alert(Ext.Array.from(arguments).join(' '));
+ * };
+ *
+ * var callback = Ext.Function.pass(originalFunction, ['Hello', 'World']);
+ *
+ * callback(); // alerts 'Hello World'
+ * callback('by Me'); // alerts 'Hello World by Me'
+ *
+ * {@link Ext#pass Ext.pass} is alias for {@link Ext.Function#pass Ext.Function.pass}
+ *
* @param {Function} fn The original function
* @param {Array} args The arguments to pass to new callback
- * @param {Object} scope (optional) The scope (<code><b>this</b></code> reference) in which the function is executed.
+ * @param {Object} scope (optional) The scope (`this` reference) in which the function is executed.
* @return {Function} The new callback function
*/
pass: function(fn, args, scope) {
},
/**
- * Create an alias to the provided method property with name <code>methodName</code> of <code>object</code>.
- * Note that the execution scope will still be bound to the provided <code>object</code> itself.
+ * Create an alias to the provided method property with name `methodName` of `object`.
+ * Note that the execution scope will still be bound to the provided `object` itself.
*
* @param {Object/Function} object
* @param {String} methodName
* Creates an interceptor function. The passed function is called before the original one. If it returns false,
* the original one is not called. The resulting function returns the results of the original function.
* The passed function is called with the parameters of the original function. Example usage:
- * <pre><code>
-var sayHi = function(name){
- alert('Hi, ' + name);
-}
-
-sayHi('Fred'); // alerts "Hi, Fred"
-
-// create a new function that validates input without
-// directly modifying the original function:
-var sayHiToFriend = Ext.Function.createInterceptor(sayHi, function(name){
- return name == 'Brian';
-});
-
-sayHiToFriend('Fred'); // no alert
-sayHiToFriend('Brian'); // alerts "Hi, Brian"
- </code></pre>
+ *
+ * var sayHi = function(name){
+ * alert('Hi, ' + name);
+ * }
+ *
+ * sayHi('Fred'); // alerts "Hi, Fred"
+ *
+ * // create a new function that validates input without
+ * // directly modifying the original function:
+ * var sayHiToFriend = Ext.Function.createInterceptor(sayHi, function(name){
+ * return name == 'Brian';
+ * });
+ *
+ * sayHiToFriend('Fred'); // no alert
+ * sayHiToFriend('Brian'); // alerts "Hi, Brian"
+ *
* @param {Function} origFn The original function.
* @param {Function} newFn The function to call before the original
- * @param {Object} scope (optional) The scope (<code><b>this</b></code> reference) in which the passed function is executed.
- * <b>If omitted, defaults to the scope in which the original function is called or the browser window.</b>
- * @param {Mixed} returnValue (optional) The value to return if the passed function return false (defaults to null).
+ * @param {Object} scope (optional) The scope (`this` reference) in which the passed function is executed.
+ * **If omitted, defaults to the scope in which the original function is called or the browser window.**
+ * @param {Object} returnValue (optional) The value to return if the passed function return false (defaults to null).
* @return {Function} The new function
*/
createInterceptor: function(origFn, newFn, scope, returnValue) {
},
/**
- * Creates a delegate (callback) which, when called, executes after a specific delay.
- * @param {Function} fn The function which will be called on a delay when the returned function is called.
- * Optionally, a replacement (or additional) argument list may be specified.
- * @param {Number} delay The number of milliseconds to defer execution by whenever called.
- * @param {Object} scope (optional) The scope (<code>this</code> reference) used by the function at execution time.
- * @param {Array} args (optional) Override arguments for the call. (Defaults to the arguments passed by the caller)
- * @param {Boolean/Number} appendArgs (optional) if True args are appended to call args instead of overriding,
- * if a number the args are inserted at the specified position.
- * @return {Function} A function which, when called, executes the original function after the specified delay.
- */
+ * Creates a delegate (callback) which, when called, executes after a specific delay.
+ *
+ * @param {Function} fn The function which will be called on a delay when the returned function is called.
+ * Optionally, a replacement (or additional) argument list may be specified.
+ * @param {Number} delay The number of milliseconds to defer execution by whenever called.
+ * @param {Object} scope (optional) The scope (`this` reference) used by the function at execution time.
+ * @param {Array} args (optional) Override arguments for the call. (Defaults to the arguments passed by the caller)
+ * @param {Boolean/Number} appendArgs (optional) if True args are appended to call args instead of overriding,
+ * if a number the args are inserted at the specified position.
+ * @return {Function} A function which, when called, executes the original function after the specified delay.
+ */
createDelayed: function(fn, delay, scope, args, appendArgs) {
if (scope || args) {
fn = Ext.Function.bind(fn, scope, args, appendArgs);
/**
* Calls this function after the number of millseconds specified, optionally in a specific scope. Example usage:
- * <pre><code>
-var sayHi = function(name){
- alert('Hi, ' + name);
-}
-
-// executes immediately:
-sayHi('Fred');
-
-// executes after 2 seconds:
-Ext.Function.defer(sayHi, 2000, this, ['Fred']);
-
-// this syntax is sometimes useful for deferring
-// execution of an anonymous function:
-Ext.Function.defer(function(){
- alert('Anonymous');
-}, 100);
- </code></pre>
+ *
+ * var sayHi = function(name){
+ * alert('Hi, ' + name);
+ * }
+ *
+ * // executes immediately:
+ * sayHi('Fred');
+ *
+ * // executes after 2 seconds:
+ * Ext.Function.defer(sayHi, 2000, this, ['Fred']);
+ *
+ * // this syntax is sometimes useful for deferring
+ * // execution of an anonymous function:
+ * Ext.Function.defer(function(){
+ * alert('Anonymous');
+ * }, 100);
+ *
+ * {@link Ext#defer Ext.defer} is alias for {@link Ext.Function#defer Ext.Function.defer}
+ *
* @param {Function} fn The function to defer.
- * @param {Number} millis The number of milliseconds for the setTimeout call (if less than or equal to 0 the function is executed immediately)
- * @param {Object} scope (optional) The scope (<code><b>this</b></code> reference) in which the function is executed.
- * <b>If omitted, defaults to the browser window.</b>
+ * @param {Number} millis The number of milliseconds for the setTimeout call
+ * (if less than or equal to 0 the function is executed immediately)
+ * @param {Object} scope (optional) The scope (`this` reference) in which the function is executed.
+ * **If omitted, defaults to the browser window.**
* @param {Array} args (optional) Overrides arguments for the call. (Defaults to the arguments passed by the caller)
* @param {Boolean/Number} appendArgs (optional) if True args are appended to call args instead of overriding,
* if a number the args are inserted at the specified position
* The resulting function returns the results of the original function.
* The passed function is called with the parameters of the original function. Example usage:
*
- * <pre><code>
-var sayHi = function(name){
- alert('Hi, ' + name);
-}
-
-sayHi('Fred'); // alerts "Hi, Fred"
-
-var sayGoodbye = Ext.Function.createSequence(sayHi, function(name){
- alert('Bye, ' + name);
-});
-
-sayGoodbye('Fred'); // both alerts show
- * </code></pre>
+ * var sayHi = function(name){
+ * alert('Hi, ' + name);
+ * }
+ *
+ * sayHi('Fred'); // alerts "Hi, Fred"
+ *
+ * var sayGoodbye = Ext.Function.createSequence(sayHi, function(name){
+ * alert('Bye, ' + name);
+ * });
+ *
+ * sayGoodbye('Fred'); // both alerts show
*
* @param {Function} origFn The original function.
* @param {Function} newFn The function to sequence
- * @param {Object} scope (optional) The scope (this reference) in which the passed function is executed.
+ * @param {Object} scope (optional) The scope (`this` reference) in which the passed function is executed.
* If omitted, defaults to the scope in which the original function is called or the browser window.
* @return {Function} The new function
*/
},
/**
- * <p>Creates a delegate function, optionally with a bound scope which, when called, buffers
+ * Creates a delegate function, optionally with a bound scope which, when called, buffers
* the execution of the passed function for the configured number of milliseconds.
* If called again within that period, the impending invocation will be canceled, and the
- * timeout period will begin again.</p>
+ * timeout period will begin again.
*
* @param {Function} fn The function to invoke on a buffered timer.
* @param {Number} buffer The number of milliseconds by which to buffer the invocation of the
* function.
- * @param {Object} scope (optional) The scope (<code><b>this</b></code> reference) in which
+ * @param {Object} scope (optional) The scope (`this` reference) in which
* the passed function is executed. If omitted, defaults to the scope specified by the caller.
* @param {Array} args (optional) Override arguments for the call. Defaults to the arguments
* passed by the caller.
return function() {
var me = this;
if (timerId) {
- clearInterval(timerId);
+ clearTimeout(timerId);
timerId = null;
}
timerId = setTimeout(function(){
},
/**
- * <p>Creates a throttled version of the passed function which, when called repeatedly and
+ * Creates a throttled version of the passed function which, when called repeatedly and
* rapidly, invokes the passed function only after a certain interval has elapsed since the
- * previous invocation.</p>
+ * previous invocation.
*
- * <p>This is useful for wrapping functions which may be called repeatedly, such as
- * a handler of a mouse move event when the processing is expensive.</p>
+ * This is useful for wrapping functions which may be called repeatedly, such as
+ * a handler of a mouse move event when the processing is expensive.
*
- * @param fn {Function} The function to execute at a regular time interval.
- * @param interval {Number} The interval <b>in milliseconds</b> on which the passed function is executed.
- * @param scope (optional) The scope (<code><b>this</b></code> reference) in which
+ * @param {Function} fn The function to execute at a regular time interval.
+ * @param {Number} interval The interval **in milliseconds** on which the passed function is executed.
+ * @param {Object} scope (optional) The scope (`this` reference) in which
* the passed function is executed. If omitted, defaults to the scope specified by the caller.
* @returns {Function} A function which invokes the passed function at the specified interval.
*/
timer = setTimeout(execute, interval - elapsed);
}
};
+ },
+
+ /**
+ * Adds behavior to an existing method that is executed before the
+ * original behavior of the function. For example:
+ *
+ * var soup = {
+ * contents: [],
+ * add: function(ingredient) {
+ * this.contents.push(ingredient);
+ * }
+ * };
+ * Ext.Function.interceptBefore(soup, "add", function(ingredient){
+ * if (!this.contents.length && ingredient !== "water") {
+ * // Always add water to start with
+ * this.contents.push("water");
+ * }
+ * });
+ * soup.add("onions");
+ * soup.add("salt");
+ * soup.contents; // will contain: water, onions, salt
+ *
+ * @param {Object} object The target object
+ * @param {String} methodName Name of the method to override
+ * @param {Function} fn Function with the new behavior. It will
+ * be called with the same arguments as the original method. The
+ * return value of this function will be the return value of the
+ * new method.
+ * @return {Function} The new function just created.
+ */
+ interceptBefore: function(object, methodName, fn) {
+ var method = object[methodName] || Ext.emptyFn;
+
+ return object[methodName] = function() {
+ var ret = fn.apply(this, arguments);
+ method.apply(this, arguments);
+
+ return ret;
+ };
+ },
+
+ /**
+ * Adds behavior to an existing method that is executed after the
+ * original behavior of the function. For example:
+ *
+ * var soup = {
+ * contents: [],
+ * add: function(ingredient) {
+ * this.contents.push(ingredient);
+ * }
+ * };
+ * Ext.Function.interceptAfter(soup, "add", function(ingredient){
+ * // Always add a bit of extra salt
+ * this.contents.push("salt");
+ * });
+ * soup.add("water");
+ * soup.add("onions");
+ * soup.contents; // will contain: water, salt, onions, salt
+ *
+ * @param {Object} object The target object
+ * @param {String} methodName Name of the method to override
+ * @param {Function} fn Function with the new behavior. It will
+ * be called with the same arguments as the original method. The
+ * return value of this function will be the return value of the
+ * new method.
+ * @return {Function} The new function just created.
+ */
+ interceptAfter: function(object, methodName, fn) {
+ var method = object[methodName] || Ext.emptyFn;
+
+ return object[methodName] = function() {
+ method.apply(this, arguments);
+ return fn.apply(this, arguments);
+ };
}
};
/**
- * Shorthand for {@link Ext.Function#defer}
+ * @method
* @member Ext
- * @method defer
+ * @alias Ext.Function#defer
*/
Ext.defer = Ext.Function.alias(Ext.Function, 'defer');
/**
- * Shorthand for {@link Ext.Function#pass}
+ * @method
* @member Ext
- * @method pass
+ * @alias Ext.Function#pass
*/
Ext.pass = Ext.Function.alias(Ext.Function, 'pass');
/**
- * Shorthand for {@link Ext.Function#bind}
+ * @method
* @member Ext
- * @method bind
+ * @alias Ext.Function#bind
*/
Ext.bind = Ext.Function.alias(Ext.Function, 'bind');
* @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']]
- }
-
- * @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
- * @return {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']]
+ * }
+ *
+ * @param {String} queryString The query string to decode
+ * @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) {
var parts = queryString.replace(/^\?/, '').split('&'),
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) {
/**
* 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) {
var keys = [],
/**
* 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);
/**
* Returns the current timestamp
* @return {Date} The current timestamp
+ * @method
*/
now: Date.now || function() {
return +new Date();
* default behaviour of javascript Date objects.
* (see {@link #parse} for more information)
* Defaults to <tt>false</tt>.
- * @static
* @type Boolean
*/
useStrict: false,
* <p>To enable Dates to also be <i>formatted</i> according to that format, a corresponding
* formatting function must be placed into the {@link #formatFunctions} property.
* @property parseFunctions
- * @static
* @type Object
*/
parseFunctions: {
* <p>To enable date strings to also be <i>parsed</i> according to that format, a corresponding
* parsing function must be placed into the {@link #parseFunctions} property.
* @property formatFunctions
- * @static
* @type Object
*/
formatFunctions: {
/**
* Date interval constant
- * @static
* @type String
*/
MILLI : "ms",
/**
* Date interval constant
- * @static
* @type String
*/
SECOND : "s",
/**
* Date interval constant
- * @static
* @type String
*/
MINUTE : "mi",
/** Date interval constant
- * @static
* @type String
*/
HOUR : "h",
/**
* Date interval constant
- * @static
* @type String
*/
DAY : "d",
/**
* Date interval constant
- * @static
* @type String
*/
MONTH : "mo",
/**
* Date interval constant
- * @static
* @type String
*/
YEAR : "y",
Ext.Date.parse('2009-02', 'Y-m'); // returns a Date object representing February 1st 2009
</code></pre>
* @property defaults
- * @static
* @type Object
*/
defaults: {},
/**
+ * @property {String[]} dayNames
* An array of textual day names.
* Override these values for international dates.
* Example:
...
];
</code></pre>
- * @type Array
- * @static
*/
dayNames : [
"Sunday",
],
/**
+ * @property {String[]} monthNames
* An array of textual month names.
* Override these values for international dates.
* Example:
...
];
</code></pre>
- * @type Array
- * @static
*/
monthNames : [
"January",
],
/**
+ * @property {Object} monthNumbers
* An object hash of zero-based javascript month numbers (with short month names as keys. note: keys are case-sensitive).
* Override these values for international dates.
* Example:
...
};
</code></pre>
- * @type Object
- * @static
*/
monthNumbers : {
Jan:0,
Dec:11
},
/**
- * <p>The date format string that the {@link #dateRenderer} and {@link #date} functions use.
- * see {@link #Date} for details.</p>
- * <p>This defaults to <code>m/d/Y</code>, but may be overridden in a locale file.</p>
- * @property defaultFormat
- * @static
- * @type String
+ * @property {String} defaultFormat
+ * <p>The date format string that the {@link Ext.util.Format#dateRenderer}
+ * and {@link Ext.util.Format#date} functions use. See {@link Ext.Date} for details.</p>
+ * <p>This may be overridden in a locale file.</p>
*/
defaultFormat : "m/d/Y",
/**
* Override this function for international dates.
* @param {Number} month A zero-based javascript month number.
* @return {String} The short month name.
- * @static
*/
getShortMonthName : function(month) {
return utilDate.monthNames[month].substring(0, 3);
* Override this function for international dates.
* @param {Number} day A zero-based javascript day number.
* @return {String} The short day name.
- * @static
*/
getShortDayName : function(day) {
return utilDate.dayNames[day].substring(0, 3);
* Override this function for international dates.
* @param {String} name The short/full month name.
* @return {Number} The zero-based javascript month number.
- * @static
*/
getMonthNumber : function(name) {
// handle camel casing for english month names (since the keys for the Ext.Date.monthNumbers hash are case sensitive)
* Checks if the specified format contains hour information
* @param {String} format The format to check
* @return {Boolean} True if the format contains hour information
- * @static
+ * @method
*/
formatContainsHourInfo : (function(){
var stripEscapeRe = /(\\.)/g,
* @param {String} format The format to check
* @return {Boolean} True if the format contains information about
* date/day information.
- * @static
+ * @method
*/
formatContainsDateInfo : (function(){
var stripEscapeRe = /(\\.)/g,
console.log(Ext.Date.format(new Date(), 'X'); // returns the current day of the month
</code></pre>
* @type Object
- * @static
*/
formatCodes : {
d: "Ext.String.leftPad(this.getDate(), 2, '0')",
* @param {Number} second (optional) Second
* @param {Number} millisecond (optional) Millisecond
* @return {Boolean} true if the passed parameters do not cause a Date "rollover", false otherwise.
- * @static
*/
isValid : function(y, m, d, h, i, s, ms) {
// setup defaults
* @param {Boolean} strict (optional) True to validate date strings while parsing (i.e. prevents javascript Date "rollover")
(defaults to false). Invalid date strings will return null when parsed.
* @return {Date} The parsed Date.
- * @static
*/
parse : function(input, format, strict) {
var p = utilDate.parseFunctions;
+ "y = ty > Ext.Date.y2kYear ? 1900 + ty : 2000 + ty;\n", // 2-digit year
s:"(\\d{1,2})"
},
- /**
+ /*
* In the am/pm parsing routines, we allow both upper and lower case
* even though it doesn't exactly match the spec. It gives much more flexibility
* in being able to specify case insensitive regexes.
* (equivalent to the format specifier 'W', but without a leading zero).
* @param {Date} date The date
* @return {Number} 1 to 53
+ * @method
*/
getWeekOfYear : (function() {
// adapted from http://www.merlyn.demon.co.uk/weekcalc.htm
* Get the number of days in the current month, adjusted for leap year.
* @param {Date} date The date
* @return {Number} The number of days in the month.
+ * @method
*/
getDaysInMonth: (function() {
var daysInMonth = [31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
* @docauthor Jacky Nguyen <jacky@sencha.com>
* @class Ext.Base
*
- * The root of all classes created with {@link Ext#define}
- * All prototype and static members of this class are inherited by any other class
+ * The root of all classes created with {@link Ext#define}.
*
+ * Ext.Base is the building block of all Ext classes. All classes in Ext inherit from Ext.Base.
+ * All prototype and static members of this class are inherited by all other classes.
*/
(function(flexSetter) {
* Get the reference to the current class from which this object was instantiated. Unlike {@link Ext.Base#statics},
* `this.self` is scope-dependent and it's meant to be used for dynamic inheritance. See {@link Ext.Base#statics}
* for a detailed comparison
-
- Ext.define('My.Cat', {
- statics: {
- speciesName: 'Cat' // My.Cat.speciesName = 'Cat'
- },
-
- constructor: function() {
- alert(this.self.speciesName); / dependent on 'this'
-
- return this;
- },
-
- clone: function() {
- return new this.self();
- }
- });
-
-
- Ext.define('My.SnowLeopard', {
- extend: 'My.Cat',
- statics: {
- speciesName: 'Snow Leopard' // My.SnowLeopard.speciesName = 'Snow Leopard'
- }
- });
-
- var cat = new My.Cat(); // alerts 'Cat'
- var snowLeopard = new My.SnowLeopard(); // alerts 'Snow Leopard'
-
- var clone = snowLeopard.clone();
- alert(Ext.getClassName(clone)); // alerts 'My.SnowLeopard'
-
- * @type Class
+ *
+ * Ext.define('My.Cat', {
+ * statics: {
+ * speciesName: 'Cat' // My.Cat.speciesName = 'Cat'
+ * },
+ *
+ * constructor: function() {
+ * alert(this.self.speciesName); / dependent on 'this'
+ *
+ * return this;
+ * },
+ *
+ * clone: function() {
+ * return new this.self();
+ * }
+ * });
+ *
+ *
+ * Ext.define('My.SnowLeopard', {
+ * extend: 'My.Cat',
+ * statics: {
+ * speciesName: 'Snow Leopard' // My.SnowLeopard.speciesName = 'Snow Leopard'
+ * }
+ * });
+ *
+ * var cat = new My.Cat(); // alerts 'Cat'
+ * var snowLeopard = new My.SnowLeopard(); // alerts 'Snow Leopard'
+ *
+ * var clone = snowLeopard.clone();
+ * alert(Ext.getClassName(clone)); // alerts 'My.SnowLeopard'
+ *
+ * @type Ext.Class
* @protected
- * @markdown
*/
self: Base,
- /**
- * Default constructor, simply returns `this`
- *
- * @constructor
- * @protected
- * @return {Object} this
- */
+ // Default constructor, simply returns `this`
constructor: function() {
return this;
},
+ //<feature classSystem.config>
/**
* Initialize configuration for this class. a typical example:
-
- Ext.define('My.awesome.Class', {
- // The default config
- config: {
- name: 'Awesome',
- isAwesome: true
- },
-
- constructor: function(config) {
- this.initConfig(config);
-
- return this;
- }
- });
-
- var awesome = new My.awesome.Class({
- name: 'Super Awesome'
- });
-
- alert(awesome.getName()); // 'Super Awesome'
-
+ *
+ * Ext.define('My.awesome.Class', {
+ * // The default config
+ * config: {
+ * name: 'Awesome',
+ * isAwesome: true
+ * },
+ *
+ * constructor: function(config) {
+ * this.initConfig(config);
+ *
+ * return this;
+ * }
+ * });
+ *
+ * var awesome = new My.awesome.Class({
+ * name: 'Super Awesome'
+ * });
+ *
+ * alert(awesome.getName()); // 'Super Awesome'
+ *
* @protected
* @param {Object} config
* @return {Object} mixins The mixin prototypes as key - value pairs
- * @markdown
*/
initConfig: function(config) {
if (!this.$configInited) {
return this;
}),
+ //</feature>
/**
* Call the parent's overridden method. For example:
-
- Ext.define('My.own.A', {
- constructor: function(test) {
- alert(test);
- }
- });
-
- Ext.define('My.own.B', {
- extend: 'My.own.A',
-
- constructor: function(test) {
- alert(test);
-
- this.callParent([test + 1]);
- }
- });
-
- Ext.define('My.own.C', {
- extend: 'My.own.B',
-
- constructor: function() {
- alert("Going to call parent's overriden constructor...");
-
- this.callParent(arguments);
- }
- });
-
- var a = new My.own.A(1); // alerts '1'
- var b = new My.own.B(1); // alerts '1', then alerts '2'
- var c = new My.own.C(2); // alerts "Going to call parent's overriden constructor..."
- // alerts '2', then alerts '3'
-
+ *
+ * Ext.define('My.own.A', {
+ * constructor: function(test) {
+ * alert(test);
+ * }
+ * });
+ *
+ * Ext.define('My.own.B', {
+ * extend: 'My.own.A',
+ *
+ * constructor: function(test) {
+ * alert(test);
+ *
+ * this.callParent([test + 1]);
+ * }
+ * });
+ *
+ * Ext.define('My.own.C', {
+ * extend: 'My.own.B',
+ *
+ * constructor: function() {
+ * alert("Going to call parent's overriden constructor...");
+ *
+ * this.callParent(arguments);
+ * }
+ * });
+ *
+ * var a = new My.own.A(1); // alerts '1'
+ * var b = new My.own.B(1); // alerts '1', then alerts '2'
+ * var c = new My.own.C(2); // alerts "Going to call parent's overriden constructor..."
+ * // alerts '2', then alerts '3'
+ *
* @protected
* @param {Array/Arguments} args The arguments, either an array or the `arguments` object
* from the current method, for example: `this.callParent(arguments)`
- * @return {Mixed} Returns the result from the superclass' method
- * @markdown
+ * @return {Object} Returns the result from the superclass' method
*/
callParent: function(args) {
var method = this.callParent.caller,
* Get the reference to the class from which this object was instantiated. Note that unlike {@link Ext.Base#self},
* `this.statics()` is scope-independent and it always returns the class from which it was called, regardless of what
* `this` points to during run-time
-
- Ext.define('My.Cat', {
- statics: {
- totalCreated: 0,
- speciesName: 'Cat' // My.Cat.speciesName = 'Cat'
- },
-
- constructor: function() {
- var statics = this.statics();
-
- alert(statics.speciesName); // always equals to 'Cat' no matter what 'this' refers to
- // equivalent to: My.Cat.speciesName
-
- alert(this.self.speciesName); // dependent on 'this'
-
- statics.totalCreated++;
-
- return this;
- },
-
- clone: function() {
- var cloned = new this.self; // dependent on 'this'
-
- cloned.groupName = this.statics().speciesName; // equivalent to: My.Cat.speciesName
-
- return cloned;
- }
- });
-
-
- Ext.define('My.SnowLeopard', {
- extend: 'My.Cat',
-
- statics: {
- speciesName: 'Snow Leopard' // My.SnowLeopard.speciesName = 'Snow Leopard'
- },
-
- constructor: function() {
- this.callParent();
- }
- });
-
- var cat = new My.Cat(); // alerts 'Cat', then alerts 'Cat'
-
- var snowLeopard = new My.SnowLeopard(); // alerts 'Cat', then alerts 'Snow Leopard'
-
- var clone = snowLeopard.clone();
- alert(Ext.getClassName(clone)); // alerts 'My.SnowLeopard'
- alert(clone.groupName); // alerts 'Cat'
-
- alert(My.Cat.totalCreated); // alerts 3
-
+ *
+ * Ext.define('My.Cat', {
+ * statics: {
+ * totalCreated: 0,
+ * speciesName: 'Cat' // My.Cat.speciesName = 'Cat'
+ * },
+ *
+ * constructor: function() {
+ * var statics = this.statics();
+ *
+ * alert(statics.speciesName); // always equals to 'Cat' no matter what 'this' refers to
+ * // equivalent to: My.Cat.speciesName
+ *
+ * alert(this.self.speciesName); // dependent on 'this'
+ *
+ * statics.totalCreated++;
+ *
+ * return this;
+ * },
+ *
+ * clone: function() {
+ * var cloned = new this.self; // dependent on 'this'
+ *
+ * cloned.groupName = this.statics().speciesName; // equivalent to: My.Cat.speciesName
+ *
+ * return cloned;
+ * }
+ * });
+ *
+ *
+ * Ext.define('My.SnowLeopard', {
+ * extend: 'My.Cat',
+ *
+ * statics: {
+ * speciesName: 'Snow Leopard' // My.SnowLeopard.speciesName = 'Snow Leopard'
+ * },
+ *
+ * constructor: function() {
+ * this.callParent();
+ * }
+ * });
+ *
+ * var cat = new My.Cat(); // alerts 'Cat', then alerts 'Cat'
+ *
+ * var snowLeopard = new My.SnowLeopard(); // alerts 'Cat', then alerts 'Snow Leopard'
+ *
+ * var clone = snowLeopard.clone();
+ * alert(Ext.getClassName(clone)); // alerts 'My.SnowLeopard'
+ * alert(clone.groupName); // alerts 'Cat'
+ *
+ * alert(My.Cat.totalCreated); // alerts 3
+ *
* @protected
- * @return {Class}
- * @markdown
+ * @return {Ext.Class}
*/
statics: function() {
var method = this.statics.caller,
/**
* Call the original method that was previously overridden with {@link Ext.Base#override}
-
- Ext.define('My.Cat', {
- constructor: function() {
- alert("I'm a cat!");
-
- return this;
- }
- });
-
- My.Cat.override({
- constructor: function() {
- alert("I'm going to be a cat!");
-
- var instance = this.callOverridden();
-
- alert("Meeeeoooowwww");
-
- return instance;
- }
- });
-
- var kitty = new My.Cat(); // alerts "I'm going to be a cat!"
- // alerts "I'm a cat!"
- // alerts "Meeeeoooowwww"
-
+ *
+ * Ext.define('My.Cat', {
+ * constructor: function() {
+ * alert("I'm a cat!");
+ *
+ * return this;
+ * }
+ * });
+ *
+ * My.Cat.override({
+ * constructor: function() {
+ * alert("I'm going to be a cat!");
+ *
+ * var instance = this.callOverridden();
+ *
+ * alert("Meeeeoooowwww");
+ *
+ * return instance;
+ * }
+ * });
+ *
+ * var kitty = new My.Cat(); // alerts "I'm going to be a cat!"
+ * // alerts "I'm a cat!"
+ * // alerts "Meeeeoooowwww"
+ *
* @param {Array/Arguments} args The arguments, either an array or the `arguments` object
- * @return {Mixed} Returns the result after calling the overridden method
- * @markdown
+ * @return {Object} Returns the result after calling the overridden method
+ * @protected
*/
callOverridden: function(args) {
var method = this.callOverridden.caller;
Ext.apply(Ext.Base, {
/**
* Create a new instance of this Class.
-Ext.define('My.cool.Class', {
- ...
-});
-
-My.cool.Class.create({
- someConfig: true
-});
- * @property create
+ *
+ * Ext.define('My.cool.Class', {
+ * ...
+ * });
+ *
+ * My.cool.Class.create({
+ * someConfig: true
+ * });
+ *
+ * All parameters are passed to the constructor of the class.
+ *
+ * @return {Object} the created instance.
* @static
- * @type Function
- * @markdown
+ * @inheritable
*/
create: function() {
return Ext.create.apply(Ext, [this].concat(Array.prototype.slice.call(arguments, 0)));
/**
* @private
+ * @inheritable
*/
- own: flexSetter(function(name, value) {
- if (typeof value === 'function') {
+ own: function(name, value) {
+ if (typeof value == 'function') {
this.ownMethod(name, value);
}
else {
this.prototype[name] = value;
}
- }),
+ },
/**
* @private
+ * @inheritable
*/
ownMethod: function(name, fn) {
var originalFn;
- if (fn.$owner !== undefined && fn !== Ext.emptyFn) {
+ if (typeof fn.$owner !== 'undefined' && fn !== Ext.emptyFn) {
originalFn = fn;
fn = function() {
/**
* Add / override static properties of this class.
-
- Ext.define('My.cool.Class', {
- ...
- });
-
- My.cool.Class.addStatics({
- someProperty: 'someValue', // My.cool.Class.someProperty = 'someValue'
- method1: function() { ... }, // My.cool.Class.method1 = function() { ... };
- method2: function() { ... } // My.cool.Class.method2 = function() { ... };
- });
-
- * @property addStatics
- * @static
- * @type Function
+ *
+ * Ext.define('My.cool.Class', {
+ * ...
+ * });
+ *
+ * My.cool.Class.addStatics({
+ * someProperty: 'someValue', // My.cool.Class.someProperty = 'someValue'
+ * method1: function() { ... }, // My.cool.Class.method1 = function() { ... };
+ * method2: function() { ... } // My.cool.Class.method2 = function() { ... };
+ * });
+ *
* @param {Object} members
- * @markdown
+ * @return {Ext.Base} this
+ * @static
+ * @inheritable
*/
addStatics: function(members) {
for (var name in members) {
},
/**
- * Add methods / properties to the prototype of this class.
-
- Ext.define('My.awesome.Cat', {
- constructor: function() {
- ...
- }
- });
+ * @private
+ * @param {Object} members
+ */
+ addInheritableStatics: function(members) {
+ var inheritableStatics,
+ hasInheritableStatics,
+ prototype = this.prototype,
+ name, member;
- My.awesome.Cat.implement({
- meow: function() {
- alert('Meowww...');
- }
- });
+ inheritableStatics = prototype.$inheritableStatics;
+ hasInheritableStatics = prototype.$hasInheritableStatics;
- var kitty = new My.awesome.Cat;
- kitty.meow();
+ if (!inheritableStatics) {
+ inheritableStatics = prototype.$inheritableStatics = [];
+ hasInheritableStatics = prototype.$hasInheritableStatics = {};
+ }
- * @property implement
- * @static
- * @type Function
- * @param {Object} members
- * @markdown
- */
- implement: function(members) {
- var prototype = this.prototype,
- name, i, member, previous;
//<debug>
var className = Ext.getClassName(this);
//</debug>
+
for (name in members) {
if (members.hasOwnProperty(name)) {
member = members[name];
+ //<debug>
+ if (typeof member == 'function') {
+ member.displayName = className + '.' + name;
+ }
+ //</debug>
+ this[name] = member;
- if (typeof member === 'function') {
- member.$owner = this;
- member.$name = name;
- //<debug>
- if (className) {
- member.displayName = className + '#' + name;
+ if (!hasInheritableStatics[name]) {
+ hasInheritableStatics[name] = true;
+ inheritableStatics.push(name);
+ }
+ }
+ }
+
+ return this;
+ },
+
+ /**
+ * Add methods / properties to the prototype of this class.
+ *
+ * Ext.define('My.awesome.Cat', {
+ * constructor: function() {
+ * ...
+ * }
+ * });
+ *
+ * My.awesome.Cat.implement({
+ * meow: function() {
+ * alert('Meowww...');
+ * }
+ * });
+ *
+ * var kitty = new My.awesome.Cat;
+ * kitty.meow();
+ *
+ * @param {Object} members
+ * @static
+ * @inheritable
+ */
+ implement: function(members) {
+ var prototype = this.prototype,
+ enumerables = Ext.enumerables,
+ name, i, member;
+ //<debug>
+ var className = Ext.getClassName(this);
+ //</debug>
+ for (name in members) {
+ if (members.hasOwnProperty(name)) {
+ member = members[name];
+
+ if (typeof member === 'function') {
+ member.$owner = this;
+ member.$name = name;
+ //<debug>
+ if (className) {
+ member.displayName = className + '#' + name;
}
//</debug>
}
}
}
- if (Ext.enumerables) {
- var enumerables = Ext.enumerables;
-
+ if (enumerables) {
for (i = enumerables.length; i--;) {
name = enumerables[i];
/**
* Borrow another class' members to the prototype of this class.
-
-Ext.define('Bank', {
- money: '$$$',
- printMoney: function() {
- alert('$$$$$$$');
- }
-});
-
-Ext.define('Thief', {
- ...
-});
-
-Thief.borrow(Bank, ['money', 'printMoney']);
-
-var steve = new Thief();
-
-alert(steve.money); // alerts '$$$'
-steve.printMoney(); // alerts '$$$$$$$'
-
- * @property borrow
- * @static
- * @type Function
+ *
+ * Ext.define('Bank', {
+ * money: '$$$',
+ * printMoney: function() {
+ * alert('$$$$$$$');
+ * }
+ * });
+ *
+ * Ext.define('Thief', {
+ * ...
+ * });
+ *
+ * Thief.borrow(Bank, ['money', 'printMoney']);
+ *
+ * var steve = new Thief();
+ *
+ * alert(steve.money); // alerts '$$$'
+ * steve.printMoney(); // alerts '$$$$$$$'
+ *
* @param {Ext.Base} fromClass The class to borrow members from
- * @param {Array/String} members The names of the members to borrow
+ * @param {String/String[]} members The names of the members to borrow
* @return {Ext.Base} this
- * @markdown
+ * @static
+ * @inheritable
*/
borrow: function(fromClass, members) {
var fromPrototype = fromClass.prototype,
/**
* Override prototype members of this class. Overridden methods can be invoked via
* {@link Ext.Base#callOverridden}
-
- Ext.define('My.Cat', {
- constructor: function() {
- alert("I'm a cat!");
-
- return this;
- }
- });
-
- My.Cat.override({
- constructor: function() {
- alert("I'm going to be a cat!");
-
- var instance = this.callOverridden();
-
- alert("Meeeeoooowwww");
-
- return instance;
- }
- });
-
- var kitty = new My.Cat(); // alerts "I'm going to be a cat!"
- // alerts "I'm a cat!"
- // alerts "Meeeeoooowwww"
-
- * @property override
- * @static
- * @type Function
+ *
+ * Ext.define('My.Cat', {
+ * constructor: function() {
+ * alert("I'm a cat!");
+ *
+ * return this;
+ * }
+ * });
+ *
+ * My.Cat.override({
+ * constructor: function() {
+ * alert("I'm going to be a cat!");
+ *
+ * var instance = this.callOverridden();
+ *
+ * alert("Meeeeoooowwww");
+ *
+ * return instance;
+ * }
+ * });
+ *
+ * var kitty = new My.Cat(); // alerts "I'm going to be a cat!"
+ * // alerts "I'm a cat!"
+ * // alerts "Meeeeoooowwww"
+ *
* @param {Object} members
* @return {Ext.Base} this
- * @markdown
+ * @static
+ * @inheritable
*/
override: function(members) {
var prototype = this.prototype,
+ enumerables = Ext.enumerables,
name, i, member, previous;
+ if (arguments.length === 2) {
+ name = members;
+ member = arguments[1];
+
+ if (typeof member == 'function') {
+ if (typeof prototype[name] == 'function') {
+ previous = prototype[name];
+ member.$previous = previous;
+ }
+
+ this.ownMethod(name, member);
+ }
+ else {
+ prototype[name] = member;
+ }
+
+ return this;
+ }
+
for (name in members) {
if (members.hasOwnProperty(name)) {
member = members[name];
}
}
- if (Ext.enumerables) {
- var enumerables = Ext.enumerables;
-
+ if (enumerables) {
for (i = enumerables.length; i--;) {
name = enumerables[i];
if (members.hasOwnProperty(name)) {
- if (prototype[name] !== undefined) {
+ if (typeof prototype[name] !== 'undefined') {
previous = prototype[name];
members[name].$previous = previous;
}
return this;
},
+ //<feature classSystem.mixins>
/**
* Used internally by the mixins pre-processor
* @private
+ * @inheritable
*/
- mixin: flexSetter(function(name, cls) {
+ mixin: function(name, cls) {
var mixin = cls.prototype,
my = this.prototype,
- i, fn;
+ key, fn;
- for (i in mixin) {
- if (mixin.hasOwnProperty(i)) {
- if (my[i] === undefined) {
- if (typeof mixin[i] === 'function') {
- fn = mixin[i];
+ for (key in mixin) {
+ if (mixin.hasOwnProperty(key)) {
+ if (typeof my[key] === 'undefined' && key !== 'mixins' && key !== 'mixinId') {
+ if (typeof mixin[key] === 'function') {
+ fn = mixin[key];
- if (fn.$owner === undefined) {
- this.ownMethod(i, fn);
+ if (typeof fn.$owner === 'undefined') {
+ this.ownMethod(key, fn);
}
else {
- my[i] = fn;
+ my[key] = fn;
}
}
else {
- my[i] = mixin[i];
+ my[key] = mixin[key];
}
}
- else if (i === 'config' && my.config && mixin.config) {
+ //<feature classSystem.config>
+ else if (key === 'config' && my.config && mixin.config) {
Ext.Object.merge(my.config, mixin.config);
}
+ //</feature>
}
}
- if (my.mixins === undefined) {
- my.mixins = {};
+ if (typeof mixin.onClassMixedIn !== 'undefined') {
+ mixin.onClassMixedIn.call(cls, this);
+ }
+
+ if (!my.hasOwnProperty('mixins')) {
+ if ('mixins' in my) {
+ my.mixins = Ext.Object.merge({}, my.mixins);
+ }
+ else {
+ my.mixins = {};
+ }
}
my.mixins[name] = mixin;
- }),
+ },
+ //</feature>
/**
* Get the current class' name in string format.
-
- Ext.define('My.cool.Class', {
- constructor: function() {
- alert(this.self.getName()); // alerts 'My.cool.Class'
- }
- });
-
- My.cool.Class.getName(); // 'My.cool.Class'
-
+ *
+ * Ext.define('My.cool.Class', {
+ * constructor: function() {
+ * alert(this.self.getName()); // alerts 'My.cool.Class'
+ * }
+ * });
+ *
+ * My.cool.Class.getName(); // 'My.cool.Class'
+ *
* @return {String} className
- * @markdown
+ * @static
+ * @inheritable
*/
getName: function() {
return Ext.getClassName(this);
/**
* Create aliases for existing prototype methods. Example:
-
- Ext.define('My.cool.Class', {
- method1: function() { ... },
- method2: function() { ... }
- });
-
- var test = new My.cool.Class();
-
- My.cool.Class.createAlias({
- method3: 'method1',
- method4: 'method2'
- });
-
- test.method3(); // test.method1()
-
- My.cool.Class.createAlias('method5', 'method3');
-
- test.method5(); // test.method3() -> test.method1()
-
- * @property createAlias
- * @static
- * @type Function
+ *
+ * Ext.define('My.cool.Class', {
+ * method1: function() { ... },
+ * method2: function() { ... }
+ * });
+ *
+ * var test = new My.cool.Class();
+ *
+ * My.cool.Class.createAlias({
+ * method3: 'method1',
+ * method4: 'method2'
+ * });
+ *
+ * test.method3(); // test.method1()
+ *
+ * My.cool.Class.createAlias('method5', 'method3');
+ *
+ * test.method5(); // test.method3() -> test.method1()
+ *
* @param {String/Object} alias The new method name, or an object to set multiple aliases. See
* {@link Ext.Function#flexSetter flexSetter}
* @param {String/Object} origin The original method name
- * @markdown
+ * @static
+ * @inheritable
+ * @method
*/
createAlias: flexSetter(function(alias, origin) {
- this.prototype[alias] = this.prototype[origin];
+ this.prototype[alias] = function() {
+ return this[origin].apply(this, arguments);
+ }
})
});
* @author Jacky Nguyen <jacky@sencha.com>
* @docauthor Jacky Nguyen <jacky@sencha.com>
* @class Ext.Class
- *
- * Handles class creation throughout the whole framework. Note that most of the time {@link Ext#define Ext.define} should
- * be used instead, since it's a higher level wrapper that aliases to {@link Ext.ClassManager#create}
- * to enable namespacing and dynamic dependency resolution.
- *
- * # Basic syntax: #
- *
- * Ext.define(className, properties);
- *
- * in which `properties` is an object represent a collection of properties that apply to the class. See
- * {@link Ext.ClassManager#create} for more detailed instructions.
- *
- * Ext.define('Person', {
- * name: 'Unknown',
- *
- * constructor: function(name) {
- * if (name) {
- * this.name = name;
- * }
- *
- * return this;
- * },
- *
- * eat: function(foodType) {
- * alert("I'm eating: " + foodType);
- *
- * return this;
- * }
- * });
- *
- * var aaron = new Person("Aaron");
- * aaron.eat("Sandwich"); // alert("I'm eating: Sandwich");
- *
- * Ext.Class has a powerful set of extensible {@link Ext.Class#registerPreprocessor pre-processors} which takes care of
- * everything related to class creation, including but not limited to inheritance, mixins, configuration, statics, etc.
- *
- * # Inheritance: #
- *
- * Ext.define('Developer', {
- * extend: 'Person',
- *
- * constructor: function(name, isGeek) {
- * this.isGeek = isGeek;
- *
- * // Apply a method from the parent class' prototype
- * this.callParent([name]);
- *
- * return this;
- *
- * },
- *
- * code: function(language) {
- * alert("I'm coding in: " + language);
- *
- * this.eat("Bugs");
- *
- * return this;
- * }
- * });
- *
- * var jacky = new Developer("Jacky", true);
- * jacky.code("JavaScript"); // alert("I'm coding in: JavaScript");
- * // alert("I'm eating: Bugs");
- *
- * See {@link Ext.Base#callParent} for more details on calling superclass' methods
- *
- * # Mixins: #
- *
- * Ext.define('CanPlayGuitar', {
- * playGuitar: function() {
- * alert("F#...G...D...A");
- * }
- * });
- *
- * Ext.define('CanComposeSongs', {
- * composeSongs: function() { ... }
- * });
- *
- * Ext.define('CanSing', {
- * sing: function() {
- * alert("I'm on the highway to hell...")
- * }
- * });
- *
- * Ext.define('Musician', {
- * extend: 'Person',
- *
- * mixins: {
- * canPlayGuitar: 'CanPlayGuitar',
- * canComposeSongs: 'CanComposeSongs',
- * canSing: 'CanSing'
- * }
- * })
- *
- * Ext.define('CoolPerson', {
- * extend: 'Person',
- *
- * mixins: {
- * canPlayGuitar: 'CanPlayGuitar',
- * canSing: 'CanSing'
- * },
- *
- * sing: function() {
- * alert("Ahem....");
- *
- * this.mixins.canSing.sing.call(this);
- *
- * alert("[Playing guitar at the same time...]");
- *
- * this.playGuitar();
- * }
- * });
- *
- * var me = new CoolPerson("Jacky");
- *
- * me.sing(); // alert("Ahem...");
- * // alert("I'm on the highway to hell...");
- * // alert("[Playing guitar at the same time...]");
- * // alert("F#...G...D...A");
- *
- * # Config: #
- *
- * Ext.define('SmartPhone', {
- * config: {
- * hasTouchScreen: false,
- * operatingSystem: 'Other',
- * price: 500
- * },
- *
- * isExpensive: false,
- *
- * constructor: function(config) {
- * this.initConfig(config);
- *
- * return this;
- * },
- *
- * applyPrice: function(price) {
- * this.isExpensive = (price > 500);
- *
- * return price;
- * },
- *
- * applyOperatingSystem: function(operatingSystem) {
- * if (!(/^(iOS|Android|BlackBerry)$/i).test(operatingSystem)) {
- * return 'Other';
- * }
- *
- * return operatingSystem;
- * }
- * });
- *
- * var iPhone = new SmartPhone({
- * hasTouchScreen: true,
- * operatingSystem: 'iOS'
- * });
- *
- * iPhone.getPrice(); // 500;
- * iPhone.getOperatingSystem(); // 'iOS'
- * iPhone.getHasTouchScreen(); // true;
- * iPhone.hasTouchScreen(); // true
- *
- * iPhone.isExpensive; // false;
- * iPhone.setPrice(600);
- * iPhone.getPrice(); // 600
- * iPhone.isExpensive; // true;
- *
- * iPhone.setOperatingSystem('AlienOS');
- * iPhone.getOperatingSystem(); // 'Other'
- *
- * # Statics: #
- *
- * Ext.define('Computer', {
- * statics: {
- * factory: function(brand) {
- * // 'this' in static methods refer to the class itself
- * return new this(brand);
- * }
- * },
- *
- * constructor: function() { ... }
- * });
- *
- * var dellComputer = Computer.factory('Dell');
- *
- * Also see {@link Ext.Base#statics} and {@link Ext.Base#self} for more details on accessing
- * static properties within class methods
*
+ * Handles class creation throughout the framework. This is a low level factory that is used by Ext.ClassManager and generally
+ * should not be used directly. If you choose to use Ext.Class you will lose out on the namespace, aliasing and depency loading
+ * features made available by Ext.ClassManager. The only time you would use Ext.Class directly is to create an anonymous class.
+ *
+ * If you wish to create a class you should use {@link Ext#define Ext.define} which aliases
+ * {@link Ext.ClassManager#create Ext.ClassManager.create} to enable namespacing and dynamic dependency resolution.
+ *
+ * Ext.Class is the factory and **not** the superclass of everything. For the base class that **all** Ext classes inherit
+ * from, see {@link Ext.Base}.
*/
(function() {
}
/**
- * @constructor
+ * @method constructor
+ * Creates new class.
* @param {Object} classData An object represent the properties of this class
- * @param {Function} createdFn Optional, the callback function to be executed when this class is fully created.
+ * @param {Function} createdFn (Optional) The callback function to be executed when this class is fully created.
* Note that the creation process can be asynchronous depending on the pre-processors used.
* @return {Ext.Base} The newly created class
*/
Ext.Class = Class = function(newClass, classData, onClassCreated) {
- if (typeof newClass !== 'function') {
+ if (typeof newClass != 'function') {
onClassCreated = classData;
classData = newClass;
newClass = function() {
registeredPreprocessors = Class.getPreprocessors(),
index = 0,
preprocessors = [],
- preprocessor, preprocessors, staticPropertyName, process, i, j, ln;
+ preprocessor, staticPropertyName, process, i, j, ln;
for (i = 0, ln = baseStaticProperties.length; i < ln; i++) {
staticPropertyName = baseStaticProperties[i];
for (j = 0, ln = preprocessorStack.length; j < ln; j++) {
preprocessor = preprocessorStack[j];
- if (typeof preprocessor === 'string') {
+ if (typeof preprocessor == 'string') {
preprocessor = registeredPreprocessors[preprocessor];
if (!preprocessor.always) {
}
}
- classData.onClassCreated = onClassCreated;
+ classData.onClassCreated = onClassCreated || Ext.emptyFn;
classData.onBeforeClassCreated = function(cls, data) {
onClassCreated = data.onClassCreated;
cls.implement(data);
- if (onClassCreated) {
- onClassCreated.call(cls, cls);
- }
+ onClassCreated.call(cls, cls);
};
process = function(cls, data) {
/**
* Register a new pre-processor to be used during the class creation process
*
- * @member Ext.Class registerPreprocessor
+ * @member Ext.Class
* @param {String} name The pre-processor's name
* @param {Function} fn The callback function to be executed. Typical format:
-
- function(cls, data, fn) {
- // Your code here
-
- // Execute this when the processing is finished.
- // Asynchronous processing is perfectly ok
- if (fn) {
- fn.call(this, cls, data);
- }
- });
-
- * Passed arguments for this function are:
*
- * - `{Function} cls`: The created class
- * - `{Object} data`: The set of properties passed in {@link Ext.Class} constructor
- * - `{Function} fn`: The callback function that <b>must</b> to be executed when this pre-processor finishes,
+ * function(cls, data, fn) {
+ * // Your code here
+ *
+ * // Execute this when the processing is finished.
+ * // Asynchronous processing is perfectly ok
+ * if (fn) {
+ * fn.call(this, cls, data);
+ * }
+ * });
+ *
+ * @param {Function} fn.cls The created class
+ * @param {Object} fn.data The set of properties passed in {@link Ext.Class} constructor
+ * @param {Function} fn.fn The callback function that **must** to be executed when this pre-processor finishes,
* regardless of whether the processing is synchronous or aynchronous
*
* @return {Ext.Class} this
- * @markdown
+ * @static
*/
registerPreprocessor: function(name, fn, always) {
this.preprocessors[name] = {
*
* @param {String} name
* @return {Function} preprocessor
+ * @static
*/
getPreprocessor: function(name) {
return this.preprocessors[name];
/**
* Retrieve the array stack of default pre-processors
*
- * @return {Function} defaultPreprocessors
+ * @return {Function[]} defaultPreprocessors
+ * @static
*/
getDefaultPreprocessors: function() {
return this.defaultPreprocessors || [];
/**
* Set the default array stack of default pre-processors
*
- * @param {Array} preprocessors
+ * @param {Function/Function[]} preprocessors
* @return {Ext.Class} this
+ * @static
*/
setDefaultPreprocessors: function(preprocessors) {
this.defaultPreprocessors = Ext.Array.from(preprocessors);
},
/**
- * Insert this pre-processor at a specific position in the stack, optionally relative to
+ * Inserts this pre-processor at a specific position in the stack, optionally relative to
* any existing pre-processor. For example:
-
- Ext.Class.registerPreprocessor('debug', function(cls, data, fn) {
- // Your code here
-
- if (fn) {
- fn.call(this, cls, data);
- }
- }).insertDefaultPreprocessor('debug', 'last');
-
+ *
+ * Ext.Class.registerPreprocessor('debug', function(cls, data, fn) {
+ * // Your code here
+ *
+ * if (fn) {
+ * fn.call(this, cls, data);
+ * }
+ * }).setDefaultPreprocessorPosition('debug', 'last');
+ *
* @param {String} name The pre-processor name. Note that it needs to be registered with
- * {@link Ext#registerPreprocessor registerPreprocessor} before this
+ * {@link #registerPreprocessor registerPreprocessor} before this
* @param {String} offset The insertion position. Four possible values are:
* 'first', 'last', or: 'before', 'after' (relative to the name provided in the third argument)
* @param {String} relativeName
* @return {Ext.Class} this
- * @markdown
+ * @static
*/
setDefaultPreprocessorPosition: function(name, offset, relativeName) {
var defaultPreprocessors = this.defaultPreprocessors,
index;
- if (typeof offset === 'string') {
+ if (typeof offset == 'string') {
if (offset === 'first') {
defaultPreprocessors.unshift(name);
index = Ext.Array.indexOf(defaultPreprocessors, relativeName);
if (index !== -1) {
- defaultPreprocessors.splice(Math.max(0, index + offset), 0, name);
+ Ext.Array.splice(defaultPreprocessors, Math.max(0, index + offset), 0, name);
}
return this;
}
});
+ /**
+ * @cfg {String} extend
+ * The parent class that this class extends. For example:
+ *
+ * Ext.define('Person', {
+ * say: function(text) { alert(text); }
+ * });
+ *
+ * Ext.define('Developer', {
+ * extend: 'Person',
+ * say: function(text) { this.callParent(["print "+text]); }
+ * });
+ */
Class.registerPreprocessor('extend', function(cls, data) {
var extend = data.extend,
base = Ext.Base,
delete data.extend;
+ //<feature classSystem.inheritableStatics>
// Statics inheritance
parentStatics = parentPrototype.$inheritableStatics;
}
}
}
+ //</feature>
+ //<feature classSystem.config>
// Merge the parent class' config object without referencing it
if (parentPrototype.config) {
clsPrototype.config = Ext.Object.merge({}, parentPrototype.config);
else {
clsPrototype.config = {};
}
+ //</feature>
+ //<feature classSystem.onClassExtended>
if (clsPrototype.$onExtended) {
clsPrototype.$onExtended.call(cls, cls, data);
}
clsPrototype.$onExtended = data.onClassExtended;
delete data.onClassExtended;
}
+ //</feature>
}, true);
+ //<feature classSystem.statics>
+ /**
+ * @cfg {Object} statics
+ * List of static methods for this class. For example:
+ *
+ * Ext.define('Computer', {
+ * statics: {
+ * factory: function(brand) {
+ * // 'this' in static methods refer to the class itself
+ * return new this(brand);
+ * }
+ * },
+ *
+ * constructor: function() { ... }
+ * });
+ *
+ * var dellComputer = Computer.factory('Dell');
+ */
Class.registerPreprocessor('statics', function(cls, data) {
- var statics = data.statics,
- name;
-
- for (name in statics) {
- if (statics.hasOwnProperty(name)) {
- cls[name] = statics[name];
- }
- }
+ cls.addStatics(data.statics);
delete data.statics;
});
+ //</feature>
+ //<feature classSystem.inheritableStatics>
+ /**
+ * @cfg {Object} inheritableStatics
+ * List of inheritable static methods for this class.
+ * Otherwise just like {@link #statics} but subclasses inherit these methods.
+ */
Class.registerPreprocessor('inheritableStatics', function(cls, data) {
- var statics = data.inheritableStatics,
- inheritableStatics,
- prototype = cls.prototype,
- name;
-
- inheritableStatics = prototype.$inheritableStatics;
-
- if (!inheritableStatics) {
- inheritableStatics = prototype.$inheritableStatics = [];
- }
-
- for (name in statics) {
- if (statics.hasOwnProperty(name)) {
- cls[name] = statics[name];
- inheritableStatics.push(name);
- }
- }
+ cls.addInheritableStatics(data.inheritableStatics);
delete data.inheritableStatics;
});
+ //</feature>
- Class.registerPreprocessor('mixins', function(cls, data) {
- cls.mixin(data.mixins);
-
- delete data.mixins;
- });
-
+ //<feature classSystem.config>
+ /**
+ * @cfg {Object} config
+ * List of configuration options with their default values, for which automatically
+ * accessor methods are generated. For example:
+ *
+ * Ext.define('SmartPhone', {
+ * config: {
+ * hasTouchScreen: false,
+ * operatingSystem: 'Other',
+ * price: 500
+ * },
+ * constructor: function(cfg) {
+ * this.initConfig(cfg);
+ * }
+ * });
+ *
+ * var iPhone = new SmartPhone({
+ * hasTouchScreen: true,
+ * operatingSystem: 'iOS'
+ * });
+ *
+ * iPhone.getPrice(); // 500;
+ * iPhone.getOperatingSystem(); // 'iOS'
+ * iPhone.getHasTouchScreen(); // true;
+ * iPhone.hasTouchScreen(); // true
+ */
Class.registerPreprocessor('config', function(cls, data) {
var prototype = cls.prototype;
data[setter] = function(val) {
var ret = this[apply].call(this, val, this[pName]);
- if (ret !== undefined) {
+ if (typeof ret != 'undefined') {
this[pName] = ret;
}
Ext.Object.merge(prototype.config, data.config);
delete data.config;
});
+ //</feature>
- Class.setDefaultPreprocessors(['extend', 'statics', 'inheritableStatics', 'mixins', 'config']);
+ //<feature classSystem.mixins>
+ /**
+ * @cfg {Object} mixins
+ * List of classes to mix into this class. For example:
+ *
+ * Ext.define('CanSing', {
+ * sing: function() {
+ * alert("I'm on the highway to hell...")
+ * }
+ * });
+ *
+ * Ext.define('Musician', {
+ * extend: 'Person',
+ *
+ * mixins: {
+ * canSing: 'CanSing'
+ * }
+ * })
+ */
+ Class.registerPreprocessor('mixins', function(cls, data) {
+ var mixins = data.mixins,
+ name, mixin, i, ln;
+ delete data.mixins;
+
+ Ext.Function.interceptBefore(data, 'onClassCreated', function(cls) {
+ if (mixins instanceof Array) {
+ for (i = 0,ln = mixins.length; i < ln; i++) {
+ mixin = mixins[i];
+ name = mixin.prototype.mixinId || mixin.$className;
+
+ cls.mixin(name, mixin);
+ }
+ }
+ else {
+ for (name in mixins) {
+ if (mixins.hasOwnProperty(name)) {
+ cls.mixin(name, mixins[name]);
+ }
+ }
+ }
+ });
+ });
+
+ //</feature>
+
+ Class.setDefaultPreprocessors([
+ 'extend'
+ //<feature classSystem.statics>
+ ,'statics'
+ //</feature>
+ //<feature classSystem.inheritableStatics>
+ ,'inheritableStatics'
+ //</feature>
+ //<feature classSystem.config>
+ ,'config'
+ //</feature>
+ //<feature classSystem.mixins>
+ ,'mixins'
+ //</feature>
+ ]);
+
+ //<feature classSystem.backwardsCompatible>
// Backwards compatible
Ext.extend = function(subclass, superclass, members) {
if (arguments.length === 2 && Ext.isObject(superclass)) {
}
members.extend = superclass;
- members.preprocessors = ['extend', 'mixins', 'config', 'statics'];
+ members.preprocessors = [
+ 'extend'
+ //<feature classSystem.statics>
+ ,'statics'
+ //</feature>
+ //<feature classSystem.inheritableStatics>
+ ,'inheritableStatics'
+ //</feature>
+ //<feature classSystem.mixins>
+ ,'mixins'
+ //</feature>
+ //<feature classSystem.config>
+ ,'config'
+ //</feature>
+ ];
if (subclass) {
cls = new Class(subclass, members);
return cls;
};
+ //</feature>
})();
* @author Jacky Nguyen <jacky@sencha.com>
* @docauthor Jacky Nguyen <jacky@sencha.com>
* @class Ext.ClassManager
-
-Ext.ClassManager manages all classes and handles mapping from string class name to
-actual class objects throughout the whole framework. It is not generally accessed directly, rather through
-these convenient shorthands:
-
-- {@link Ext#define Ext.define}
-- {@link Ext#create Ext.create}
-- {@link Ext#widget Ext.widget}
-- {@link Ext#getClass Ext.getClass}
-- {@link Ext#getClassName Ext.getClassName}
-
+ *
+ * Ext.ClassManager manages all classes and handles mapping from string class name to
+ * actual class objects throughout the whole framework. It is not generally accessed directly, rather through
+ * these convenient shorthands:
+ *
+ * - {@link Ext#define Ext.define}
+ * - {@link Ext#create Ext.create}
+ * - {@link Ext#widget Ext.widget}
+ * - {@link Ext#getClass Ext.getClass}
+ * - {@link Ext#getClassName Ext.getClassName}
+ *
+ * # Basic syntax:
+ *
+ * Ext.define(className, properties);
+ *
+ * in which `properties` is an object represent a collection of properties that apply to the class. See
+ * {@link Ext.ClassManager#create} for more detailed instructions.
+ *
+ * Ext.define('Person', {
+ * name: 'Unknown',
+ *
+ * constructor: function(name) {
+ * if (name) {
+ * this.name = name;
+ * }
+ *
+ * return this;
+ * },
+ *
+ * eat: function(foodType) {
+ * alert("I'm eating: " + foodType);
+ *
+ * return this;
+ * }
+ * });
+ *
+ * var aaron = new Person("Aaron");
+ * aaron.eat("Sandwich"); // alert("I'm eating: Sandwich");
+ *
+ * Ext.Class has a powerful set of extensible {@link Ext.Class#registerPreprocessor pre-processors} which takes care of
+ * everything related to class creation, including but not limited to inheritance, mixins, configuration, statics, etc.
+ *
+ * # Inheritance:
+ *
+ * Ext.define('Developer', {
+ * extend: 'Person',
+ *
+ * constructor: function(name, isGeek) {
+ * this.isGeek = isGeek;
+ *
+ * // Apply a method from the parent class' prototype
+ * this.callParent([name]);
+ *
+ * return this;
+ *
+ * },
+ *
+ * code: function(language) {
+ * alert("I'm coding in: " + language);
+ *
+ * this.eat("Bugs");
+ *
+ * return this;
+ * }
+ * });
+ *
+ * var jacky = new Developer("Jacky", true);
+ * jacky.code("JavaScript"); // alert("I'm coding in: JavaScript");
+ * // alert("I'm eating: Bugs");
+ *
+ * See {@link Ext.Base#callParent} for more details on calling superclass' methods
+ *
+ * # Mixins:
+ *
+ * Ext.define('CanPlayGuitar', {
+ * playGuitar: function() {
+ * alert("F#...G...D...A");
+ * }
+ * });
+ *
+ * Ext.define('CanComposeSongs', {
+ * composeSongs: function() { ... }
+ * });
+ *
+ * Ext.define('CanSing', {
+ * sing: function() {
+ * alert("I'm on the highway to hell...")
+ * }
+ * });
+ *
+ * Ext.define('Musician', {
+ * extend: 'Person',
+ *
+ * mixins: {
+ * canPlayGuitar: 'CanPlayGuitar',
+ * canComposeSongs: 'CanComposeSongs',
+ * canSing: 'CanSing'
+ * }
+ * })
+ *
+ * Ext.define('CoolPerson', {
+ * extend: 'Person',
+ *
+ * mixins: {
+ * canPlayGuitar: 'CanPlayGuitar',
+ * canSing: 'CanSing'
+ * },
+ *
+ * sing: function() {
+ * alert("Ahem....");
+ *
+ * this.mixins.canSing.sing.call(this);
+ *
+ * alert("[Playing guitar at the same time...]");
+ *
+ * this.playGuitar();
+ * }
+ * });
+ *
+ * var me = new CoolPerson("Jacky");
+ *
+ * me.sing(); // alert("Ahem...");
+ * // alert("I'm on the highway to hell...");
+ * // alert("[Playing guitar at the same time...]");
+ * // alert("F#...G...D...A");
+ *
+ * # Config:
+ *
+ * Ext.define('SmartPhone', {
+ * config: {
+ * hasTouchScreen: false,
+ * operatingSystem: 'Other',
+ * price: 500
+ * },
+ *
+ * isExpensive: false,
+ *
+ * constructor: function(config) {
+ * this.initConfig(config);
+ *
+ * return this;
+ * },
+ *
+ * applyPrice: function(price) {
+ * this.isExpensive = (price > 500);
+ *
+ * return price;
+ * },
+ *
+ * applyOperatingSystem: function(operatingSystem) {
+ * if (!(/^(iOS|Android|BlackBerry)$/i).test(operatingSystem)) {
+ * return 'Other';
+ * }
+ *
+ * return operatingSystem;
+ * }
+ * });
+ *
+ * var iPhone = new SmartPhone({
+ * hasTouchScreen: true,
+ * operatingSystem: 'iOS'
+ * });
+ *
+ * iPhone.getPrice(); // 500;
+ * iPhone.getOperatingSystem(); // 'iOS'
+ * iPhone.getHasTouchScreen(); // true;
+ * iPhone.hasTouchScreen(); // true
+ *
+ * iPhone.isExpensive; // false;
+ * iPhone.setPrice(600);
+ * iPhone.getPrice(); // 600
+ * iPhone.isExpensive; // true;
+ *
+ * iPhone.setOperatingSystem('AlienOS');
+ * iPhone.getOperatingSystem(); // 'Other'
+ *
+ * # Statics:
+ *
+ * Ext.define('Computer', {
+ * statics: {
+ * factory: function(brand) {
+ * // 'this' in static methods refer to the class itself
+ * return new this(brand);
+ * }
+ * },
+ *
+ * constructor: function() { ... }
+ * });
+ *
+ * var dellComputer = Computer.factory('Dell');
+ *
+ * Also see {@link Ext.Base#statics} and {@link Ext.Base#self} for more details on accessing
+ * static properties within class methods
+ *
* @singleton
- * @markdown
*/
(function(Class, alias) {
var Manager = Ext.ClassManager = {
/**
- * @property classes
- * @type Object
+ * @property {Object} classes
* All classes which were defined through the ClassManager. Keys are the
* name of the classes and the values are references to the classes.
* @private
/**
* Creates a namespace and assign the `value` to the created object
-
- Ext.ClassManager.setNamespace('MyCompany.pkg.Example', someObject);
-
- alert(MyCompany.pkg.Example === someObject); // alerts true
-
+ *
+ * Ext.ClassManager.setNamespace('MyCompany.pkg.Example', someObject);
+ *
+ * alert(MyCompany.pkg.Example === someObject); // alerts true
+ *
* @param {String} name
- * @param {Mixed} value
- * @markdown
+ * @param {Object} value
*/
setNamespace: function(name, value) {
var root = Ext.global,
parts = this.parseNamespace(name),
- leaf = parts.pop(),
- i, ln, part;
+ ln = parts.length - 1,
+ leaf = parts[ln],
+ i, part;
- for (i = 0, ln = parts.length; i < ln; i++) {
+ for (i = 0; i < ln; i++) {
part = parts[i];
if (typeof part !== 'string') {
* Retrieve a class by its name.
*
* @param {String} name
- * @return {Class} class
+ * @return {Ext.Class} class
*/
get: function(name) {
if (this.classes.hasOwnProperty(name)) {
/**
* Register the alias for a class.
*
- * @param {Class/String} cls a reference to a class or a className
+ * @param {Ext.Class/String} cls a reference to a class or a className
* @param {String} alias Alias to use when referring to this class
*/
setAlias: function(cls, alias) {
* Get a reference to the class by its alias.
*
* @param {String} alias
- * @return {Class} class
+ * @return {Ext.Class} class
*/
getByAlias: function(alias) {
return this.get(this.getNameByAlias(alias));
* Get the aliases of a class by the class name
*
* @param {String} name
- * @return {Array} aliases
+ * @return {String[]} aliases
*/
getAliasesByName: function(name) {
return this.maps.nameToAliases[name] || [];
},
/**
- * Get the name of the class by its reference or its instance;
- * usually invoked by the shorthand {@link Ext#getClassName Ext.getClassName}
-
- Ext.ClassManager.getName(Ext.Action); // returns "Ext.Action"
-
- * @param {Class/Object} object
+ * Get the name of the class by its reference or its instance.
+ *
+ * Ext.ClassManager.getName(Ext.Action); // returns "Ext.Action"
+ *
+ * {@link Ext#getClassName Ext.getClassName} is alias for {@link Ext.ClassManager#getName Ext.ClassManager.getName}.
+ *
+ * @param {Ext.Class/Object} object
* @return {String} className
- * @markdown
*/
getName: function(object) {
return object && object.$className || '';
/**
* Get the class of the provided object; returns null if it's not an instance
- * of any class created with Ext.define. This is usually invoked by the shorthand {@link Ext#getClass Ext.getClass}
+ * of any class created with Ext.define.
+ *
+ * var component = new Ext.Component();
+ *
+ * Ext.ClassManager.getClass(component); // returns Ext.Component
+ *
+ * {@link Ext#getClass Ext.getClass} is alias for {@link Ext.ClassManager#getClass Ext.ClassManager.getClass}.
*
- var component = new Ext.Component();
-
- Ext.ClassManager.getClass(component); // returns Ext.Component
- *
* @param {Object} object
- * @return {Class} class
- * @markdown
+ * @return {Ext.Class} class
*/
getClass: function(object) {
return object && object.self || null;
},
/**
- * Defines a class. This is usually invoked via the alias {@link Ext#define Ext.define}
-
- Ext.ClassManager.create('My.awesome.Class', {
- someProperty: 'something',
- someMethod: function() { ... }
- ...
-
- }, function() {
- alert('Created!');
- alert(this === My.awesome.Class); // alerts true
-
- var myInstance = new this();
- });
-
+ * Defines a class.
+ *
+ * {@link Ext#define Ext.define} and {@link Ext.ClassManager#create Ext.ClassManager.create} are almost aliases
+ * of each other, with the only exception that Ext.define allows definition of {@link Ext.Class#override overrides}.
+ * To avoid trouble, always use Ext.define.
+ *
+ * Ext.define('My.awesome.Class', {
+ * someProperty: 'something',
+ * someMethod: function() { ... }
+ * ...
+ *
+ * }, function() {
+ * alert('Created!');
+ * alert(this === My.awesome.Class); // alerts true
+ *
+ * var myInstance = new this();
+ * });
+ *
* @param {String} className The class name to create in string dot-namespaced format, for example:
- * 'My.very.awesome.Class', 'FeedViewer.plugin.CoolPager'
- * It is highly recommended to follow this simple convention:
-
-- The root and the class name are 'CamelCased'
-- Everything else is lower-cased
-
- * @param {Object} data The key - value pairs of properties to apply to this class. Property names can be of any valid
- * strings, except those in the reserved listed below:
-
-- `mixins`
-- `statics`
-- `config`
-- `alias`
-- `self`
-- `singleton`
-- `alternateClassName`
+ * `My.very.awesome.Class`, `FeedViewer.plugin.CoolPager`. It is highly recommended to follow this simple convention:
+ *
+ * - The root and the class name are 'CamelCased'
+ * - Everything else is lower-cased
+ *
+ * @param {Object} data The key-value pairs of properties to apply to this class. Property names can be of any valid
+ * strings, except those in the reserved list below:
*
- * @param {Function} createdFn Optional callback to execute after the class is created, the execution scope of which
+ * - {@link Ext.Base#self self}
+ * - {@link Ext.Class#alias alias}
+ * - {@link Ext.Class#alternateClassName alternateClassName}
+ * - {@link Ext.Class#config config}
+ * - {@link Ext.Class#extend extend}
+ * - {@link Ext.Class#inheritableStatics inheritableStatics}
+ * - {@link Ext.Class#mixins mixins}
+ * - {@link Ext.Class#override override} (only when using {@link Ext#define Ext.define})
+ * - {@link Ext.Class#requires requires}
+ * - {@link Ext.Class#singleton singleton}
+ * - {@link Ext.Class#statics statics}
+ * - {@link Ext.Class#uses uses}
+ *
+ * @param {Function} [createdFn] callback to execute after the class is created, the execution scope of which
* (`this`) will be the newly created class itself.
+ *
* @return {Ext.Base}
- * @markdown
*/
create: function(className, data, createdFn) {
var manager = this;
registeredPostprocessors = manager.postprocessors,
index = 0,
postprocessors = [],
- postprocessor, postprocessors, process, i, ln;
+ postprocessor, process, i, ln;
delete data.postprocessors;
},
/**
- * Instantiate a class by its alias; usually invoked by the convenient shorthand {@link Ext#createByAlias Ext.createByAlias}
+ * Instantiate a class by its alias.
+ *
* If {@link Ext.Loader} is {@link Ext.Loader#setConfig enabled} and the class has not been defined yet, it will
* attempt to load the class via synchronous loading.
-
- var window = Ext.ClassManager.instantiateByAlias('widget.window', { width: 600, height: 800, ... });
-
+ *
+ * var window = Ext.ClassManager.instantiateByAlias('widget.window', { width: 600, height: 800, ... });
+ *
+ * {@link Ext#createByAlias Ext.createByAlias} is alias for {@link Ext.ClassManager#instantiateByAlias Ext.ClassManager.instantiateByAlias}.
+ *
* @param {String} alias
- * @param {Mixed} args,... Additional arguments after the alias will be passed to the
+ * @param {Object...} args Additional arguments after the alias will be passed to the
* class constructor.
* @return {Object} instance
- * @markdown
*/
instantiateByAlias: function() {
var alias = arguments[0],
},
/**
- * Instantiate a class by either full name, alias or alternate name; usually invoked by the convenient
- * shorthand {@link Ext#create Ext.create}
+ * Instantiate a class by either full name, alias or alternate name.
*
* If {@link Ext.Loader} is {@link Ext.Loader#setConfig enabled} and the class has not been defined yet, it will
* attempt to load the class via synchronous loading.
*
* For example, all these three lines return the same result:
-
- // alias
- var window = Ext.ClassManager.instantiate('widget.window', { width: 600, height: 800, ... });
-
- // alternate name
- var window = Ext.ClassManager.instantiate('Ext.Window', { width: 600, height: 800, ... });
-
- // full class name
- var window = Ext.ClassManager.instantiate('Ext.window.Window', { width: 600, height: 800, ... });
-
+ *
+ * // alias
+ * var window = Ext.ClassManager.instantiate('widget.window', { width: 600, height: 800, ... });
+ *
+ * // alternate name
+ * var window = Ext.ClassManager.instantiate('Ext.Window', { width: 600, height: 800, ... });
+ *
+ * // full class name
+ * var window = Ext.ClassManager.instantiate('Ext.window.Window', { width: 600, height: 800, ... });
+ *
+ * {@link Ext#create Ext.create} is alias for {@link Ext.ClassManager#instantiate Ext.ClassManager.instantiate}.
+ *
* @param {String} name
- * @param {Mixed} args,... Additional arguments after the name will be passed to the class' constructor.
+ * @param {Object...} args Additional arguments after the name will be passed to the class' constructor.
* @return {Object} instance
- * @markdown
*/
instantiate: function() {
var name = arguments[0],
/**
* Set the default post processors array stack which are applied to every class.
*
- * @param {String/Array} The name of a registered post processor or an array of registered names.
+ * @param {String/String[]} The name of a registered post processor or an array of registered names.
* @return {Ext.ClassManager} this
*/
setDefaultPostprocessors: function(postprocessors) {
index = Ext.Array.indexOf(defaultPostprocessors, relativeName);
if (index !== -1) {
- defaultPostprocessors.splice(Math.max(0, index + offset), 0, name);
+ Ext.Array.splice(defaultPostprocessors, Math.max(0, index + offset), 0, name);
}
return this;
/**
* Converts a string expression to an array of matching class names. An expression can either refers to class aliases
* or class names. Expressions support wildcards:
-
- // returns ['Ext.window.Window']
- var window = Ext.ClassManager.getNamesByExpression('widget.window');
-
- // returns ['widget.panel', 'widget.window', ...]
- var allWidgets = Ext.ClassManager.getNamesByExpression('widget.*');
-
- // returns ['Ext.data.Store', 'Ext.data.ArrayProxy', ...]
- var allData = Ext.ClassManager.getNamesByExpression('Ext.data.*');
-
+ *
+ * // returns ['Ext.window.Window']
+ * var window = Ext.ClassManager.getNamesByExpression('widget.window');
+ *
+ * // returns ['widget.panel', 'widget.window', ...]
+ * var allWidgets = Ext.ClassManager.getNamesByExpression('widget.*');
+ *
+ * // returns ['Ext.data.Store', 'Ext.data.ArrayProxy', ...]
+ * var allData = Ext.ClassManager.getNamesByExpression('Ext.data.*');
+ *
* @param {String} expression
- * @return {Array} classNames
- * @markdown
+ * @return {String[]} classNames
*/
getNamesByExpression: function(expression) {
var nameToAliasesMap = this.maps.nameToAliases,
}
};
+ var defaultPostprocessors = Manager.defaultPostprocessors;
+ //<feature classSystem.alias>
+
+ /**
+ * @cfg {String[]} alias
+ * @member Ext.Class
+ * List of short aliases for class names. Most useful for defining xtypes for widgets:
+ *
+ * Ext.define('MyApp.CoolPanel', {
+ * extend: 'Ext.panel.Panel',
+ * alias: ['widget.coolpanel'],
+ * title: 'Yeah!'
+ * });
+ *
+ * // Using Ext.create
+ * Ext.widget('widget.coolpanel');
+ * // Using the shorthand for widgets and in xtypes
+ * Ext.widget('panel', {
+ * items: [
+ * {xtype: 'coolpanel', html: 'Foo'},
+ * {xtype: 'coolpanel', html: 'Bar'}
+ * ]
+ * });
+ */
Manager.registerPostprocessor('alias', function(name, cls, data) {
var aliases = data.alias,
- widgetPrefix = 'widget.',
- i, ln, alias;
+ i, ln;
- if (!(aliases instanceof Array)) {
- aliases = [aliases];
- }
+ delete data.alias;
for (i = 0, ln = aliases.length; i < ln; i++) {
alias = aliases[i];
- //<debug error>
- if (typeof alias !== 'string') {
- Ext.Error.raise({
- sourceClass: "Ext",
- sourceMethod: "define",
- msg: "Invalid alias of: '" + alias + "' for class: '" + name + "'; must be a valid string"
- });
- }
- //</debug>
-
this.setAlias(cls, alias);
}
-
- // This is ugly, will change to make use of parseNamespace for alias later on
- for (i = 0, ln = aliases.length; i < ln; i++) {
- alias = aliases[i];
-
- if (alias.substring(0, widgetPrefix.length) === widgetPrefix) {
- // Only the first alias with 'widget.' prefix will be used for xtype
- cls.xtype = cls.$xtype = alias.substring(widgetPrefix.length);
- break;
- }
- }
});
+ /**
+ * @cfg {Boolean} singleton
+ * @member Ext.Class
+ * When set to true, the class will be instantiated as singleton. For example:
+ *
+ * Ext.define('Logger', {
+ * singleton: true,
+ * log: function(msg) {
+ * console.log(msg);
+ * }
+ * });
+ *
+ * Logger.log('Hello');
+ */
Manager.registerPostprocessor('singleton', function(name, cls, data, fn) {
fn.call(this, name, new cls(), data);
return false;
});
+ /**
+ * @cfg {String/String[]} alternateClassName
+ * @member Ext.Class
+ * Defines alternate names for this class. For example:
+ *
+ * Ext.define('Developer', {
+ * alternateClassName: ['Coder', 'Hacker'],
+ * code: function(msg) {
+ * alert('Typing... ' + msg);
+ * }
+ * });
+ *
+ * var joe = Ext.create('Developer');
+ * joe.code('stackoverflow');
+ *
+ * var rms = Ext.create('Hacker');
+ * rms.code('hack hack');
+ */
Manager.registerPostprocessor('alternateClassName', function(name, cls, data) {
var alternates = data.alternateClassName,
i, ln, alternate;
Ext.apply(Ext, {
/**
- * Convenient shorthand, see {@link Ext.ClassManager#instantiate}
+ * @method
* @member Ext
- * @method create
+ * @alias Ext.ClassManager#instantiate
*/
create: alias(Manager, 'instantiate'),
* @private
* API to be stablized
*
- * @param {Mixed} item
+ * @param {Object} item
* @param {String} namespace
*/
factory: function(item, namespace) {
/**
* Convenient shorthand to create a widget by its xtype, also see {@link Ext.ClassManager#instantiateByAlias}
-
- var button = Ext.widget('button'); // Equivalent to Ext.create('widget.button')
- var panel = Ext.widget('panel'); // Equivalent to Ext.create('widget.panel')
-
+ *
+ * var button = Ext.widget('button'); // Equivalent to Ext.create('widget.button')
+ * var panel = Ext.widget('panel'); // Equivalent to Ext.create('widget.panel')
+ *
+ * @method
* @member Ext
- * @method widget
- * @markdown
+ * @param {String} name xtype of the widget to create.
+ * @param {Object...} args arguments for the widget constructor.
+ * @return {Object} widget instance
*/
widget: function(name) {
var args = slice.call(arguments);
},
/**
- * Convenient shorthand, see {@link Ext.ClassManager#instantiateByAlias}
+ * @method
* @member Ext
- * @method createByAlias
+ * @alias Ext.ClassManager#instantiateByAlias
*/
createByAlias: alias(Manager, 'instantiateByAlias'),
/**
- * Convenient shorthand for {@link Ext.ClassManager#create}, see detailed {@link Ext.Class explanation}
+ * @cfg {String} override
+ * @member Ext.Class
+ *
+ * Defines an override applied to a class. Note that **overrides can only be created using
+ * {@link Ext#define}.** {@link Ext.ClassManager#create} only creates classes.
+ *
+ * To define an override, include the override property. The content of an override is
+ * aggregated with the specified class in order to extend or modify that class. This can be
+ * as simple as setting default property values or it can extend and/or replace methods.
+ * This can also extend the statics of the class.
+ *
+ * One use for an override is to break a large class into manageable pieces.
+ *
+ * // File: /src/app/Panel.js
+ *
+ * Ext.define('My.app.Panel', {
+ * extend: 'Ext.panel.Panel',
+ * requires: [
+ * 'My.app.PanelPart2',
+ * 'My.app.PanelPart3'
+ * ]
+ *
+ * constructor: function (config) {
+ * this.callSuper(arguments); // calls Ext.panel.Panel's constructor
+ * //...
+ * },
+ *
+ * statics: {
+ * method: function () {
+ * return 'abc';
+ * }
+ * }
+ * });
+ *
+ * // File: /src/app/PanelPart2.js
+ * Ext.define('My.app.PanelPart2', {
+ * override: 'My.app.Panel',
+ *
+ * constructor: function (config) {
+ * this.callSuper(arguments); // calls My.app.Panel's constructor
+ * //...
+ * }
+ * });
+ *
+ * Another use of overrides is to provide optional parts of classes that can be
+ * independently required. In this case, the class may even be unaware of the
+ * override altogether.
+ *
+ * Ext.define('My.ux.CoolTip', {
+ * override: 'Ext.tip.ToolTip',
+ *
+ * constructor: function (config) {
+ * this.callSuper(arguments); // calls Ext.tip.ToolTip's constructor
+ * //...
+ * }
+ * });
+ *
+ * The above override can now be required as normal.
+ *
+ * Ext.define('My.app.App', {
+ * requires: [
+ * 'My.ux.CoolTip'
+ * ]
+ * });
+ *
+ * Overrides can also contain statics:
+ *
+ * Ext.define('My.app.BarMod', {
+ * override: 'Ext.foo.Bar',
+ *
+ * statics: {
+ * method: function (x) {
+ * return this.callSuper([x * 2]); // call Ext.foo.Bar.method
+ * }
+ * }
+ * });
+ *
+ * IMPORTANT: An override is only included in a build if the class it overrides is
+ * required. Otherwise, the override, like the target class, is not included.
+ */
+
+ /**
+ * @method
+ *
* @member Ext
- * @method define
+ * @alias Ext.ClassManager#create
*/
- define: alias(Manager, 'create'),
+ define: function (className, data, createdFn) {
+ if (!data.override) {
+ return Manager.create.apply(Manager, arguments);
+ }
+
+ var requires = data.requires,
+ uses = data.uses,
+ overrideName = className;
+
+ className = data.override;
+
+ // hoist any 'requires' or 'uses' from the body onto the faux class:
+ data = Ext.apply({}, data);
+ delete data.requires;
+ delete data.uses;
+ delete data.override;
+
+ // make sure className is in the requires list:
+ if (typeof requires == 'string') {
+ requires = [ className, requires ];
+ } else if (requires) {
+ requires = requires.slice(0);
+ requires.unshift(className);
+ } else {
+ requires = [ className ];
+ }
+
+// TODO - we need to rework this to allow the override to not require the target class
+// and rather 'wait' for it in such a way that if the target class is not in the build,
+// neither are any of its overrides.
+//
+// Also, this should process the overrides for a class ASAP (ideally before any derived
+// classes) if the target class 'requires' the overrides. Without some special handling, the
+// overrides so required will be processed before the class and have to be bufferred even
+// in a build.
+//
+// TODO - we should probably support the "config" processor on an override (to config new
+// functionaliy like Aria) and maybe inheritableStatics (although static is now supported
+// by callSuper). If inheritableStatics causes those statics to be included on derived class
+// constructors, that probably means "no" to this since an override can come after other
+// classes extend the target.
+ return Manager.create(overrideName, {
+ requires: requires,
+ uses: uses,
+ isPartial: true,
+ constructor: function () {
+ //<debug error>
+ throw new Error("Cannot create override '" + overrideName + "'");
+ //</debug>
+ }
+ }, function () {
+ var cls = Manager.get(className);
+ if (cls.override) { // if (normal class)
+ cls.override(data);
+ } else { // else (singleton)
+ cls.self.override(data);
+ }
+
+ if (createdFn) {
+ // called once the override is applied and with the context of the
+ // overridden class (the override itself is a meaningless, name-only
+ // thing).
+ createdFn.call(cls);
+ }
+ });
+ },
/**
- * Convenient shorthand, see {@link Ext.ClassManager#getName}
+ * @method
* @member Ext
- * @method getClassName
+ * @alias Ext.ClassManager#getName
*/
getClassName: alias(Manager, 'getName'),
/**
- *
- * @param {Mixed} object
+ * Returns the displayName property or className or object.
+ * When all else fails, returns "Anonymous".
+ * @param {Object} object
+ * @return {String}
*/
getDisplayName: function(object) {
if (object.displayName) {
},
/**
- * Convenient shorthand, see {@link Ext.ClassManager#getClass}
+ * @method
* @member Ext
- * @method getClassName
+ * @alias Ext.ClassManager#getClass
*/
getClass: alias(Manager, 'getClass'),
/**
* Creates namespaces to be used for scoping variables and classes so that they are not global.
* Specifying the last node of a namespace implicitly creates all other nodes. Usage:
-
- Ext.namespace('Company', 'Company.data');
-
- // equivalent and preferable to the above syntax
- Ext.namespace('Company.data');
-
- Company.Widget = function() { ... };
-
- Company.data.CustomStore = function(config) { ... };
-
- * @param {String} namespace1
- * @param {String} namespace2
- * @param {String} etc
- * @return {Object} The namespace object. (If multiple arguments are passed, this will be the last namespace created)
- * @function
+ *
+ * Ext.namespace('Company', 'Company.data');
+ *
+ * // equivalent and preferable to the above syntax
+ * Ext.namespace('Company.data');
+ *
+ * Company.Widget = function() { ... };
+ *
+ * Company.data.CustomStore = function(config) { ... };
+ *
+ * @method
* @member Ext
- * @method namespace
- * @markdown
- */
- namespace: alias(Manager, 'createNamespaces')
- });
-
- Ext.createWidget = Ext.widget;
-
- /**
- * Convenient alias for {@link Ext#namespace Ext.namespace}
- * @member Ext
- * @method ns
- */
- Ext.ns = Ext.namespace;
-
- Class.registerPreprocessor('className', function(cls, data) {
- if (data.$className) {
- cls.$className = data.$className;
- //<debug>
- cls.displayName = cls.$className;
- //</debug>
- }
- }, true);
-
- Class.setDefaultPreprocessorPosition('className', 'first');
-
-})(Ext.Class, Ext.Function.alias);
-
-/**
- * @author Jacky Nguyen <jacky@sencha.com>
- * @docauthor Jacky Nguyen <jacky@sencha.com>
- * @class Ext.Loader
- *
-
-Ext.Loader is the heart of the new dynamic dependency loading capability in Ext JS 4+. It is most commonly used
-via the {@link Ext#require} shorthand. Ext.Loader supports both asynchronous and synchronous loading
-approaches, and leverage their advantages for the best development flow. We'll discuss about the pros and cons of each approach:
-
-# Asynchronous Loading #
-
-- Advantages:
- + Cross-domain
- + No web server needed: you can run the application via the file system protocol (i.e: `file://path/to/your/index
- .html`)
- + Best possible debugging experience: error messages come with the exact file name and line number
-
-- Disadvantages:
- + Dependencies need to be specified before-hand
-
-### Method 1: Explicitly include what you need: ###
-
- // Syntax
- Ext.require({String/Array} expressions);
-
- // Example: Single alias
- Ext.require('widget.window');
-
- // Example: Single class name
- Ext.require('Ext.window.Window');
-
- // Example: Multiple aliases / class names mix
- Ext.require(['widget.window', 'layout.border', 'Ext.data.Connection']);
-
- // Wildcards
- Ext.require(['widget.*', 'layout.*', 'Ext.data.*']);
-
-### Method 2: Explicitly exclude what you don't need: ###
-
- // Syntax: Note that it must be in this chaining format.
- Ext.exclude({String/Array} expressions)
- .require({String/Array} expressions);
-
- // Include everything except Ext.data.*
- Ext.exclude('Ext.data.*').require('*');Â
-
- // Include all widgets except widget.checkbox*,
- // which will match widget.checkbox, widget.checkboxfield, widget.checkboxgroup, etc.
- Ext.exclude('widget.checkbox*').require('widget.*');
-
-# Synchronous Loading on Demand #
-
-- *Advantages:*
- + There's no need to specify dependencies before-hand, which is always the convenience of including ext-all.js
- before
+ * @param {String} namespace1
+ * @param {String} namespace2
+ * @param {String} etc
+ * @return {Object} The namespace object. (If multiple arguments are passed, this will be the last namespace created)
+ */
+ namespace: alias(Manager, 'createNamespaces')
+ });
-- *Disadvantages:*
- + Not as good debugging experience since file name won't be shown (except in Firebug at the moment)
- + Must be from the same domain due to XHR restriction
- + Need a web server, same reason as above
+ /**
+ * Old name for {@link Ext#widget}.
+ * @deprecated 4.0.0 Use {@link Ext#widget} instead.
+ * @method
+ * @member Ext
+ * @alias Ext#widget
+ */
+ Ext.createWidget = Ext.widget;
-There's one simple rule to follow: Instantiate everything with Ext.create instead of the `new` keyword
+ /**
+ * Convenient alias for {@link Ext#namespace Ext.namespace}
+ * @method
+ * @member Ext
+ * @alias Ext#namespace
+ */
+ Ext.ns = Ext.namespace;
- Ext.create('widget.window', { ... }); // Instead of new Ext.window.Window({...});
+ Class.registerPreprocessor('className', function(cls, data) {
+ if (data.$className) {
+ cls.$className = data.$className;
+ //<debug>
+ cls.displayName = cls.$className;
+ //</debug>
+ }
+ }, true);
- Ext.create('Ext.window.Window', {}); // Same as above, using full class name instead of alias
+ Class.setDefaultPreprocessorPosition('className', 'first');
- Ext.widget('window', {}); // Same as above, all you need is the traditional `xtype`
+ Class.registerPreprocessor('xtype', function(cls, data) {
+ var xtypes = Ext.Array.from(data.xtype),
+ widgetPrefix = 'widget.',
+ aliases = Ext.Array.from(data.alias),
+ i, ln, xtype;
-Behind the scene, {@link Ext.ClassManager} will automatically check whether the given class name / alias has already
- existed on the page. If it's not, Ext.Loader will immediately switch itself to synchronous mode and automatic load the given
- class and all its dependencies.
+ data.xtype = xtypes[0];
+ data.xtypes = xtypes;
-# Hybrid Loading - The Best of Both Worlds #
+ aliases = data.alias = Ext.Array.from(data.alias);
-It has all the advantages combined from asynchronous and synchronous loading. The development flow is simple:
+ for (i = 0,ln = xtypes.length; i < ln; i++) {
+ xtype = xtypes[i];
-### Step 1: Start writing your application using synchronous approach. Ext.Loader will automatically fetch all
- dependencies on demand as they're needed during run-time. For example: ###
+ //<debug error>
+ if (typeof xtype != 'string' || xtype.length < 1) {
+ throw new Error("[Ext.define] Invalid xtype of: '" + xtype + "' for class: '" + name + "'; must be a valid non-empty string");
+ }
+ //</debug>
- Ext.onReady(function(){
- var window = Ext.createWidget('window', {
- width: 500,
- height: 300,
- layout: {
- type: 'border',
- padding: 5
- },
- title: 'Hello Dialog',
- items: [{
- title: 'Navigation',
- collapsible: true,
- region: 'west',
- width: 200,
- html: 'Hello',
- split: true
- }, {
- title: 'TabPanel',
- region: 'center'
- }]
- });
+ aliases.push(widgetPrefix + xtype);
+ }
- window.show();
- })
+ data.alias = aliases;
+ });
-### Step 2: Along the way, when you need better debugging ability, watch the console for warnings like these: ###
+ Class.setDefaultPreprocessorPosition('xtype', 'last');
- [Ext.Loader] Synchronously loading 'Ext.window.Window'; consider adding Ext.require('Ext.window.Window') before your application's code
- ClassManager.js:432
- [Ext.Loader] Synchronously loading 'Ext.layout.container.Border'; consider adding Ext.require('Ext.layout.container.Border') before your application's code
+ Class.registerPreprocessor('alias', function(cls, data) {
+ var aliases = Ext.Array.from(data.alias),
+ xtypes = Ext.Array.from(data.xtypes),
+ widgetPrefix = 'widget.',
+ widgetPrefixLength = widgetPrefix.length,
+ i, ln, alias, xtype;
-Simply copy and paste the suggested code above `Ext.onReady`, i.e:
+ for (i = 0, ln = aliases.length; i < ln; i++) {
+ alias = aliases[i];
- Ext.require('Ext.window.Window');
- Ext.require('Ext.layout.container.Border');
+ //<debug error>
+ if (typeof alias != 'string') {
+ throw new Error("[Ext.define] Invalid alias of: '" + alias + "' for class: '" + name + "'; must be a valid string");
+ }
+ //</debug>
- Ext.onReady(...);
+ if (alias.substring(0, widgetPrefixLength) === widgetPrefix) {
+ xtype = alias.substring(widgetPrefixLength);
+ Ext.Array.include(xtypes, xtype);
-Everything should now load via asynchronous mode.
+ if (!cls.xtype) {
+ cls.xtype = data.xtype = xtype;
+ }
+ }
+ }
-# Deployment #
+ data.alias = aliases;
+ data.xtypes = xtypes;
+ });
-It's important to note that dynamic loading should only be used during development on your local machines.
-During production, all dependencies should be combined into one single JavaScript file. Ext.Loader makes
-the whole process of transitioning from / to between development / maintenance and production as easy as
-possible. Internally {@link Ext.Loader#history Ext.Loader.history} maintains the list of all dependencies your application
-needs in the exact loading sequence. It's as simple as concatenating all files in this array into one,
-then include it on top of your application.
+ Class.setDefaultPreprocessorPosition('alias', 'last');
-This process will be automated with Sencha Command, to be released and documented towards Ext JS 4 Final.
+})(Ext.Class, Ext.Function.alias);
+/**
+ * @class Ext.Loader
* @singleton
- * @markdown
+ * @author Jacky Nguyen <jacky@sencha.com>
+ * @docauthor Jacky Nguyen <jacky@sencha.com>
+ *
+ * Ext.Loader is the heart of the new dynamic dependency loading capability in Ext JS 4+. It is most commonly used
+ * via the {@link Ext#require} shorthand. Ext.Loader supports both asynchronous and synchronous loading
+ * approaches, and leverage their advantages for the best development flow. We'll discuss about the pros and cons
+ * of each approach:
+ *
+ * # Asynchronous Loading
+ *
+ * - Advantages:
+ * + Cross-domain
+ * + No web server needed: you can run the application via the file system protocol
+ * (i.e: `file://path/to/your/index.html`)
+ * + Best possible debugging experience: error messages come with the exact file name and line number
+ *
+ * - Disadvantages:
+ * + Dependencies need to be specified before-hand
+ *
+ * ### Method 1: Explicitly include what you need:
+ *
+ * // Syntax
+ * Ext.require({String/Array} expressions);
+ *
+ * // Example: Single alias
+ * Ext.require('widget.window');
+ *
+ * // Example: Single class name
+ * Ext.require('Ext.window.Window');
+ *
+ * // Example: Multiple aliases / class names mix
+ * Ext.require(['widget.window', 'layout.border', 'Ext.data.Connection']);
+ *
+ * // Wildcards
+ * Ext.require(['widget.*', 'layout.*', 'Ext.data.*']);
+ *
+ * ### Method 2: Explicitly exclude what you don't need:
+ *
+ * // Syntax: Note that it must be in this chaining format.
+ * Ext.exclude({String/Array} expressions)
+ * .require({String/Array} expressions);
+ *
+ * // Include everything except Ext.data.*
+ * Ext.exclude('Ext.data.*').require('*');Â
+ *
+ * // Include all widgets except widget.checkbox*,
+ * // which will match widget.checkbox, widget.checkboxfield, widget.checkboxgroup, etc.
+ * Ext.exclude('widget.checkbox*').require('widget.*');
+ *
+ * # Synchronous Loading on Demand
+ *
+ * - Advantages:
+ * + There's no need to specify dependencies before-hand, which is always the convenience of including
+ * ext-all.js before
+ *
+ * - Disadvantages:
+ * + Not as good debugging experience since file name won't be shown (except in Firebug at the moment)
+ * + Must be from the same domain due to XHR restriction
+ * + Need a web server, same reason as above
+ *
+ * There's one simple rule to follow: Instantiate everything with Ext.create instead of the `new` keyword
+ *
+ * Ext.create('widget.window', { ... }); // Instead of new Ext.window.Window({...});
+ *
+ * Ext.create('Ext.window.Window', {}); // Same as above, using full class name instead of alias
+ *
+ * Ext.widget('window', {}); // Same as above, all you need is the traditional `xtype`
+ *
+ * Behind the scene, {@link Ext.ClassManager} will automatically check whether the given class name / alias has already
+ * existed on the page. If it's not, Ext.Loader will immediately switch itself to synchronous mode and automatic load
+ * the given class and all its dependencies.
+ *
+ * # Hybrid Loading - The Best of Both Worlds
+ *
+ * It has all the advantages combined from asynchronous and synchronous loading. The development flow is simple:
+ *
+ * ### Step 1: Start writing your application using synchronous approach.
+ *
+ * Ext.Loader will automatically fetch all dependencies on demand as they're needed during run-time. For example:
+ *
+ * Ext.onReady(function(){
+ * var window = Ext.createWidget('window', {
+ * width: 500,
+ * height: 300,
+ * layout: {
+ * type: 'border',
+ * padding: 5
+ * },
+ * title: 'Hello Dialog',
+ * items: [{
+ * title: 'Navigation',
+ * collapsible: true,
+ * region: 'west',
+ * width: 200,
+ * html: 'Hello',
+ * split: true
+ * }, {
+ * title: 'TabPanel',
+ * region: 'center'
+ * }]
+ * });
+ *
+ * window.show();
+ * })
+ *
+ * ### Step 2: Along the way, when you need better debugging ability, watch the console for warnings like these:
+ *
+ * [Ext.Loader] Synchronously loading 'Ext.window.Window'; consider adding Ext.require('Ext.window.Window') before your application's code ClassManager.js:432
+ * [Ext.Loader] Synchronously loading 'Ext.layout.container.Border'; consider adding Ext.require('Ext.layout.container.Border') before your application's code
+ *
+ * Simply copy and paste the suggested code above `Ext.onReady`, e.g.:
+ *
+ * Ext.require('Ext.window.Window');
+ * Ext.require('Ext.layout.container.Border');
+ *
+ * Ext.onReady(...);
+ *
+ * Everything should now load via asynchronous mode.
+ *
+ * # Deployment
+ *
+ * It's important to note that dynamic loading should only be used during development on your local machines.
+ * During production, all dependencies should be combined into one single JavaScript file. Ext.Loader makes
+ * the whole process of transitioning from / to between development / maintenance and production as easy as
+ * possible. Internally {@link Ext.Loader#history Ext.Loader.history} maintains the list of all dependencies
+ * your application needs in the exact loading sequence. It's as simple as concatenating all files in this
+ * array into one, then include it on top of your application.
+ *
+ * This process will be automated with Sencha Command, to be released and documented towards Ext JS 4 Final.
*/
-
(function(Manager, Class, flexSetter, alias) {
var
classNameToFilePathMap: {},
/**
+ * @property {String[]} history
* An array of class names to keep track of the dependency loading order.
- * This is not guaranteed to be the same everytime due to the asynchronous
- * nature of the Loader.
- *
- * @property history
- * @type Array
+ * This is not guaranteed to be the same everytime due to the asynchronous nature of the Loader.
*/
history: [],
*/
config: {
/**
- * Whether or not to enable the dynamic dependency loading feature
- * Defaults to false
* @cfg {Boolean} enabled
+ * Whether or not to enable the dynamic dependency loading feature.
*/
enabled: false,
/**
* @cfg {Boolean} disableCaching
- * Appends current timestamp to script files to prevent caching
- * Defaults to true
+ * Appends current timestamp to script files to prevent caching.
*/
disableCaching: true,
/**
* @cfg {String} disableCachingParam
* The get parameter name for the cache buster's timestamp.
- * Defaults to '_dc'
*/
disableCachingParam: '_dc',
/**
* @cfg {Object} paths
* The mapping from namespaces to file paths
- {
- 'Ext': '.', // This is set by default, Ext.layout.container.Container will be
- // loaded from ./layout/Container.js
-
- 'My': './src/my_own_folder' // My.layout.Container will be loaded from
- // ./src/my_own_folder/layout/Container.js
- }
+ *
+ * {
+ * 'Ext': '.', // This is set by default, Ext.layout.container.Container will be
+ * // loaded from ./layout/Container.js
+ *
+ * 'My': './src/my_own_folder' // My.layout.Container will be loaded from
+ * // ./src/my_own_folder/layout/Container.js
+ * }
+ *
* Note that all relative paths are relative to the current HTML document.
- * If not being specified, for example, <code>Other.awesome.Class</code>
- * will simply be loaded from <code>./Other/awesome/Class.js</code>
+ * If not being specified, for example, `Other.awesome.Class`
+ * will simply be loaded from `./Other/awesome/Class.js`
*/
paths: {
'Ext': '.'
/**
* Set the configuration for the loader. This should be called right after ext-core.js
- * (or ext-core-debug.js) is included in the page, i.e:
-
- <script type="text/javascript" src="ext-core-debug.js"></script>
- <script type="text/javascript">
- Ext.Loader.setConfig({
- enabled: true,
- paths: {
- 'My': 'my_own_path'
- }
- });
- <script>
- <script type="text/javascript">
- Ext.require(...);
-
- Ext.onReady(function() {
- // application code here
- });
- </script>
-
- * Refer to {@link Ext.Loader#configs} for the list of possible properties
- *
- * @param {Object} config The config object to override the default values in {@link Ext.Loader#config}
+ * (or ext-core-debug.js) is included in the page, e.g.:
+ *
+ * <script type="text/javascript" src="ext-core-debug.js"></script>
+ * <script type="text/javascript">
+ * Ext.Loader.setConfig({
+ * enabled: true,
+ * paths: {
+ * 'My': 'my_own_path'
+ * }
+ * });
+ * <script>
+ * <script type="text/javascript">
+ * Ext.require(...);
+ *
+ * Ext.onReady(function() {
+ * // application code here
+ * });
+ * </script>
+ *
+ * Refer to config options of {@link Ext.Loader} for the list of possible properties.
+ *
+ * @param {String/Object} name Name of the value to override, or a config object to override multiple values.
+ * @param {Object} value (optional) The new value to set, needed if first parameter is String.
* @return {Ext.Loader} this
- * @markdown
*/
setConfig: function(name, value) {
if (Ext.isObject(name) && arguments.length === 1) {
},
/**
- * Get the config value corresponding to the specified name. If no name is given, will return the config object
+ * Get the config value corresponding to the specified name.
+ * If no name is given, will return the config object.
* @param {String} name The config property name
- * @return {Object/Mixed}
+ * @return {Object}
*/
getConfig: function(name) {
if (name) {
},
/**
- * Sets the path of a namespace.
- * For Example:
-
- Ext.Loader.setPath('Ext', '.');
-
+ * Sets the path of a namespace. For Example:
+ *
+ * Ext.Loader.setPath('Ext', '.');
+ *
* @param {String/Object} name See {@link Ext.Function#flexSetter flexSetter}
* @param {String} path See {@link Ext.Function#flexSetter flexSetter}
* @return {Ext.Loader} this
- * @markdown
+ * @method
*/
setPath: flexSetter(function(name, path) {
//<if nonBrowser>
}),
/**
- * Translates a className to a file path by adding the
- * the proper prefix and converting the .'s to /'s. For example:
-
- Ext.Loader.setPath('My', '/path/to/My');
-
- alert(Ext.Loader.getPath('My.awesome.Class')); // alerts '/path/to/My/awesome/Class.js'
-
+ * Translates a className to a file path by adding the the proper prefix and converting the .'s to /'s.
+ * For example:
+ *
+ * Ext.Loader.setPath('My', '/path/to/My');
+ *
+ * alert(Ext.Loader.getPath('My.awesome.Class')); // alerts '/path/to/My/awesome/Class.js'
+ *
* Note that the deeper namespace levels, if explicitly set, are always resolved first. For example:
-
- Ext.Loader.setPath({
- 'My': '/path/to/lib',
- 'My.awesome': '/other/path/for/awesome/stuff',
- 'My.awesome.more': '/more/awesome/path'
- });
-
- alert(Ext.Loader.getPath('My.awesome.Class')); // alerts '/other/path/for/awesome/stuff/Class.js'
-
- alert(Ext.Loader.getPath('My.awesome.more.Class')); // alerts '/more/awesome/path/Class.js'
-
- alert(Ext.Loader.getPath('My.cool.Class')); // alerts '/path/to/lib/cool/Class.js'
-
- alert(Ext.Loader.getPath('Unknown.strange.Stuff')); // alerts 'Unknown/strange/Stuff.js'
-
+ *
+ * Ext.Loader.setPath({
+ * 'My': '/path/to/lib',
+ * 'My.awesome': '/other/path/for/awesome/stuff',
+ * 'My.awesome.more': '/more/awesome/path'
+ * });
+ *
+ * alert(Ext.Loader.getPath('My.awesome.Class')); // alerts '/other/path/for/awesome/stuff/Class.js'
+ *
+ * alert(Ext.Loader.getPath('My.awesome.more.Class')); // alerts '/more/awesome/path/Class.js'
+ *
+ * alert(Ext.Loader.getPath('My.cool.Class')); // alerts '/path/to/lib/cool/Class.js'
+ *
+ * alert(Ext.Loader.getPath('Unknown.strange.Stuff')); // alerts 'Unknown/strange/Stuff.js'
+ *
* @param {String} className
* @return {String} path
- * @markdown
*/
getPath: function(className) {
var path = '',
do {
if (Manager.isCreated(requires[j])) {
// Take out from the queue
- requires.splice(j, 1);
+ Ext.Array.erase(requires, j, 1);
}
else {
j++;
} while (j < requires.length);
if (item.requires.length === 0) {
- this.queue.splice(i, 1);
+ Ext.Array.erase(this.queue, i, 1);
item.callback.call(item.scope);
this.refreshQueue();
break;
*
* @param {String} url
* @param {Function} onLoad
- * @param {Scope} scope
+ * @param {Object} scope
* @param {Boolean} synchronous
* @private
*/
/**
* Explicitly exclude files from being loaded. Useful when used in conjunction with a broad include expression.
- * Can be chained with more `require` and `exclude` methods, eg:
-
- Ext.exclude('Ext.data.*').require('*');
-
- Ext.exclude('widget.button*').require('widget.*');
-
- * @param {Array} excludes
+ * Can be chained with more `require` and `exclude` methods, e.g.:
+ *
+ * Ext.exclude('Ext.data.*').require('*');
+ *
+ * Ext.exclude('widget.button*').require('widget.*');
+ *
+ * {@link Ext#exclude Ext.exclude} is alias for {@link Ext.Loader#exclude Ext.Loader.exclude} for convenience.
+ *
+ * @param {String/String[]} excludes
* @return {Object} object contains `require` method for chaining
- * @markdown
*/
exclude: function(excludes) {
var me = this;
},
/**
- * Synchronously loads all classes by the given names and all their direct dependencies; optionally executes the given callback function when finishes, within the optional scope. This method is aliased by {@link Ext#syncRequire} for convenience
- * @param {String/Array} expressions Can either be a string or an array of string
+ * Synchronously loads all classes by the given names and all their direct dependencies;
+ * optionally executes the given callback function when finishes, within the optional scope.
+ *
+ * {@link Ext#syncRequire Ext.syncRequire} is alias for {@link Ext.Loader#syncRequire Ext.Loader.syncRequire} for convenience.
+ *
+ * @param {String/String[]} expressions Can either be a string or an array of string
* @param {Function} fn (Optional) The callback function
* @param {Object} scope (Optional) The execution scope (`this`) of the callback function
- * @param {String/Array} excludes (Optional) Classes to be excluded, useful when being used with expressions
- * @markdown
+ * @param {String/String[]} excludes (Optional) Classes to be excluded, useful when being used with expressions
*/
syncRequire: function() {
this.syncModeEnabled = true;
},
/**
- * Loads all classes by the given names and all their direct dependencies; optionally executes the given callback function when
- * finishes, within the optional scope. This method is aliased by {@link Ext#require Ext.require} for convenience
- * @param {String/Array} expressions Can either be a string or an array of string
+ * Loads all classes by the given names and all their direct dependencies;
+ * optionally executes the given callback function when finishes, within the optional scope.
+ *
+ * {@link Ext#require Ext.require} is alias for {@link Ext.Loader#require Ext.Loader.require} for convenience.
+ *
+ * @param {String/String[]} expressions Can either be a string or an array of string
* @param {Function} fn (Optional) The callback function
* @param {Object} scope (Optional) The execution scope (`this`) of the callback function
- * @param {String/Array} excludes (Optional) Classes to be excluded, useful when being used with expressions
- * @markdown
+ * @param {String/String[]} excludes (Optional) Classes to be excluded, useful when being used with expressions
*/
require: function(expressions, fn, scope, excludes) {
var filePath, expression, exclude, className, excluded = {},
},
/**
- * Add a new listener to be executed when all required scripts are fully loaded
+ * Adds new listener to be executed when all required scripts are fully loaded.
*
* @param {Function} fn The function callback to be executed
- * @param {Object} scope The execution scope (<code>this</code>) of the callback function
+ * @param {Object} scope The execution scope (`this`) of the callback function
* @param {Boolean} withDomReady Whether or not to wait for document dom ready as well
*/
onReady: function(fn, scope, withDomReady, options) {
};
/**
- * Convenient alias of {@link Ext.Loader#require}. Please see the introduction documentation of
- * {@link Ext.Loader} for examples.
* @member Ext
* @method require
+ * @alias Ext.Loader#require
*/
Ext.require = alias(Loader, 'require');
/**
- * Synchronous version of {@link Ext#require}, convenient alias of {@link Ext.Loader#syncRequire}.
- *
* @member Ext
* @method syncRequire
+ * @alias Ext.Loader#syncRequire
*/
Ext.syncRequire = alias(Loader, 'syncRequire');
/**
- * Convenient shortcut to {@link Ext.Loader#exclude}
* @member Ext
* @method exclude
+ * @alias Ext.Loader#exclude
*/
Ext.exclude = alias(Loader, 'exclude');
/**
* @member Ext
* @method onReady
+ * @alias Ext.Loader#onReady
*/
Ext.onReady = function(fn, scope, options) {
Loader.onReady(fn, scope, true, options);
};
+ /**
+ * @cfg {String[]} requires
+ * @member Ext.Class
+ * List of classes that have to be loaded before instantiating this class.
+ * For example:
+ *
+ * Ext.define('Mother', {
+ * requires: ['Child'],
+ * giveBirth: function() {
+ * // we can be sure that child class is available.
+ * return new Child();
+ * }
+ * });
+ */
Class.registerPreprocessor('loader', function(cls, data, continueFn) {
var me = this,
dependencies = [],
}
}
}
- else {
+ else if (typeof propertyValue != 'function') {
for (j in propertyValue) {
if (propertyValue.hasOwnProperty(j)) {
value = propertyValue[j];
}
}
}
- else {
+ else if (typeof propertyValue != 'function') {
for (var k in propertyValue) {
if (propertyValue.hasOwnProperty(k)) {
value = propertyValue[k];
Class.setDefaultPreprocessorPosition('loader', 'after', 'className');
+ /**
+ * @cfg {String[]} uses
+ * @member Ext.Class
+ * List of classes to load together with this class. These aren't neccessarily loaded before
+ * this class is instantiated. For example:
+ *
+ * Ext.define('Mother', {
+ * uses: ['Child'],
+ * giveBirth: function() {
+ * // This code might, or might not work:
+ * // return new Child();
+ *
+ * // Instead use Ext.create() to load the class at the spot if not loaded already:
+ * return Ext.create('Child');
+ * }
+ * });
+ */
Manager.registerPostprocessor('uses', function(name, cls, data) {
var uses = Ext.Array.from(data.uses),
items = [],
})(Ext.ClassManager, Ext.Class, Ext.Function.flexSetter, Ext.Function.alias);
/**
- * @class Ext.Error
- * @private
- * @extends Error
-
-A wrapper class for the native JavaScript Error object that adds a few useful capabilities for handling
-errors in an Ext application. When you use Ext.Error to {@link #raise} an error from within any class that
-uses the Ext 4 class system, the Error class can automatically add the source class and method from which
-the error was raised. It also includes logic to automatically log the eroor to the console, if available,
-with additional metadata about the error. In all cases, the error will always be thrown at the end so that
-execution will halt.
-
-Ext.Error also offers a global error {@link #handle handling} method that can be overridden in order to
-handle application-wide errors in a single spot. You can optionally {@link #ignore} errors altogether,
-although in a real application it's usually a better idea to override the handling function and perform
-logging or some other method of reporting the errors in a way that is meaningful to the application.
-
-At its simplest you can simply raise an error as a simple string from within any code:
-
-#Example usage:#
-
- Ext.Error.raise('Something bad happened!');
-
-If raised from plain JavaScript code, the error will be logged to the console (if available) and the message
-displayed. In most cases however you'll be raising errors from within a class, and it may often be useful to add
-additional metadata about the error being raised. The {@link #raise} method can also take a config object.
-In this form the `msg` attribute becomes the error description, and any other data added to the config gets
-added to the error object and, if the console is available, logged to the console for inspection.
-
-#Example usage:#
-
- Ext.define('Ext.Foo', {
- doSomething: function(option){
- if (someCondition === false) {
- Ext.Error.raise({
- msg: 'You cannot do that!',
- option: option, // whatever was passed into the method
- 'error code': 100 // other arbitrary info
- });
- }
- }
- });
-
-If a console is available (that supports the `console.dir` function) you'll see console output like:
-
- An error was raised with the following data:
- option: Object { foo: "bar"}
- foo: "bar"
- error code: 100
- msg: "You cannot do that!"
- sourceClass: "Ext.Foo"
- sourceMethod: "doSomething"
-
- uncaught exception: You cannot do that!
-
-As you can see, the error will report exactly where it was raised and will include as much information as the
-raising code can usefully provide.
-
-If you want to handle all application errors globally you can simply override the static {@link handle} method
-and provide whatever handling logic you need. If the method returns true then the error is considered handled
-and will not be thrown to the browser. If anything but true is returned then the error will be thrown normally.
-
-#Example usage:#
-
- Ext.Error.handle = function(err) {
- if (err.someProperty == 'NotReallyAnError') {
- // maybe log something to the application here if applicable
- return true;
- }
- // any non-true return value (including none) will cause the error to be thrown
- }
-
- * Create a new Error object
- * @param {Object} config The config object
- * @markdown
* @author Brian Moeskau <brian@sencha.com>
* @docauthor Brian Moeskau <brian@sencha.com>
+ *
+ * A wrapper class for the native JavaScript Error object that adds a few useful capabilities for handling
+ * errors in an Ext application. When you use Ext.Error to {@link #raise} an error from within any class that
+ * uses the Ext 4 class system, the Error class can automatically add the source class and method from which
+ * the error was raised. It also includes logic to automatically log the eroor to the console, if available,
+ * with additional metadata about the error. In all cases, the error will always be thrown at the end so that
+ * execution will halt.
+ *
+ * Ext.Error also offers a global error {@link #handle handling} method that can be overridden in order to
+ * handle application-wide errors in a single spot. You can optionally {@link #ignore} errors altogether,
+ * although in a real application it's usually a better idea to override the handling function and perform
+ * logging or some other method of reporting the errors in a way that is meaningful to the application.
+ *
+ * At its simplest you can simply raise an error as a simple string from within any code:
+ *
+ * Example usage:
+ *
+ * Ext.Error.raise('Something bad happened!');
+ *
+ * If raised from plain JavaScript code, the error will be logged to the console (if available) and the message
+ * displayed. In most cases however you'll be raising errors from within a class, and it may often be useful to add
+ * additional metadata about the error being raised. The {@link #raise} method can also take a config object.
+ * In this form the `msg` attribute becomes the error description, and any other data added to the config gets
+ * added to the error object and, if the console is available, logged to the console for inspection.
+ *
+ * Example usage:
+ *
+ * Ext.define('Ext.Foo', {
+ * doSomething: function(option){
+ * if (someCondition === false) {
+ * Ext.Error.raise({
+ * msg: 'You cannot do that!',
+ * option: option, // whatever was passed into the method
+ * 'error code': 100 // other arbitrary info
+ * });
+ * }
+ * }
+ * });
+ *
+ * If a console is available (that supports the `console.dir` function) you'll see console output like:
+ *
+ * An error was raised with the following data:
+ * option: Object { foo: "bar"}
+ * foo: "bar"
+ * error code: 100
+ * msg: "You cannot do that!"
+ * sourceClass: "Ext.Foo"
+ * sourceMethod: "doSomething"
+ *
+ * uncaught exception: You cannot do that!
+ *
+ * As you can see, the error will report exactly where it was raised and will include as much information as the
+ * raising code can usefully provide.
+ *
+ * If you want to handle all application errors globally you can simply override the static {@link #handle} method
+ * and provide whatever handling logic you need. If the method returns true then the error is considered handled
+ * and will not be thrown to the browser. If anything but true is returned then the error will be thrown normally.
+ *
+ * Example usage:
+ *
+ * Ext.Error.handle = function(err) {
+ * if (err.someProperty == 'NotReallyAnError') {
+ * // maybe log something to the application here if applicable
+ * return true;
+ * }
+ * // any non-true return value (including none) will cause the error to be thrown
+ * }
+ *
*/
Ext.Error = Ext.extend(Error, {
statics: {
/**
- * @property ignore
-Static flag that can be used to globally disable error reporting to the browser if set to true
-(defaults to false). Note that if you ignore Ext errors it's likely that some other code may fail
-and throw a native JavaScript error thereafter, so use with caution. In most cases it will probably
-be preferable to supply a custom error {@link #handle handling} function instead.
-
-#Example usage:#
-
- Ext.Error.ignore = true;
-
- * @markdown
+ * @property {Boolean} ignore
+ * Static flag that can be used to globally disable error reporting to the browser if set to true
+ * (defaults to false). Note that if you ignore Ext errors it's likely that some other code may fail
+ * and throw a native JavaScript error thereafter, so use with caution. In most cases it will probably
+ * be preferable to supply a custom error {@link #handle handling} function instead.
+ *
+ * Example usage:
+ *
+ * Ext.Error.ignore = true;
+ *
* @static
*/
ignore: false,
/**
-Raise an error that can include additional data and supports automatic console logging if available.
-You can pass a string error message or an object with the `msg` attribute which will be used as the
-error message. The object can contain any other name-value attributes (or objects) to be logged
-along with the error.
-
-Note that after displaying the error message a JavaScript error will ultimately be thrown so that
-execution will halt.
-
-#Example usage:#
-
- Ext.Error.raise('A simple string error message');
-
- // or...
+ * @property {Boolean} notify
+ * Static flag that can be used to globally control error notification to the user. Unlike
+ * Ex.Error.ignore, this does not effect exceptions. They are still thrown. This value can be
+ * set to false to disable the alert notification (default is true for IE6 and IE7).
+ *
+ * Only the first error will generate an alert. Internally this flag is set to false when the
+ * first error occurs prior to displaying the alert.
+ *
+ * This flag is not used in a release build.
+ *
+ * Example usage:
+ *
+ * Ext.Error.notify = false;
+ *
+ * @static
+ */
+ //notify: Ext.isIE6 || Ext.isIE7,
- Ext.define('Ext.Foo', {
- doSomething: function(option){
- if (someCondition === false) {
- Ext.Error.raise({
- msg: 'You cannot do that!',
- option: option, // whatever was passed into the method
- 'error code': 100 // other arbitrary info
- });
- }
- }
- });
- * @param {String/Object} err The error message string, or an object containing the
- * attribute "msg" that will be used as the error message. Any other data included in
- * the object will also be logged to the browser console, if available.
+ /**
+ * Raise an error that can include additional data and supports automatic console logging if available.
+ * You can pass a string error message or an object with the `msg` attribute which will be used as the
+ * error message. The object can contain any other name-value attributes (or objects) to be logged
+ * along with the error.
+ *
+ * Note that after displaying the error message a JavaScript error will ultimately be thrown so that
+ * execution will halt.
+ *
+ * Example usage:
+ *
+ * Ext.Error.raise('A simple string error message');
+ *
+ * // or...
+ *
+ * Ext.define('Ext.Foo', {
+ * doSomething: function(option){
+ * if (someCondition === false) {
+ * Ext.Error.raise({
+ * msg: 'You cannot do that!',
+ * option: option, // whatever was passed into the method
+ * 'error code': 100 // other arbitrary info
+ * });
+ * }
+ * }
+ * });
+ *
+ * @param {String/Object} err The error message string, or an object containing the attribute "msg" that will be
+ * used as the error message. Any other data included in the object will also be logged to the browser console,
+ * if available.
* @static
- * @markdown
*/
raise: function(err){
err = err || {};
}
if (Ext.Error.handle(err) !== true) {
- var global = Ext.global,
- con = global.console,
- msg = Ext.Error.prototype.toString.call(err),
- noConsoleMsg = 'An uncaught error was raised: "' + msg +
- '". Use Firebug or Webkit console for additional details.';
-
- if (con) {
- if (con.dir) {
- con.warn('An uncaught error was raised with the following data:');
- con.dir(err);
- }
- else {
- con.warn(noConsoleMsg);
- }
- if (con.error) {
- con.error(msg);
- }
- }
- else if (global.alert){
- global.alert(noConsoleMsg);
- }
-
+ var msg = Ext.Error.prototype.toString.call(err);
+
+ Ext.log({
+ msg: msg,
+ level: 'error',
+ dump: err,
+ stack: true
+ });
+
throw new Ext.Error(err);
}
},
/**
-Globally handle any Ext errors that may be raised, optionally providing custom logic to
-handle different errors individually. Return true from the function to bypass throwing the
-error to the browser, otherwise the error will be thrown and execution will halt.
-
-#Example usage:#
-
- Ext.Error.handle = function(err) {
- if (err.someProperty == 'NotReallyAnError') {
- // maybe log something to the application here if applicable
- return true;
- }
- // any non-true return value (including none) will cause the error to be thrown
- }
-
- * @param {Ext.Error} err The Ext.Error object being raised. It will contain any attributes
- * that were originally raised with it, plus properties about the method and class from which
- * the error originated (if raised from a class that uses the Ext 4 class system).
+ * Globally handle any Ext errors that may be raised, optionally providing custom logic to
+ * handle different errors individually. Return true from the function to bypass throwing the
+ * error to the browser, otherwise the error will be thrown and execution will halt.
+ *
+ * Example usage:
+ *
+ * Ext.Error.handle = function(err) {
+ * if (err.someProperty == 'NotReallyAnError') {
+ * // maybe log something to the application here if applicable
+ * return true;
+ * }
+ * // any non-true return value (including none) will cause the error to be thrown
+ * }
+ *
+ * @param {Ext.Error} err The Ext.Error object being raised. It will contain any attributes that were originally
+ * raised with it, plus properties about the method and class from which the error originated (if raised from a
+ * class that uses the Ext 4 class system).
* @static
- * @markdown
*/
handle: function(){
return Ext.Error.ignore;
}
},
+ // This is the standard property that is the name of the constructor.
+ name: 'Ext.Error',
+
/**
- * @constructor
- * @param {String/Object} config The error message string, or an object containing the
+ * Creates new Error object.
+ * @param {String/Object} config The error message string, or an object containing the
* attribute "msg" that will be used as the error message. Any other data included in
* the object will be applied to the error instance and logged to the browser console, if available.
*/
if (Ext.isString(config)) {
config = { msg: config };
}
- Ext.apply(this, config);
+
+ var me = this;
+
+ Ext.apply(me, config);
+
+ me.message = me.message || me.msg; // 'message' is standard ('msg' is non-standard)
+ // note: the above does not work in old WebKit (me.message is readonly) (Safari 4)
},
/**
-Provides a custom string representation of the error object. This is an override of the base JavaScript
-`Object.toString` method, which is useful so that when logged to the browser console, an error object will
-be displayed with a useful message instead of `[object Object]`, the default `toString` result.
-
-The default implementation will include the error message along with the raising class and method, if available,
-but this can be overridden with a custom implementation either at the prototype level (for all errors) or on
-a particular error instance, if you want to provide a custom description that will show up in the console.
- * @markdown
- * @return {String} The error message. If raised from within the Ext 4 class system, the error message
- * will also include the raising class and method names, if available.
+ * Provides a custom string representation of the error object. This is an override of the base JavaScript
+ * `Object.toString` method, which is useful so that when logged to the browser console, an error object will
+ * be displayed with a useful message instead of `[object Object]`, the default `toString` result.
+ *
+ * The default implementation will include the error message along with the raising class and method, if available,
+ * but this can be overridden with a custom implementation either at the prototype level (for all errors) or on
+ * a particular error instance, if you want to provide a custom description that will show up in the console.
+ * @return {String} The error message. If raised from within the Ext 4 class system, the error message will also
+ * include the raising class and method names, if available.
*/
toString: function(){
var me = this,
}
});
+/*
+ * This mechanism is used to notify the user of the first error encountered on the page. This
+ * was previously internal to Ext.Error.raise and is a desirable feature since errors often
+ * slip silently under the radar. It cannot live in Ext.Error.raise since there are times
+ * where exceptions are handled in a try/catch.
+ */
+//<debug>
+(function () {
+ var prevOnError, timer, errors = 0,
+ extraordinarilyBad = /(out of stack)|(too much recursion)|(stack overflow)|(out of memory)/i,
+ win = Ext.global;
+
+ if (typeof window === 'undefined') {
+ return; // build system or some such environment...
+ }
+
+ // This method is called to notify the user of the current error status.
+ function notify () {
+ var counters = Ext.log.counters,
+ supports = Ext.supports,
+ hasOnError = supports && supports.WindowOnError; // TODO - timing
+
+ // Put log counters to the status bar (for most browsers):
+ if (counters && (counters.error + counters.warn + counters.info + counters.log)) {
+ var msg = [ 'Logged Errors:',counters.error, 'Warnings:',counters.warn,
+ 'Info:',counters.info, 'Log:',counters.log].join(' ');
+ if (errors) {
+ msg = '*** Errors: ' + errors + ' - ' + msg;
+ } else if (counters.error) {
+ msg = '*** ' + msg;
+ }
+ win.status = msg;
+ }
+
+ // Display an alert on the first error:
+ if (!Ext.isDefined(Ext.Error.notify)) {
+ Ext.Error.notify = Ext.isIE6 || Ext.isIE7; // TODO - timing
+ }
+ if (Ext.Error.notify && (hasOnError ? errors : (counters && counters.error))) {
+ Ext.Error.notify = false;
+
+ if (timer) {
+ win.clearInterval(timer); // ticks can queue up so stop...
+ timer = null;
+ }
+
+ alert('Unhandled error on page: See console or log');
+ poll();
+ }
+ }
+
+ // Sets up polling loop. This is the only way to know about errors in some browsers
+ // (Opera/Safari) and is the only way to update the status bar for warnings and other
+ // non-errors.
+ function poll () {
+ timer = win.setInterval(notify, 1000);
+ }
+
+ // window.onerror sounds ideal but it prevents the built-in error dialog from doing
+ // its (better) thing.
+ poll();
+})();
+//</debug>
+
+
git.ithinksw.org / extjs.git / blobdiff