Hopiu/angular.js
1
0
Fork 0
mirror of https://github.com/Hopiu/angular.js.git synced 2026-04-30 03:14:48 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

doc(API): various API documentation improvements

Browse source
This commit is contained in:
Toni Thompson 2011-08-18 17:41:57 -07:00 committed by Vojta Jina
parent e3fad0feb3
commit 446f6b233f
3 changed files with 221 additions and 179 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

123
src/Angular.js
View file

@ -44,8 +44,8 @@ var manualUppercase = function (s) {
// String#toLowerCase and String#toUpperCase don't produce correct results in browsers with Turkish // String#toLowerCase and String#toUpperCase don't produce correct results in browsers with Turkish
// locale, for this reason we need to detect this case and redefine lowercase/uppercase methods with // locale, for this reason we need to detect this case and redefine lowercase/uppercase methods
// correct but slower alternatives. // with correct but slower alternatives.
if ('i' !== 'I'.toLowerCase()) { if ('i' !== 'I'.toLowerCase()) {
lowercase = manualLowercase; lowercase = manualLowercase;
uppercase = manualUppercase; uppercase = manualUppercase;
@ -118,10 +118,11 @@ var _undefined = undefined,
* @function * @function
* *
* @description * @description
* Invokes the `iterator` function once for each item in `obj` collection. The collection can either * Invokes the `iterator` function once for each item in `obj` collection. The collection can
* be an object or an array. The `iterator` function is invoked with `iterator(value, key)`, where * either be an object or an array. The `iterator` function is invoked with `iterator(value, key)`,
* `value` is the value of an object property or an array element and `key` is the object property * where `value` is the value of an object property or an array element and `key` is the object
* key or array element index. Optionally, `context` can be specified for the iterator function. * property key or array element index. Optionally, `context` can be specified for the iterator
* function.
* *
* Note: this function was previously known as `angular.foreach`. * Note: this function was previously known as `angular.foreach`.
* *
@ -222,8 +223,8 @@ function nextUid() {
* @function * @function
* *
* @description * @description
* Extends the destination object `dst` by copying all of the properties from the `src` object(s) to * Extends the destination object `dst` by copying all of the properties from the `src` object(s)
* `dst`. You can specify multiple `src` objects. * to `dst`. You can specify multiple `src` objects.
* *
* @param {Object} dst The destination object. * @param {Object} dst The destination object.
* @param {...Object} src The source object(s). * @param {...Object} src The source object(s).
@ -428,9 +429,13 @@ function isWindow(obj) {
return obj && obj.document && obj.location && obj.alert && obj.setInterval; return obj && obj.document && obj.location && obj.alert && obj.setInterval;
} }
function isBoolean(value) { return typeof value == $boolean;} function isBoolean(value) { return typeof value == $boolean; }
function isTextNode(node) { return nodeName_(node) == '#text'; } function isTextNode(node) { return nodeName_(node) == '#text'; }
function trim(value) { return isString(value) ? value.replace(/^\s*/, '').replace(/\s*$/, '') : value; }
function trim(value) {
return isString(value) ? value.replace(/^\s*/, '').replace(/\s*$/, '') : value;
}
function isElement(node) { function isElement(node) {
return node && return node &&
(node.nodeName // we are a direct element (node.nodeName // we are a direct element
@ -451,10 +456,12 @@ function makeMap(str){
/** /**
* HTML class which is the only class which can be used in ng:bind to inline HTML for security reasons. * HTML class which is the only class which can be used in ng:bind to inline HTML for security
* reasons.
*
* @constructor * @constructor
* @param html raw (unsafe) html * @param html raw (unsafe) html
* @param {string=} option if set to 'usafe' then get method will return raw (unsafe/unsanitized) html * @param {string=} option If set to 'usafe', get method will return raw (unsafe/unsanitized) html
*/ */
function HTML(html, option) { function HTML(html, option) {
this.html = html; this.html = html;
@ -470,7 +477,8 @@ function HTML(html, option) {
if (msie < 9) { if (msie < 9) {
nodeName_ = function(element) { nodeName_ = function(element) {
element = element.nodeName ? element : element[0]; element = element.nodeName ? element : element[0];
return (element.scopeName && element.scopeName != 'HTML' ) ? uppercase(element.scopeName + ':' + element.nodeName) : element.nodeName; return (element.scopeName && element.scopeName != 'HTML')
? uppercase(element.scopeName + ':' + element.nodeName) : element.nodeName;
}; };
} else { } else {
nodeName_ = function(element) { nodeName_ = function(element) {
@ -500,26 +508,35 @@ function map(obj, iterator, context) {
* @function * @function
* *
* @description * @description
* Determines the number of elements in an array, number of properties of an object or string * Determines the number of elements in an array, the number of properties an object has, or
* length. * the length of a string.
* *
* Note: this function is used to augment the Object type in angular expressions. See * Note: This function is used to augment the Object type in Angular expressions. See
* {@link angular.Object} for more info. * {@link angular.Object} for more information about Angular arrays.
* *
* @param {Object|Array|string} obj Object, array or string to inspect. * @param {Object|Array|string} obj Object, array, or string to inspect.
* @param {boolean} [ownPropsOnly=false] Count only "own" properties in an object * @param {boolean} [ownPropsOnly=false] Count only "own" properties in an object
* @returns {number} The size of `obj` or `0` if `obj` is neither an object or an array. * @returns {number} The size of `obj` or `0` if `obj` is neither an object or an array.
* *
* @example * @example
* <doc:example> * <doc:example>
* <doc:source> * <doc:source>
* Number of items in array: {{ [1,2].$size() }}<br/> * <script>
* Number of items in object: {{ {a:1, b:2, c:3}.$size() }}<br/> * function SizeCtrl() {
* this.fooStringLength = angular.Object.size('foo');
* }
* </script>
* <div ng:controller="SizeCtrl">
* Number of items in array: {{ [1,2].$size() }}<br/>
* Number of items in object: {{ {a:1, b:2, c:3}.$size() }}<br/>
* String length: {{fooStringLength}}
* </div>
* </doc:source> * </doc:source>
* <doc:scenario> * <doc:scenario>
* it('should print correct sizes for an array and an object', function() { * it('should print correct sizes for an array and an object', function() {
* expect(binding('[1,2].$size()')).toBe('2'); * expect(binding('[1,2].$size()')).toBe('2');
* expect(binding('{a:1, b:2, c:3}.$size()')).toBe('3'); * expect(binding('{a:1, b:2, c:3}.$size()')).toBe('3');
* expect(binding('fooStringLength')).toBe('3');
* }); * });
* </doc:scenario> * </doc:scenario>
* </doc:example> * </doc:example>
@ -581,24 +598,21 @@ function isLeafNode (node) {
* @function * @function
* *
* @description * @description
* Creates a deep copy of `source`. * Creates a deep copy of `source`, which should be an object or an array.
* *
* If `source` is an object or an array, all of its members will be copied into the `destination` * * If no destination is supplied, a copy of the object or array is created.
* object. * * If a destination is provided, all of its elements (for array) or properties (for objects)
* are deleted and then all elements/properties from the source are copied to it.
* * If `source` is not an object or array, `source` is returned.
* *
* If `destination` is not provided and `source` is an object or an array, a copy is created & * Note: this function is used to augment the Object type in Angular expressions. See
* returned, otherwise the `source` is returned. * {@link angular.Array} for more information about Angular arrays.
* *
* If `destination` is provided, all of its properties will be deleted. * @param {*} source The source that will be used to make a copy.
* * Can be any type, including primitives, `null`, and `undefined`.
* Note: this function is used to augment the Object type in angular expressions. See * @param {(Object|Array)=} destination Destination into which the source is copied. If
* {@link angular.Object} for more info.
*
* @param {*} source The source to be used to make a copy.
* Can be any type including primitives, `null` and `undefined`.
* @param {(Object|Array)=} destination Optional destination into which the source is copied. If
* provided, must be of the same type as `source`. * provided, must be of the same type as `source`.
* @returns {*} The copy or updated `destination` if `destination` was specified. * @returns {*} The copy or updated `destination`, if `destination` was specified.
* *
* @example * @example
* <doc:example> * <doc:example>
@ -660,7 +674,6 @@ function copy(source, destination){
} }
/** /**
* @workInProgress
* @ngdoc function * @ngdoc function
* @name angular.equals * @name angular.equals
* @function * @function
@ -675,16 +688,19 @@ function copy(source, destination){
* @function * @function
* *
* @description * @description
* Determines if two objects or value are equivalent. * Determines if two objects or two values are equivalent. Supports value types, arrays and
* objects.
* *
* To be equivalent, they must pass `===` comparison or be of the same type and have all their * Two objects or values are considered equivalent if at least one of the following is true:
* properties pass `===` comparison. During property comparision properties of `function` type and
* properties with name starting with `$` are ignored.
* *
* Supports values types, arrays and objects. * * Both objects or values pass `===` comparison.
* * Both objects or values are of the same type and all of their properties pass `===` comparison.
* *
* Note: this function is used to augment the Object type in angular expressions. See * During a property comparision, properties of `function` type and properties with names
* {@link angular.Object} for more info. * that begin with `$` are ignored.
*
* Note: This function is used to augment the Object type in Angular expressions. See
* {@link angular.Array} for more information about Angular arrays.
* *
* @param {*} o1 Object or value to compare. * @param {*} o1 Object or value to compare.
* @param {*} o2 Object or value to compare. * @param {*} o2 Object or value to compare.
@ -732,7 +748,9 @@ function equals(o1, o2) {
} else { } else {
keySet = {}; keySet = {};
for(key in o1) { for(key in o1) {
if (key.charAt(0) !== '$' && !isFunction(o1[key]) && !equals(o1[key], o2[key])) return false; if (key.charAt(0) !== '$' && !isFunction(o1[key]) && !equals(o1[key], o2[key])) {
return false;
}
keySet[key] = true; keySet[key] = true;
} }
for(key in o2) { for(key in o2) {
@ -802,7 +820,9 @@ function sliceArgs(args, startIndex) {
* @function * @function
* *
* @description * @description
* Returns a function which calls function `fn` bound to `self` (`self` becomes the `this` for `fn`). * Returns a function which calls function `fn` bound to `self`
* (`self` becomes the `this` for `fn`).
*
* Optional `args` can be supplied which are prebound to the function, also known as * Optional `args` can be supplied which are prebound to the function, also known as
* [function currying](http://en.wikipedia.org/wiki/Currying). * [function currying](http://en.wikipedia.org/wiki/Currying).
* *
@ -826,7 +846,8 @@ function bind(self, fn) {
: fn.call(self); : fn.call(self);
}; };
} else { } else {
// in IE, native methods are not functions and so they can not be bound (but they don't need to be) // in IE, native methods are not functions and so they can not be bound
// (but they don't need to be)
return fn; return fn;
} }
} }
@ -928,7 +949,6 @@ function encodeUriQuery(val, pctEncodeSpaces) {
/** /**
* @workInProgress
* @ngdoc directive * @ngdoc directive
* @name angular.directive.ng:autobind * @name angular.directive.ng:autobind
* @element script * @element script
@ -938,14 +958,17 @@ function encodeUriQuery(val, pctEncodeSpaces) {
* @TODO rename to ng:autobind to ng:autoboot * @TODO rename to ng:autobind to ng:autoboot
* *
* @description * @description
* Technically, ng:autobind is not a directive; it is an Angular bootstrap parameter that can act
* as a directive. It must exist in the script used to boot Angular and can be used only one time.
* For details on bootstrapping Angular, see {@link guide/dev_guide.bootstrap Initializing Angular}
* in the Angular Developer Guide.
* *
* `ng:autobind` with no parameters tells angular to compile and manage the whole page. * `ng:autobind` with no parameters tells Angular to compile and manage the whole page.
* *
* `ng:autobind="[root element ID]"` tells angular to compile and manage part of the docucment, * `ng:autobind="[root element ID]"` tells Angular to compile and manage part of the document,
* starting at "root element ID". * starting at "root element ID".
* *
* For details on bootstrapping angular, see {@link guide/dev_guide.bootstrap Initializing Angular}
* in the Angular Developer Guide.
*/ */
function angularInit(config, document){ function angularInit(config, document){
var autobind = config.autobind; var autobind = config.autobind;

206
src/apis.js
View file

@ -23,18 +23,20 @@ var angularGlobal = {
* A namespace for utility functions used to work with JavaScript objects. These functions are * A namespace for utility functions used to work with JavaScript objects. These functions are
* exposed in two ways: * exposed in two ways:
* *
* __* Angular expressions:__ Functions are bound to all objects and augment the Object type. The * * __Angular expressions:__ Functions are bound to all objects and augment the Object type.
* names of these methods are prefixed with the '$' character in order to minimize naming collisions. * The names of these methods are prefixed with the '$' character in order to minimize naming
* To call a method, invoke the function without the first argument, e.g, `myObject.$foo(param2)`. * collisions. To call a method, invoke the function without the first argument, for example,
* `myObject.$foo(param2)`.
* *
* __* JavaScript code:__ Functions don't augment the Object type and must be invoked as functions of * * __JavaScript code:__ Functions don't augment the Object type and must be invoked as functions
* `angular.Object` as `angular.Object.foo(myObject, param2)`. * of `angular.Object` as `angular.Object.foo(myObject, param2)`.
* *
* * {@link angular.Object.copy angular.Object.copy()} - Creates a deep copy of the source parameter * * {@link angular.Object.copy angular.Object.copy()} - Creates a deep copy of the source
* * {@link angular.Object.equals angular.Object.equals()} - Determines if two objects or values are * parameter.
* equivalent * * {@link angular.Object.equals angular.Object.equals()} - Determines if two objects or values
* * {@link angular.Object.size angular.Object.size()} - Determines the number of elements in * are equivalent.
* strings, arrays, and objects. * * {@link angular.Object.size angular.Object.size()} - Determines the number of elements in
* strings, arrays, and objects.
*/ */
var angularCollection = { var angularCollection = {
'copy': copy, 'copy': copy,
@ -54,28 +56,30 @@ var angularObject = {
* *
* These functions are exposed in two ways: * These functions are exposed in two ways:
* *
* * __Angular expressions:__ Functions are bound to the Array objects and augment the Array type as * * __Angular expressions:__ Functions are bound to the Array objects and augment the Array type
* array methods. The names of these methods are prefixed with $ character to minimize naming * as array methods. The names of these methods are prefixed with the `$` character to minimize
* collisions. To call a method, invoke myArrayObject.$foo(params). * naming collisions. To call a method, invoke myArrayObject.$foo(params).
* *
* Because Array type is a subtype of the Object type, all angular.Object functions augment * Because Array type is a subtype of the Object type, all angular.Object functions augment
* theArray type in angular expressions as well. * the Array type in Angular expressions as well.
* *
* * __JavaScript code:__ Functions don't augment the Array type and must be invoked as functions of * * __JavaScript code:__ Functions do nor augment the Array type and must be invoked as functions
* `angular.Array` as `angular.Array.foo(myArrayObject, params)`. * of `angular.Array` as `angular.Array.foo(myArrayObject, params)`.
* *
* The following APIs are built-in to the angular Array object: * The following APIs are built in to the Angular Array object:
* *
* * {@link angular.Array.add angular.Array.add()} - Optionally adds a new element to an array. * * {@link angular.Array.add angular.Array.add()} - Optionally adds a new element to an array.
* * {@link angular.Array.count angular.Array.count()} - Determines the number of elements in an * * {@link angular.Array.count angular.Array.count()} - Determines the number of elements in an
* array. * array.
* * {@link angular.Array.filter angular.Array.filter()} - Returns a subset of items as a new array. * * {@link angular.Array.filter angular.Array.filter()} - Returns the subset of elements specified
* * {@link angular.Array.indexOf angular.Array.indexOf()} - Determines the index of an array value. * in the filter as a new array.
* * {@link angular.Array.limitTo angular.Array.limitTo()} - Creates a new array off the front or * * {@link angular.Array.indexOf angular.Array.indexOf()} - Determines the index of an array
* back of an existing array. * value.
* * {@link angular.Array.orderBy angular.Array.orderBy()} - Orders array elements * * {@link angular.Array.limitTo angular.Array.limitTo()} - Creates a sub-array of an existing
* * {@link angular.Array.remove angular.Array.remove()} - Removes array elements * array.
* * {@link angular.Array.sum angular.Array.sum()} - Sums the number elements in an array * * {@link angular.Array.orderBy angular.Array.orderBy()} - Orders array elements.
* * {@link angular.Array.remove angular.Array.remove()} - Removes array elements.
* * {@link angular.Array.sum angular.Array.sum()} - Sums the numbers in an array.
*/ */
var angularArray = { var angularArray = {
@ -86,14 +90,15 @@ var angularArray = {
* @function * @function
* *
* @description * @description
* Determines the index of `value` in `array`. * Determines the index of a `value` in an `array`.
* *
* Note: this function is used to augment the `Array` type in angular expressions. See * Note: This function is used to augment the `Array` type in Angular expressions. See
* {@link angular.Array} for more info. * {@link angular.Array} for more information about Angular arrays.
* *
* @param {Array} array Array to search. * @param {Array} array Array to search.
* @param {*} value Value to search for. * @param {*} value Value to search for.
* @returns {number} The position of the element in `array`. The position is 0-based. `-1` is returned if the value can't be found. * @returns {number} The position of the element in `array`. The position is 0-based.
* If the value cannot be found, `-1` is returned.
* *
* @example * @example
<doc:example> <doc:example>
@ -126,38 +131,39 @@ var angularArray = {
* @function * @function
* *
* @description * @description
* This function calculates the sum of all numbers in `array`. If the `expressions` is supplied, * The `sum` function calculates the sum of all numbers in an `array`. If an `expression` is
* it is evaluated once for each element in `array` and then the sum of these values is returned. * supplied, `sum` evaluates each element in the `array` with the expression and then returns
* the sum of the calculated values.
* *
* Note: this function is used to augment the `Array` type in angular expressions. See * Note: This function is used to augment the `Array` type in Angular expressions. See
* {@link angular.Array} for more info. * {@link angular.Array} for more info about Angular arrays.
* *
* @param {Array} array The source array. * @param {Array} array The source array.
* @param {(string|function())=} expression Angular expression or a function to be evaluated for each * @param {(string|function())=} expression Angular expression or a function to be evaluated for
* element in `array`. The array element becomes the `this` during the evaluation. * each element in `array`. The array element becomes the `this` during the evaluation.
* @returns {number} Sum of items in the array. * @returns {number} Sum of items in the array.
* *
* @example * @example
<doc:example> <doc:example>
<doc:source> <doc:source>
<table ng:init="invoice= {items:[{qty:10, description:'gadget', cost:9.95}]}"> <table ng:init="invoice= {items:[{qty:10, description:'gadget', cost:9.95}]}">
<tr><th>Qty</th><th>Description</th><th>Cost</th><th>Total</th><th></th></tr> <tr><th>Qty</th><th>Description</th><th>Cost</th><th>Total</th><th></th></tr>
<tr ng:repeat="item in invoice.items"> <tr ng:repeat="item in invoice.items">
<td><input name="item.qty" value="1" size="4" ng:required ng:validate="integer"></td> <td><input name="item.qty" value="1" size="4" ng:required ng:validate="integer"></td>
<td><input name="item.description"></td> <td><input name="item.description"></td>
<td><input name="item.cost" value="0.00" ng:required ng:validate="number" size="6"></td> <td><input name="item.cost" value="0.00" ng:required ng:validate="number" size="6"></td>
<td>{{item.qty * item.cost | currency}}</td> <td>{{item.qty * item.cost | currency}}</td>
<td>[<a href ng:click="invoice.items.$remove(item)">X</a>]</td> <td>[<a href ng:click="invoice.items.$remove(item)">X</a>]</td>
</tr> </tr>
<tr> <tr>
<td><a href ng:click="invoice.items.$add()">add item</a></td> <td><a href ng:click="invoice.items.$add()">add item</a></td>
<td></td> <td></td>
<td>Total:</td> <td>Total:</td>
<td>{{invoice.items.$sum('qty*cost') | currency}}</td> <td>{{invoice.items.$sum('qty*cost') | currency}}</td>
</tr> </tr>
</table> </table>
</doc:source> </doc:source>
<doc:scenario> <doc:scenario>
//TODO: these specs are lame because I had to work around issues #164 and #167 //TODO: these specs are lame because I had to work around issues #164 and #167
it('should initialize and calculate the totals', function() { it('should initialize and calculate the totals', function() {
expect(repeater('.doc-example-live table tr', 'item in invoice.items').count()).toBe(3); expect(repeater('.doc-example-live table tr', 'item in invoice.items').count()).toBe(3);
@ -176,7 +182,7 @@ var angularArray = {
toEqual(['$2,000.00']); toEqual(['$2,000.00']);
expect(binding("invoice.items.$sum('qty*cost')")).toBe('$2,099.50'); expect(binding("invoice.items.$sum('qty*cost')")).toBe('$2,099.50');
}); });
</doc:scenario> </doc:scenario>
</doc:example> </doc:example>
*/ */
'sum':function(array, expression) { 'sum':function(array, expression) {
@ -202,8 +208,8 @@ var angularArray = {
* {@link angular.Array.indexOf indexOf} function on the `array` and only the first instance of * {@link angular.Array.indexOf indexOf} function on the `array` and only the first instance of
* the element will be removed. * the element will be removed.
* *
* Note: this function is used to augment the `Array` type in angular expressions. See * Note: This function is used to augment the `Array` type in Angular expressions. See
* {@link angular.Array} for more info. * {@link angular.Array} for more information about Angular arrays.
* *
* @param {Array} array Array from which an element should be removed. * @param {Array} array Array from which an element should be removed.
* @param {*} value Element to be removed. * @param {*} value Element to be removed.
@ -258,8 +264,8 @@ var angularArray = {
* @description * @description
* Selects a subset of items from `array` and returns it as a new array. * Selects a subset of items from `array` and returns it as a new array.
* *
* Note: this function is used to augment the `Array` type in angular expressions. See * Note: This function is used to augment the `Array` type in Angular expressions. See
* {@link angular.Array} for more info. * {@link angular.Array} for more information about Angular arrays.
* *
* @param {Array} array The source array. * @param {Array} array The source array.
* @param {string|Object|function()} expression The predicate to be used for selecting items from * @param {string|Object|function()} expression The predicate to be used for selecting items from
@ -412,28 +418,28 @@ var angularArray = {
/** /**
* @workInProgress
* @ngdoc function * @ngdoc function
* @name angular.Array.add * @name angular.Array.add
* @function * @function
* *
* @description * @description
* `add` is a function similar to JavaScript's `Array#push` method, in that it appends a new * The `add` function in Angualar is similar to JavaScript's `Array#push` method in that it
* element to an array. The difference is that the value being added is optional and defaults to * appends a new element to an array. Angular's function differs from the JavaScript method in
* an empty object. * that specifying a value for the function is optional and the default for the function is an
* empty object.
* *
* Note: this function is used to augment the `Array` type in angular expressions. See * Note: This function is used to augment the `Array` type in Angular expressions. See
* {@link angular.Array} for more info. * {@link angular.Array} for more information about Angular arrays.
* *
* @param {Array} array The array expand. * @param {Array} array The array to be expanded.
* @param {*=} [value={}] The value to be added. * @param {*=} [value={}] The value to be appended.
* @returns {Array} The expanded array. * @returns {Array} The expanded array.
* *
* @TODO simplify the example. * @TODO simplify the example.
* *
* @example * @example
* This example shows how an initially empty array can be filled with objects created from user * This example shows how you can use the `$add` method to populate an initially empty array
* input via the `$add` method. * with objects created from user input.
<doc:example> <doc:example>
<doc:source> <doc:source>
[<a href="" ng:click="people.$add()">add empty</a>] [<a href="" ng:click="people.$add()">add empty</a>]
@ -493,17 +499,18 @@ var angularArray = {
* @function * @function
* *
* @description * @description
* Determines the number of elements in an array. Optionally it will count only those elements * Determines the number of elements in an array. Provides an option for counting only those
* for which the `condition` evaluates to `true`. * elements for which a specified `condition` evaluates to `true`.
* *
* Note: this function is used to augment the `Array` type in angular expressions. See * Note: This function is used to augment the `Array` type in Angular expressions. See
* {@link angular.Array} for more info. * {@link angular.Array} for more information about Angular arrays.
* *
* @param {Array} array The array to count elements in. * @param {Array} array The array containing the elements to be counted.
* @param {(function()|string)=} condition A function to be evaluated or angular expression to be * @param {(function()|string)=} condition A function to be evaluated or
* compiled and evaluated. The element that is currently being iterated over, is exposed to * an Angular expression to be compiled and evaluated. The element being
* the `condition` as `this`. * iterated over is exposed to the `condition` as `this`.
* @returns {number} Number of elements in the array (for which the condition evaluates to true). * @returns {number} Number of elements in the array. If a `condition` is specified, returns
* the number of elements whose `condition` evaluates to `true`.
* *
* @example * @example
<doc:example> <doc:example>
@ -518,7 +525,8 @@ var angularArray = {
</li> </li>
</ul> </ul>
<p>Number of items which have one point: <em>{{ items.$count('points==1') }}</em></p> <p>Number of items which have one point: <em>{{ items.$count('points==1') }}</em></p>
<p>Number of items which have more than one point: <em>{{items.$count('points&gt;1')}}</em></p> <p>Number of items which have more than one point:
<em>{{items.$count('points&gt;1')}}</em></p>
</doc:source> </doc:source>
<doc:scenario> <doc:scenario>
it('should calculate counts', function() { it('should calculate counts', function() {
@ -552,10 +560,10 @@ var angularArray = {
* @function * @function
* *
* @description * @description
* Orders `array` by the `expression` predicate. * Orders a specified `array` by the `expression` predicate.
* *
* Note: this function is used to augment the `Array` type in angular expressions. See * Note: this function is used to augment the `Array` type in Angular expressions. See
* {@link angular.Array} for more info. * {@link angular.Array} for more informaton about Angular arrays.
* *
* @param {Array} array The array to sort. * @param {Array} array The array to sort.
* @param {function(*)|string|Array.<(function(*)|string)>} expression A predicate to be * @param {function(*)|string|Array.<(function(*)|string)>} expression A predicate to be
@ -563,13 +571,13 @@ var angularArray = {
* *
* Can be one of: * Can be one of:
* *
* - `function`: getter function. The result of this function will be sorted using the * - `function`: Getter function. The result of this function will be sorted using the
* `<`, `=`, `>` operator * `<`, `=`, `>` operator.
* - `string`: angular expression which evaluates to an object to order by, such as 'name' to * - `string`: An Angular expression which evaluates to an object to order by, such as 'name'
* sort by a property called 'name'. Optionally prefixed with `+` or `-` to control ascending * to sort by a property called 'name'. Optionally prefixed with `+` or `-` to control
* or descending sort order (e.g. +name or -name). * ascending or descending sort order (for example, +name or -name).
* - `Array`: array of function or string predicates, such that a first predicate in the array * - `Array`: An array of function or string predicates. The first predicate in the array
* is used for sorting, but when the items are equivalent next predicate is used. * is used for sorting, but when two items are equivalent, the next predicate is used.
* *
* @param {boolean=} reverse Reverse the order the array. * @param {boolean=} reverse Reverse the order the array.
* @returns {Array} Sorted copy of the source array. * @returns {Array} Sorted copy of the source array.
@ -678,16 +686,18 @@ var angularArray = {
* @function * @function
* *
* @description * @description
* Creates a new array containing only the first, or last `limit` number of elements of the * Creates a new array containing only a specified number of elements in an array. The elements
* source `array`. * are taken from either the beginning or the end of the source array, as specified by the
* value and sign (positive or negative) of `limit`.
* *
* Note: this function is used to augment the `Array` type in angular expressions. See * Note: This function is used to augment the `Array` type in Angular expressions. See
* {@link angular.Array} for more info. * {@link angular.Array} for more information about Angular arrays.
* *
* @param {Array} array Source array to be limited. * @param {Array} array Source array to be limited.
* @param {string|Number} limit The length of the returned array. If the number is positive, the * @param {string|Number} limit The length of the returned array. If the `limit` number is
* first `limit` items from the source array will be copied, if the number is negative, the * positive, `limit` number of items from the beginning of the source array are copied.
* last `limit` items will be copied. * If the number is negative, `limit` number of items from the end of the source array are
* copied.
* @returns {Array} A new sub-array of length `limit`. * @returns {Array} A new sub-array of length `limit`.
* *
* @example * @example
@ -761,7 +771,9 @@ var angularString = {
}, },
/** /**
* Tries to convert input to date and if successful returns the date, otherwise returns the input. * Tries to convert input to date and if successful returns the date, otherwise returns the
* input.
*
* @param {string} string * @param {string} string
* @return {(Date|string)} * @return {(Date|string)}
*/ */

71
src/directives.js
View file

@ -1,44 +1,46 @@
'use strict'; 'use strict';
/** /**
* @workInProgress
* @ngdoc overview * @ngdoc overview
* @name angular.directive * @name angular.directive
* @description * @description
* *
* Custom attributes for DOM elements. Directives modify the behavior of the element they are * Angular directives create custom attributes for DOM elements. A directive can modify the
* specified in, but are not intended to add elements to the DOM as are * behavior of the element in which it is specified. Do not use directives to add elements to the
* {@link angular.widget widgets}. * DOM; instead, use {@link angular.widget widgets} to add DOM elements.
* *
* Following is the list of built-in angular directives: * Following is the list of built-in Angular directives:
* *
* * {@link angular.directive.ng:bind ng:bind} - Creates a data-binding between HTML text value and * * {@link angular.directive.ng:autobind ng:autobind} - An Angular bootstrap parameter that can
* data model. * act as a directive.
* * {@link angular.directive.ng:bind-attr ng:bind-attr} - Creates a data-binding as in `ng:bind`, * * {@link angular.directive.ng:bind ng:bind} - Creates a data-binding between an HTML text value
* but uses JSON key / value pairs. * and a data model.
* * {@link angular.directive.ng:bind-template ng:bind-template} - Replaces text value of an element * * {@link angular.directive.ng:bind-attr ng:bind-attr} - Creates a data-binding in a way similar
* with a specified template. * to `ng:bind`, but uses JSON key / value pairs to do so.
* * {@link angular.directive.ng:bind-template ng:bind-template} - Replaces the text value of an
* element with a specified template.
* * {@link angular.directive.ng:change ng:change} - Executes an expression when the value of an * * {@link angular.directive.ng:change ng:change} - Executes an expression when the value of an
* input widget changes. * input widget changes.
* * {@link angular.directive.ng:class ng:class} - Conditionally set CSS class on an element. * * {@link angular.directive.ng:class ng:class} - Conditionally set a CSS class on an element.
* * {@link angular.directive.ng:class-even ng:class-even} - Like `ng:class`, but works in * * {@link angular.directive.ng:class-even ng:class-even} - Like `ng:class`, but works in
* conjunction with {@link angular.widget.@ng:repeat} to affect even rows in a collection. * conjunction with {@link angular.widget.@ng:repeat} to affect even rows in a collection.
* * {@link angular.directive.ng:class-odd ng:class-odd} - Like `ng:class`, but works with {@link * * {@link angular.directive.ng:class-odd ng:class-odd} - Like `ng:class`, but works with {@link
* angular.widget.@ng:repeat} to affect odd rows. * angular.widget.@ng:repeat} to affect odd rows.
* * {@link angular.directive.ng:click ng:click} - Executes custom behavior when element is clicked. * * {@link angular.directive.ng:click ng:click} - Executes custom behavior when an element is
* clicked.
* * {@link angular.directive.ng:controller ng:controller} - Creates a scope object linked to the * * {@link angular.directive.ng:controller ng:controller} - Creates a scope object linked to the
* DOM element and assigns behavior to the scope. * DOM element and assigns behavior to the scope.
* * {@link angular.directive.ng:hide ng:hide} - Conditionally hides a portion of HTML. * * {@link angular.directive.ng:hide ng:hide} - Conditionally hides a portion of HTML.
* * {@link angular.directive.ng:href ng:href} - Places an href in the angular namespace. * * {@link angular.directive.ng:href ng:href} - Places an href in the Angular namespace.
* * {@link angular.directive.ng:init} - Initialization tasks run before a template is executed. * * {@link angular.directive.ng:init} - Initialization tasks run before a template is executed.
* * {@link angular.directive.ng:show ng:show} - Conditionally displays a portion of HTML. * * {@link angular.directive.ng:show ng:show} - Conditionally displays a portion of HTML.
* * {@link angular.directive.ng:src ng:src} - Places a `src` attribute into the angular namespace. * * {@link angular.directive.ng:src ng:src} - Places a `src` attribute into the Angular namespace.
* * {@link angular.directive.ng:style ng:style} - Conditionally set CSS styles on an element. * * {@link angular.directive.ng:style ng:style} - Conditionally set CSS styles on an element.
* * {@link angular.directive.ng:submit} - Binds angular expressions to `onSubmit` events. * * {@link angular.directive.ng:submit} - Binds Angular expressions to `onSubmit` events.
* *
* For more information about how angular directives work, and how to create your own directives, * For more information about how Angular directives work, and to learn how to create your own
* see {@link guide/dev_guide.compiler.directives Understanding Angular Directives} in the angular * directives, see {@link guide/dev_guide.compiler.directives Understanding Angular Directives} in
* Developer Guide. * the Angular Developer Guide.
*/ */
/** /**
@ -151,12 +153,17 @@ angularDirective("ng:init", function(expression){
<doc:scenario> <doc:scenario>
it('should check controller', function(){ it('should check controller', function(){
expect(element('.doc-example-live div>:input').val()).toBe('John Smith'); expect(element('.doc-example-live div>:input').val()).toBe('John Smith');
expect(element('.doc-example-live li[ng\\:repeat-index="0"] input').val()).toBe('408 555 1212'); expect(element('.doc-example-live li[ng\\:repeat-index="0"] input').val())
expect(element('.doc-example-live li[ng\\:repeat-index="1"] input').val()).toBe('john.smith@example.org'); .toBe('408 555 1212');
expect(element('.doc-example-live li[ng\\:repeat-index="1"] input').val())
.toBe('john.smith@example.org');
element('.doc-example-live li:first a:contains("clear")').click(); element('.doc-example-live li:first a:contains("clear")').click();
expect(element('.doc-example-live li:first input').val()).toBe(''); expect(element('.doc-example-live li:first input').val()).toBe('');
element('.doc-example-live li:last a:contains("add")').click(); element('.doc-example-live li:last a:contains("add")').click();
expect(element('.doc-example-live li[ng\\:repeat-index="2"] input').val()).toBe('yourname@example.org'); expect(element('.doc-example-live li[ng\\:repeat-index="2"] input').val())
.toBe('yourname@example.org');
}); });
</doc:scenario> </doc:scenario>
</doc:example> </doc:example>
@ -173,22 +180,21 @@ angularDirective("ng:controller", function(expression){
}); });
/** /**
* @workInProgress
* @ngdoc directive * @ngdoc directive
* @name angular.directive.ng:bind * @name angular.directive.ng:bind
* *
* @description * @description
* The `ng:bind` attribute asks angular to replace the text content of this * The `ng:bind` attribute tells Angular to replace the text content of the specified
* HTML element with the value of the given expression, and to keep the text * HTML element with the value of the given expression, and to update the text
* content up to date when the expression's value changes. Usually you would * content whenever the expression's value changes. Usually, you would
* just write `{{ expression }}` and let angular compile it into * just write `{{ expression }}` and let Angular compile it into
* `<span ng:bind="expression"></span>` at bootstrap time. * `<span ng:bind="expression"></span>` at bootstrap time.
* *
* @element ANY * @element ANY
* @param {expression} expression {@link guide/dev_guide.expressions Expression} to eval. * @param {expression} expression {@link guide/dev_guide.expressions Expression} to evaluate.
* *
* @example * @example
* You can try it right here: enter text in the text box and watch the greeting change. * Enter a name in the Live Preview text box and watch the greeting below it change instantly.
<doc:example> <doc:example>
<doc:source> <doc:source>
Enter name: <input type="text" name="name" value="Whirled"> <br> Enter name: <input type="text" name="name" value="Whirled"> <br>
@ -227,8 +233,8 @@ angularDirective("ng:bind", function(expression, element){
delete scope.$element; delete scope.$element;
} }
} }
// If we are HTML than save the raw HTML data so that we don't // If we are HTML, then save the raw HTML data so that we don't
// recompute sanitization since it is expensive. // recompute sanitization since that is expensive.
// TODO: turn this into a more generic way to compute this // TODO: turn this into a more generic way to compute this
if ((isHtml = (value instanceof HTML))) if ((isHtml = (value instanceof HTML)))
value = (html = value).html; value = (html = value).html;
@ -458,7 +464,8 @@ angularDirective("ng:bind-attr", function(expression){
* element is clicked. * element is clicked.
* *
* @element ANY * @element ANY
* @param {expression} expression {@link guide/dev_guide.expressions Expression} to eval upon click. * @param {expression} expression {@link guide/dev_guide.expressions Expression} to evaluate upon
* click.
* *
* @example * @example
<doc:example> <doc:example>