diff options
Diffstat (limited to 'src')
| -rw-r--r-- | src/Scope.js | 141 | ||||
| -rw-r--r-- | src/angular-mocks.js | 17 | ||||
| -rw-r--r-- | src/apis.js | 49 | ||||
| -rw-r--r-- | src/directives.js | 42 | ||||
| -rw-r--r-- | src/filters.js | 26 | ||||
| -rw-r--r-- | src/formatters.js | 22 | ||||
| -rw-r--r-- | src/validators.js | 30 | ||||
| -rw-r--r-- | src/widgets.js | 27 |
8 files changed, 207 insertions, 147 deletions
diff --git a/src/Scope.js b/src/Scope.js index caff69c9..c7bdda0e 100644 --- a/src/Scope.js +++ b/src/Scope.js @@ -104,6 +104,7 @@ function errorHandlerFor(element, error) { elementError(element, NG_EXCEPTION, isDefined(error) ? formatError(error) : error); } + /** * @workInProgress * @ngdoc overview @@ -111,134 +112,24 @@ function errorHandlerFor(element, error) { * * @description * Scope is a JavaScript object and the execution context for expressions. You can think about - * scopes as JavaScript objects that have extra APIs for registering watchers. A scope is the model - * in the model-view-controller design pattern. - * - * A few other characteristics of scopes: - * - * - Scopes can be nested. A scope (prototypically) inherits properties from its parent scope. - * - Scopes can be attached (bound) to the HTML DOM tree (the view). - * - A scope {@link angular.scope.$become becomes} `this` for a controller. - * - A scope's {@link angular.scope.$eval $eval} is used to update its view. - * - Scopes can {@link angular.scope.$watch $watch} properties and fire events. - * - * # Basic Operations - * Scopes can be created by calling {@link angular.scope angular.scope()} or by compiling HTML. - * - * {@link angular.widget Widgets} and data bindings register listeners on the current scope to be - * notified of changes to the scope state. When notified, these listeners push the updated state - * through to the DOM. - * - * Here is a simple scope snippet to show how you can interact with the scope. - * <pre> - var scope = angular.scope(); - scope.salutation = 'Hello'; - scope.name = 'World'; - - expect(scope.greeting).toEqual(undefined); - - scope.$watch('name', function(){ - this.greeting = this.salutation + ' ' + this.name + '!'; - }); - - expect(scope.greeting).toEqual('Hello World!'); - scope.name = 'Misko'; - // scope.$eval() will propagate the change to listeners - expect(scope.greeting).toEqual('Hello World!'); - - scope.$eval(); - expect(scope.greeting).toEqual('Hello Misko!'); - * </pre> - * - * # Inheritance - * A scope can inherit from a parent scope, as in this example: - * <pre> - var parent = angular.scope(); - var child = angular.scope(parent); - - parent.salutation = "Hello"; - child.name = "World"; - expect(child.salutation).toEqual('Hello'); - - child.salutation = "Welcome"; - expect(child.salutation).toEqual('Welcome'); - expect(parent.salutation).toEqual('Hello'); - * </pre> - * - * # Dependency Injection - * Scope also acts as a simple dependency injection framework. - * - * **TODO**: more info needed - * - * # When scopes are evaluated - * Anyone can update a scope by calling its {@link angular.scope.$eval $eval()} method. By default - * angular widgets listen to user change events (e.g. the user enters text into a text field), copy - * the data from the widget to the scope (the MVC model), and then call the `$eval()` method on the - * root scope to update dependents. This creates a spreadsheet-like behavior: the bound views update - * immediately as the user types into the text field. + * scopes as JavaScript objects that have extra APIs for registering watchers. A scope is the + * context in which model (from the model-view-controller design pattern) exists. * - * Similarly, when a request to fetch data from a server is made and the response comes back, the - * data is written into the model and then $eval() is called to push updates through to the view and - * any other dependents. + * Angular scope objects provide the following methods: * - * Because a change in the model that's triggered either by user input or by server response calls - * `$eval()`, it is unnecessary to call `$eval()` from within your controller. The only time when - * calling `$eval()` is needed is when implementing a custom widget or service. + * * {@link angular.Scope.$become $become()} - + * * {@link angular.Scope.$bind $bind()} - + * * {@link angular.Scope.$eval $eval()} - + * * {@link angular.Scope.$get $get()} - + * * {@link angular.Scope.$new $new()} - + * * {@link angular.Scope.$onEval $onEval()} - + * * {@link angular.Scope.$service $service()} - + * * {@link angular.Scope.$set $set()} - + * * {@link angular.Scope.$tryEval $tryEval()} - + * * {@link angular.Scope.$watch $watch()} - * - * Because scopes are inherited, the child scope `$eval()` overrides the parent `$eval()` method. - * So to update the whole page you need to call `$eval()` on the root scope as `$root.$eval()`. - * - * Note: A widget that creates scopes (i.e. {@link angular.widget.@ng:repeat ng:repeat}) is - * responsible for forwarding `$eval()` calls from the parent to those child scopes. That way, - * calling $eval() on the root scope will update the whole page. - * - * - * @TODO THESE PARAMS AND RETURNS ARE NOT RENDERED IN THE TEMPLATE!! FIX THAT! - * @param {Object} parent The scope that should become the parent for the newly created scope. - * @param {Object.<string, function()>=} providers Map of service factory which need to be provided - * for the current scope. Usually {@link angular.service}. - * @param {Object.<string, *>=} instanceCache Provides pre-instantiated services which should - * append/override services provided by `providers`. - * @returns {Object} Newly created scope. - * - * - * @example - * This example demonstrates scope inheritance and property overriding. - * - * In this example, the root scope encompasses the whole HTML DOM tree. This scope has `salutation`, - * `name`, and `names` properties. The {@link angular.widget.@ng:repeat ng:repeat} creates a child - * scope, one for each element in the names array. The repeater also assigns $index and name into - * the child scope. - * - * Notice that: - * - * - While the name is set in the child scope it does not change the name defined in the root scope. - * - The child scope inherits the salutation property from the root scope. - * - The $index property does not leak from the child scope to the root scope. - * - <doc:example> - <doc:source> - <ul ng:init="salutation='Hello'; name='Misko'; names=['World', 'Earth']"> - <li ng:repeat="name in names"> - {{$index}}: {{salutation}} {{name}}! - </li> - </ul> - <pre> - $index={{$index}} - salutation={{salutation}} - name={{name}}</pre> - </doc:source> - <doc:scenario> - it('should inherit the salutation property and override the name property', function() { - expect(using('.doc-example-live').repeater('li').row(0)). - toEqual(['0', 'Hello', 'World']); - expect(using('.doc-example-live').repeater('li').row(1)). - toEqual(['1', 'Hello', 'Earth']); - expect(using('.doc-example-live').element('pre').text()). - toBe(' $index=\n salutation=Hello\n name=Misko'); - }); - </doc:scenario> - </doc:example> + * For more information about how angular scope objects work,, see {@link guide/scopes Angular Scope + * Objects} in the angular Developer Guide. */ function createScope(parent, providers, instanceCache) { function Parent(){} diff --git a/src/angular-mocks.js b/src/angular-mocks.js index f0313b25..ba7f7461 100644 --- a/src/angular-mocks.js +++ b/src/angular-mocks.js @@ -57,14 +57,21 @@ /** + * @workInProgress * @ngdoc overview * @name angular.mock - * @namespace Namespace for all built-in angular mocks. - * * @description - * `angular.mock` is a namespace for all built-in mocks that ship with angular and automatically - * replace real services if `angular-mocks.js` file is loaded after `angular.js` and before any - * tests. + * + * The `angular.mock` object is a namespace for all built-in mock services that ship with angular. + * It automatically replaces real services if the `angular-mocks.js` file is loaded after + * `angular.js` and before any tests. + * + * Built-in mocks: + * + * * {@link angular.Mock.service.$browser $browser } - A mock implementation of the browser. + * * {@link angular.Mock.service.$exceptionHandler $exceptionHandler } - A mock implementation of the + * angular service exception handler. + * * {@link angular.Mock.service.$log $log } - A mock implementation of the angular service log. */ angular.mock = {}; diff --git a/src/apis.js b/src/apis.js index 0f2968e6..237a1c1c 100644 --- a/src/apis.js +++ b/src/apis.js @@ -18,17 +18,21 @@ var angularGlobal = { * @function * * @description - * `angular.Object` is a namespace for utility functions for manipulation with JavaScript objects. + * A namespace for utility functions used to work with JavaScript objects. These functions are + * exposed in two ways: * - * These functions are exposed in two ways: - * - * - **in angular expressions**: the functions are bound to all objects and augment the Object - * type. The names of these methods are prefixed with `$` character 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, e.g, `myObject.$foo(param2)`. * - * - **in JavaScript code**: the 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. */ var angularCollection = { 'copy': copy, @@ -44,21 +48,32 @@ var angularObject = { * @name angular.Array * * @description - * `angular.Array` is a namespace for utility functions for manipulation of JavaScript `Array` - * objects. + * A namespace for utility functions for the manipulation of JavaScript Array objects. * * These functions are exposed in two ways: * - * - **in angular expressions**: the 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 $ 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. * - * Because `Array` type is a subtype of the Object type, all {@link angular.Object} functions - * augment 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)`. * - * - **in JavaScript code**: the functions don't 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: * + * * {@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 */ var angularArray = { diff --git a/src/directives.js b/src/directives.js index f98f3421..07c8fdc1 100644 --- a/src/directives.js +++ b/src/directives.js @@ -1,5 +1,47 @@ /** * @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 widget widgets}. + * + * 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: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-even ng:class-even} - Like `ng:class`, but works in + * conjunction with {@link 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 + * 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:controller ng:controller} - Creates a scope object linked to the + * DOM element and assigns behavior to the scope. + * * {@link angular.Directive.ng:eval ng:eval} - Executes a binding but blocks output. + * * {@link angular.Directive.ng:eval-order ng:eval-order} - Change evaluation order when updating + * the view. + * * {@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: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:style ng:style} - Conditionally set CSS styles on an element. + * * {@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/directives Understanding Angular Directives} in the angular Developer Guide. + */ + +/** + * @workInProgress * @ngdoc directive * @name angular.directive.ng:init * diff --git a/src/filters.js b/src/filters.js index f7a4909d..d77adc57 100644 --- a/src/filters.js +++ b/src/filters.js @@ -1,5 +1,31 @@ /** * @workInProgress + * @ngdoc overview + * @name angular.filter + * @description + * + * Filters are used for formatting data displayed to the user. + * + * The general syntax in templates is as follows: + * + * {{ expression | [ filter_name ] }} + * + * Following is the list of built-in angular filters: + * + * * {@link angular.Filter.currency currency} + * * {@link angular.Filter.date date} + * * {@link angular.Filter.html html} + * * {@link angular.Filter.json json} + * * {@link angular.Filter.linky linky} + * * {@link angular.Filter.lowercase lowercase} + * * {@link angular.Filter.number number} + * * {@link angular.Filter.uppercase uppercase} + * + * For more information about how angular filters work, and how to create your own filters, see {@link guide/filters Understanding Angular Filters} in the angular Developer Guide. + */ + +/** + * @workInProgress * @ngdoc filter * @name angular.filter.currency * @function diff --git a/src/formatters.js b/src/formatters.js index 02773be1..d9b0a9fe 100644 --- a/src/formatters.js +++ b/src/formatters.js @@ -1,3 +1,25 @@ +/** + * @workInProgress + * @ngdoc overview + * @name angular.formatter + * @description + * + * Formatters are used for translating data formats between those used in for display and those used + * for storage. + * + * Following is the list of built-in angular formatters: + * + * * {@link angular.Formatter.boolean boolean} - Formats user input in boolean format + * * {@link angular.Formatter.index index} - Manages indexing into an HTML select widget + * * {@link angular.Formatter.json json} - Formats user input in JSON format + * * {@link angular.Formatter.list list} - Formats user input string as an array + * * {@link angular.Formatter.number} - Formats user input strings as a number + * * {@link angular.Formatter.trim} - Trims extras spaces from end of user input + * + * For more information about how angular formatters work, and how to create your own formatters, + * see {@link guide/filters Understanding Angular Formatters} in the angular Developer Guide. + */ + function formatter(format, parse) {return {'format':format, 'parse':parse || format};} function toString(obj) { return (isDefined(obj) && obj !== null) ? "" + obj : obj; diff --git a/src/validators.js b/src/validators.js index de67a965..db5d01f3 100644 --- a/src/validators.js +++ b/src/validators.js @@ -1,3 +1,33 @@ +/** + * @workInProgress + * @ngdoc overview + * @name angular.validator + * @description + * + * Most of the built-in angular validators are used to check user input against defined types or + * patterns. You can easily create your own custom validators as well. + * + * Following is the list of built-in angular validators: + * + * * {@link angular.Validator.asynchronous asynchronous()} - Provides asynchronous validation via a + * callback function. + * * {@link angular.Validator.date date()} - Checks user input against default date format: + * "MM/DD/YYYY" + * * {@link angular.Validator.email email()} - Validates that user input is a well-formed email + * address. + * * {@link angular.Validator.integer integer()} - Validates that user input is an integer + * * {@link angular.Validator.json json()} - Validates that user input is valid JSON + * * {@link angular.Validator.number number()} - Validates that user input is a number + * * {@link angular.Validator.phone phone()} - Validates that user input matches the pattern + * "1(123)123-1234" + * * {@link angular.Validator.regexp regexp()} - Restricts valid input to a specified regular + * expression pattern + * * {@link angular.Validator.url url()} - Validates that user input is a well-formed URL. + * + * For more information about how angular validators work, and how to create your own validators, + * see {@link guide/validators Understanding Angular Validators} in the angular Developer Guide. + */ + extend(angularValidator, { 'noop': function() { return null; }, diff --git a/src/widgets.js b/src/widgets.js index 1cd7211f..c923b551 100644 --- a/src/widgets.js +++ b/src/widgets.js @@ -1,5 +1,32 @@ /** * @workInProgress + * @ngdoc overview + * @name angular.widget + * @description + * + * Widgets are custom DOM elements. An angular widget can be either a custom + * attribute that modifies an existing DOM elements or an entirely new DOM element. + * + * Following is the list of built-in angular widgets: + * + * * {@link angular.Widget.@ng:format ng:format} - Formats data for display to user and for storage. + * * {@link angular.Widget.@ng:non-bindable ng:non-bindable} - Blocks angular from processing an + * HTML element. + * * {@link angular.Widget.@ng:repeat ng:repeat} - Creates and manages a collection of cloned HTML + * elements. + * * {@link angular.Widget.@ng:required ng:required} - Verifies presence of user input. + * * {@link angular.Widget.@ng:validate ng:validate} - Validates content of user input. + * * {@link angular.Widget.HTML HTML} - Standard HTML processed by angular. + * * {@link angular.Widget.ng:view ng:view} - Works with $route to "include" partial templates + * * {@link angular.Widget.ng:switch ng:switch} - Conditionally changes DOM structure + * * {@link angular.Widget.ng:include ng:include} - Includes an external HTML fragment + * + * For more information about angular widgets, see {@link guide/widgets Understanding Angular + * Widgets} in the angular Developer Guide. + */ + +/** + * @workInProgress * @ngdoc widget * @name angular.widget.HTML * |