Hopiu/angular.js
1
0
Fork 0
mirror of https://github.com/Hopiu/angular.js.git synced 2026-03-17 07:40:22 +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
// locale, for this reason we need to detect this case and redefine lowercase/uppercase methods with
// correct but slower alternatives.
// locale, for this reason we need to detect this case and redefine lowercase/uppercase methods
// with correct but slower alternatives.
if ('i' !== 'I'.toLowerCase()) {
lowercase = manualLowercase;
uppercase = manualUppercase;
@ -118,10 +118,11 @@ var _undefined = undefined,
* @function
*
* @description
* Invokes the `iterator` function once for each item in `obj` collection. The collection can either
* be an object or an array. The `iterator` function is invoked with `iterator(value, key)`, where
* `value` is the value of an object property or an array element and `key` is the object property
* key or array element index. Optionally, `context` can be specified for the iterator function.
* Invokes the `iterator` function once for each item in `obj` collection. The collection can
* either be an object or an array. The `iterator` function is invoked with `iterator(value, key)`,
* where `value` is the value of an object property or an array element and `key` is the object
* property key or array element index. Optionally, `context` can be specified for the iterator
* function.
*
* Note: this function was previously known as `angular.foreach`.
*
@ -222,8 +223,8 @@ function nextUid() {
* @function
*
* @description
* Extends the destination object `dst` by copying all of the properties from the `src` object(s) to
* `dst`. You can specify multiple `src` objects.
* Extends the destination object `dst` by copying all of the properties from the `src` object(s)
* to `dst`. You can specify multiple `src` objects.
*
* @param {Object} dst The destination object.
* @param {...Object} src The source object(s).
@ -428,9 +429,13 @@ function isWindow(obj) {
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 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) {
return node &&
(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
* @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) {
this.html = html;
@ -470,7 +477,8 @@ function HTML(html, option) {
if (msie < 9) {
nodeName_ = function(element) {
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 {
nodeName_ = function(element) {
@ -500,26 +508,35 @@ function map(obj, iterator, context) {
* @function
*
* @description
* Determines the number of elements in an array, number of properties of an object or string
* length.
* Determines the number of elements in an array, the number of properties an object has, or
* the length of a string.
*
* Note: this function is used to augment the Object type in angular expressions. See
* {@link angular.Object} for more info.
* Note: This function is used to augment the Object type in Angular expressions. See
* {@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
* @returns {number} The size of `obj` or `0` if `obj` is neither an object or an array.
*
* @example
* <doc:example>
* <doc:source>
* Number of items in array: {{ [1,2].$size() }}<br/>
* Number of items in object: {{ {a:1, b:2, c:3}.$size() }}<br/>
* <script>
* 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:scenario>
* it('should print correct sizes for an array and an object', function() {
* expect(binding('[1,2].$size()')).toBe('2');
* expect(binding('{a:1, b:2, c:3}.$size()')).toBe('3');
* expect(binding('fooStringLength')).toBe('3');
* });
* </doc:scenario>
* </doc:example>
@ -581,24 +598,21 @@ function isLeafNode (node) {
* @function
*
* @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`
* object.
* * If no destination is supplied, a copy of the object or array is created.
* * 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 &
* returned, otherwise the `source` is returned.
* Note: this function is used to augment the Object type in Angular expressions. See
* {@link angular.Array} for more information about Angular arrays.
*
* If `destination` is provided, all of its properties will be deleted.
*
* Note: this function is used to augment the Object type in angular expressions. See
* {@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
* @param {*} source The source that will be used to make a copy.
* Can be any type, including primitives, `null`, and `undefined`.
* @param {(Object|Array)=} destination Destination into which the source is copied. If
* 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
* <doc:example>
@ -660,7 +674,6 @@ function copy(source, destination){
}
/**
* @workInProgress
* @ngdoc function
* @name angular.equals
* @function
@ -675,16 +688,19 @@ function copy(source, destination){
* @function
*
* @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
* properties pass `===` comparison. During property comparision properties of `function` type and
* properties with name starting with `$` are ignored.
* Two objects or values are considered equivalent if at least one of the following is true:
*
* 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
* {@link angular.Object} for more info.
* During a property comparision, properties of `function` type and properties with names
* 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 {*} o2 Object or value to compare.
@ -732,7 +748,9 @@ function equals(o1, o2) {
} else {
keySet = {};
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;
}
for(key in o2) {
@ -802,7 +820,9 @@ function sliceArgs(args, startIndex) {
* @function
*
* @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
* [function currying](http://en.wikipedia.org/wiki/Currying).
*
@ -826,7 +846,8 @@ function bind(self, fn) {
: fn.call(self);
};
} 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;
}
}
@ -928,7 +949,6 @@ function encodeUriQuery(val, pctEncodeSpaces) {
/**
* @workInProgress
* @ngdoc directive
* @name angular.directive.ng:autobind
* @element script
@ -938,14 +958,17 @@ function encodeUriQuery(val, pctEncodeSpaces) {
* @TODO rename to ng:autobind to ng:autoboot
*
* @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".
*
* For details on bootstrapping angular, see {@link guide/dev_guide.bootstrap Initializing Angular}
* in the Angular Developer Guide.
*/
function angularInit(config, document){
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
* exposed in two ways:
*
* __* Angular expressions:__ Functions are bound to all objects and augment the Object type. The
* names of these methods are prefixed with the '$' character in order to minimize naming collisions.
* To call a method, invoke the function without the first argument, e.g, `myObject.$foo(param2)`.
* * __Angular expressions:__ Functions are bound to all objects and augment the Object type.
* The names of these methods are prefixed with the '$' character in order to minimize naming
* 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
* `angular.Object` as `angular.Object.foo(myObject, param2)`.
* * __JavaScript code:__ Functions don't augment the Object type and must be invoked as functions
* 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.equals angular.Object.equals()} - Determines if two objects or values are
* equivalent
* * {@link angular.Object.size angular.Object.size()} - Determines the number of elements in
* strings, arrays, and objects.
* * {@link angular.Object.copy angular.Object.copy()} - Creates a deep copy of the source
* parameter.
* * {@link angular.Object.equals angular.Object.equals()} - Determines if two objects or values
* are equivalent.
* * {@link angular.Object.size angular.Object.size()} - Determines the number of elements in
* strings, arrays, and objects.
*/
var angularCollection = {
'copy': copy,
@ -54,28 +56,30 @@ var angularObject = {
*
* These functions are exposed in two ways:
*
* * __Angular expressions:__ Functions are bound to the Array objects and augment the Array type as
* array methods. The names of these methods are prefixed with $ character to minimize naming
* collisions. To call a method, invoke myArrayObject.$foo(params).
* * __Angular expressions:__ Functions are bound to the Array objects and augment the Array type
* as array methods. The names of these methods are prefixed with the `$` character to minimize
* 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
* 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
* `angular.Array` as `angular.Array.foo(myArrayObject, params)`.
* * __JavaScript code:__ Functions do nor augment the Array type and must be invoked as functions
* 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.count angular.Array.count()} - Determines the number of elements in an
* array.
* * {@link angular.Array.filter angular.Array.filter()} - Returns a subset of items as a new array.
* * {@link angular.Array.indexOf angular.Array.indexOf()} - Determines the index of an array value.
* * {@link angular.Array.limitTo angular.Array.limitTo()} - Creates a new array off the front or
* back of an existing 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 number elements in an array
* array.
* * {@link angular.Array.filter angular.Array.filter()} - Returns the subset of elements specified
* in the filter as a new array.
* * {@link angular.Array.indexOf angular.Array.indexOf()} - Determines the index of an array
* value.
* * {@link angular.Array.limitTo angular.Array.limitTo()} - Creates a sub-array of an existing
* 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 = {
@ -86,14 +90,15 @@ var angularArray = {
* @function
*
* @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
* {@link angular.Array} for more info.
* Note: This function is used to augment the `Array` type in Angular expressions. See
* {@link angular.Array} for more information about Angular arrays.
*
* @param {Array} array Array to search.
* @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
<doc:example>
@ -126,38 +131,39 @@ var angularArray = {
* @function
*
* @description
* This function calculates the sum of all numbers in `array`. If the `expressions` is supplied,
* it is evaluated once for each element in `array` and then the sum of these values is returned.
* The `sum` function calculates the sum of all numbers in an `array`. If an `expression` is
* 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
* {@link angular.Array} for more info.
* Note: This function is used to augment the `Array` type in Angular expressions. See
* {@link angular.Array} for more info about Angular arrays.
*
* @param {Array} array The source array.
* @param {(string|function())=} expression Angular expression or a function to be evaluated for each
* element in `array`. The array element becomes the `this` during the evaluation.
* @param {(string|function())=} expression Angular expression or a function to be evaluated for
* each element in `array`. The array element becomes the `this` during the evaluation.
* @returns {number} Sum of items in the array.
*
* @example
<doc:example>
<doc:source>
<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 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.description"></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>[<a href ng:click="invoice.items.$remove(item)">X</a>]</td>
</tr>
<tr>
<td><a href ng:click="invoice.items.$add()">add item</a></td>
<td></td>
<td>Total:</td>
<td>{{invoice.items.$sum('qty*cost') | currency}}</td>
</tr>
</table>
</doc:source>
<doc:scenario>
<doc:source>
<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 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.description"></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>[<a href ng:click="invoice.items.$remove(item)">X</a>]</td>
</tr>
<tr>
<td><a href ng:click="invoice.items.$add()">add item</a></td>
<td></td>
<td>Total:</td>
<td>{{invoice.items.$sum('qty*cost') | currency}}</td>
</tr>
</table>
</doc:source>
<doc:scenario>
//TODO: these specs are lame because I had to work around issues #164 and #167
it('should initialize and calculate the totals', function() {
expect(repeater('.doc-example-live table tr', 'item in invoice.items').count()).toBe(3);
@ -176,7 +182,7 @@ var angularArray = {
toEqual(['$2,000.00']);
expect(binding("invoice.items.$sum('qty*cost')")).toBe('$2,099.50');
});
</doc:scenario>
</doc:scenario>
</doc:example>
*/
'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
* the element will be removed.
*
* Note: this function is used to augment the `Array` type in angular expressions. See
* {@link angular.Array} for more info.
* Note: This function is used to augment the `Array` type in Angular expressions. See
* {@link angular.Array} for more information about Angular arrays.
*
* @param {Array} array Array from which an element should be removed.
* @param {*} value Element to be removed.
@ -258,8 +264,8 @@ var angularArray = {
* @description
* 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
* {@link angular.Array} for more info.
* Note: This function is used to augment the `Array` type in Angular expressions. See
* {@link angular.Array} for more information about Angular arrays.
*
* @param {Array} array The source array.
* @param {string|Object|function()} expression The predicate to be used for selecting items from
@ -412,28 +418,28 @@ var angularArray = {
/**
* @workInProgress
* @ngdoc function
* @name angular.Array.add
* @function
*
* @description
* `add` is a function similar to JavaScript's `Array#push` method, in that it appends a new
* element to an array. The difference is that the value being added is optional and defaults to
* an empty object.
* The `add` function in Angualar is similar to JavaScript's `Array#push` method in that it
* appends a new element to an array. Angular's function differs from the JavaScript method in
* 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
* {@link angular.Array} for more info.
* Note: This function is used to augment the `Array` type in Angular expressions. See
* {@link angular.Array} for more information about Angular arrays.
*
* @param {Array} array The array expand.
* @param {*=} [value={}] The value to be added.
* @param {Array} array The array to be expanded.
* @param {*=} [value={}] The value to be appended.
* @returns {Array} The expanded array.
*
* @TODO simplify the example.
*
* @example
* This example shows how an initially empty array can be filled with objects created from user
* input via the `$add` method.
* This example shows how you can use the `$add` method to populate an initially empty array
* with objects created from user input.
<doc:example>
<doc:source>
[<a href="" ng:click="people.$add()">add empty</a>]
@ -493,17 +499,18 @@ var angularArray = {
* @function
*
* @description
* Determines the number of elements in an array. Optionally it will count only those elements
* for which the `condition` evaluates to `true`.
* Determines the number of elements in an array. Provides an option for counting only those
* elements for which a specified `condition` evaluates to `true`.
*
* Note: this function is used to augment the `Array` type in angular expressions. See
* {@link angular.Array} for more info.
* Note: This function is used to augment the `Array` type in Angular expressions. See
* {@link angular.Array} for more information about Angular arrays.
*
* @param {Array} array The array to count elements in.
* @param {(function()|string)=} condition A function to be evaluated or angular expression to be
* compiled and evaluated. The element that is currently being iterated over, is exposed to
* the `condition` as `this`.
* @returns {number} Number of elements in the array (for which the condition evaluates to true).
* @param {Array} array The array containing the elements to be counted.
* @param {(function()|string)=} condition A function to be evaluated or
* an Angular expression to be compiled and evaluated. The element being
* iterated over is exposed to the `condition` as `this`.
* @returns {number} Number of elements in the array. If a `condition` is specified, returns
* the number of elements whose `condition` evaluates to `true`.
*
* @example
<doc:example>
@ -518,7 +525,8 @@ var angularArray = {
</li>
</ul>
<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:scenario>
it('should calculate counts', function() {
@ -552,10 +560,10 @@ var angularArray = {
* @function
*
* @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
* {@link angular.Array} for more info.
* Note: this function is used to augment the `Array` type in Angular expressions. See
* {@link angular.Array} for more informaton about Angular arrays.
*
* @param {Array} array The array to sort.
* @param {function(*)|string|Array.<(function(*)|string)>} expression A predicate to be
@ -563,13 +571,13 @@ var angularArray = {
*
* Can be one of:
*
* - `function`: getter function. The result of this function will be sorted using the
* `<`, `=`, `>` operator
* - `string`: angular expression which evaluates to an object to order by, such as 'name' to
* sort by a property called 'name'. Optionally prefixed with `+` or `-` to control ascending
* or descending sort order (e.g. +name or -name).
* - `Array`: array of function or string predicates, such that a first predicate in the array
* is used for sorting, but when the items are equivalent next predicate is used.
* - `function`: Getter function. The result of this function will be sorted using the
* `<`, `=`, `>` operator.
* - `string`: An Angular expression which evaluates to an object to order by, such as 'name'
* to sort by a property called 'name'. Optionally prefixed with `+` or `-` to control
* ascending or descending sort order (for example, +name or -name).
* - `Array`: An array of function or string predicates. The first predicate in the array
* is used for sorting, but when two items are equivalent, the next predicate is used.
*
* @param {boolean=} reverse Reverse the order the array.
* @returns {Array} Sorted copy of the source array.
@ -678,16 +686,18 @@ var angularArray = {
* @function
*
* @description
* Creates a new array containing only the first, or last `limit` number of elements of the
* source `array`.
* Creates a new array containing only a specified number of elements in an array. The elements
* 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
* {@link angular.Array} for more info.
* Note: This function is used to augment the `Array` type in Angular expressions. See
* {@link angular.Array} for more information about Angular arrays.
*
* @param {Array} array Source array to be limited.
* @param {string|Number} limit The length of the returned array. If the number is positive, the
* first `limit` items from the source array will be copied, if the number is negative, the
* last `limit` items will be copied.
* @param {string|Number} limit The length of the returned array. If the `limit` number is
* positive, `limit` number of items from the beginning of the source array are 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`.
*
* @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
* @return {(Date|string)}
*/

71
src/directives.js
View file

@ -1,44 +1,46 @@
'use strict';
/**
* @workInProgress
* @ngdoc overview
* @name angular.directive
* @description
*
* Custom attributes for DOM elements. Directives modify the behavior of the element they are
* specified in, but are not intended to add elements to the DOM as are
* {@link angular.widget widgets}.
* Angular directives create custom attributes for DOM elements. A directive can modify the
* behavior of the element in which it is specified. Do not use directives to add elements to the
* 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
* data model.
* * {@link angular.directive.ng:bind-attr ng:bind-attr} - Creates a data-binding as in `ng:bind`,
* but uses JSON key / value pairs.
* * {@link angular.directive.ng:bind-template ng:bind-template} - Replaces text value of an element
* with a specified template.
* * {@link angular.directive.ng:autobind ng:autobind} - An Angular bootstrap parameter that can
* act as a directive.
* * {@link angular.directive.ng:bind ng:bind} - Creates a data-binding between an HTML text value
* and a data model.
* * {@link angular.directive.ng:bind-attr ng:bind-attr} - Creates a data-binding in a way similar
* 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
* 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
* 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
* 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
* 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: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: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: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,
* see {@link guide/dev_guide.compiler.directives Understanding Angular Directives} in the angular
* Developer Guide.
* For more information about how Angular directives work, and to learn how to create your own
* directives, see {@link guide/dev_guide.compiler.directives Understanding Angular Directives} in
* the Angular Developer Guide.
*/
/**
@ -151,12 +153,17 @@ angularDirective("ng:init", function(expression){
<doc:scenario>
it('should check controller', function(){
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="1"] input').val()).toBe('john.smith@example.org');
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="1"] input').val())
.toBe('john.smith@example.org');
element('.doc-example-live li:first a:contains("clear")').click();
expect(element('.doc-example-live li:first input').val()).toBe('');
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:example>
@ -173,22 +180,21 @@ angularDirective("ng:controller", function(expression){
});
/**
* @workInProgress
* @ngdoc directive
* @name angular.directive.ng:bind
*
* @description
* The `ng:bind` attribute asks angular to replace the text content of this
* HTML element with the value of the given expression, and to keep the text
* content up to date when the expression's value changes. Usually you would
* just write `{{ expression }}` and let angular compile it into
* 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 update the text
* content whenever the expression's value changes. Usually, you would
* just write `{{ expression }}` and let Angular compile it into
* `<span ng:bind="expression"></span>` at bootstrap time.
*
* @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
* 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:source>
Enter name: <input type="text" name="name" value="Whirled"> <br>
@ -227,8 +233,8 @@ angularDirective("ng:bind", function(expression, element){
delete scope.$element;
}
}
// If we are HTML than save the raw HTML data so that we don't
// recompute sanitization since it is expensive.
// If we are HTML, then save the raw HTML data so that we don't
// recompute sanitization since that is expensive.
// TODO: turn this into a more generic way to compute this
if ((isHtml = (value instanceof HTML)))
value = (html = value).html;
@ -458,7 +464,8 @@ angularDirective("ng:bind-attr", function(expression){
* element is clicked.
*
* @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
<doc:example>