diff options
| -rw-r--r-- | docs/content/api/angular.filter.ngdoc | 87 | ||||
| -rw-r--r-- | docs/content/api/angular.formatter.ngdoc | 82 | ||||
| -rw-r--r-- | docs/content/api/angular.service.ngdoc | 195 | ||||
| -rw-r--r-- | docs/content/api/angular.validator.ngdoc | 77 | ||||
| -rw-r--r-- | docs/content/api/angular.widget.ngdoc | 78 | ||||
| -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 |
13 files changed, 376 insertions, 497 deletions
diff --git a/docs/content/api/angular.filter.ngdoc b/docs/content/api/angular.filter.ngdoc deleted file mode 100644 index 5d4f5940..00000000 --- a/docs/content/api/angular.filter.ngdoc +++ /dev/null @@ -1,87 +0,0 @@ -@workInProgress -@ngdoc overview -@name angular.filter -@namespace Namespace for all filters. -@description -# Overview -Filters are a standard way to format your data for display to the user. For example, you -might have the number 1234.5678 and would like to display it as US currency: $1,234.57. -Filters allow you to do just that. In addition to transforming the data, filters also modify -the DOM. This allows the filters to for example apply css styles to the filtered output if -certain conditions were met. - - -# Standard Filters - -The Angular framework provides a standard set of filters for common operations, including: -{@link angular.filter.currency currency}, {@link angular.filter.json json}, -{@link angular.filter.number number}, and {@link angular.filter.html html}. You can also add -your own filters. - - -# Syntax - -Filters can be part of any {@link angular.scope} evaluation but are typically used with -{{bindings}}. Filters typically transform the data to a new data type, formating the data in -the process. Filters can be chained and take optional arguments. Here are few examples: - -* No filter: {{1234.5678}} => 1234.5678 -* Number filter: {{1234.5678|number}} => 1,234.57. Notice the “,” and rounding to two - significant digits. -* Filter with arguments: {{1234.5678|number:5}} => 1,234.56780. Filters can take optional - arguments, separated by colons in a binding. To number, the argument “5” requests 5 digits - to the right of the decimal point. - - -# Writing your own Filters - -Writing your own filter is very easy: just define a JavaScript function on `angular.filter`. -The framework passes in the input value as the first argument to your function. Any filter -arguments are passed in as additional function arguments. - -You can use these variables in the function: - -* `this` — The current scope. -* `this.$element` — The DOM element containing the binding. This allows the filter to manipulate - the DOM in addition to transforming the input. - - -@example - The following example filter reverses a text string. In addition, it conditionally makes the - text upper-case (to demonstrate optional arguments) and assigns color (to demonstrate DOM - modification). - -<doc:example> - <doc:source> - <script type="text/javascript"> - angular.filter('reverse', function(input, uppercase, color) { - var out = ""; - for (var i = 0; i < input.length; i++) { - out = input.charAt(i) + out; - } - if (uppercase) { - out = out.toUpperCase(); - } - if (color) { - this.$element.css('color', color); - } - return out; - }); - </script> - - <input name="text" type="text" value="hello" /><br> - No filter: {{text}}<br> - Reverse: {{text|reverse}}<br> - Reverse + uppercase: {{text|reverse:true}}<br> - Reverse + uppercase + blue: {{text|reverse:true:"blue"}} - </doc:source> - <doc:scenario> - it('should reverse text', function(){ - expect(binding('text|reverse')).toEqual('olleh'); - input('text').enter('ABC'); - expect(binding('text|reverse')).toEqual('CBA'); - }); - </doc:scenario> -</doc:example> - - diff --git a/docs/content/api/angular.formatter.ngdoc b/docs/content/api/angular.formatter.ngdoc deleted file mode 100644 index 4eef190e..00000000 --- a/docs/content/api/angular.formatter.ngdoc +++ /dev/null @@ -1,82 +0,0 @@ -@workInProgress -@ngdoc overview -@name angular.formatter -@namespace Namespace for all formats. -@description -# Overview -The formatters are responsible for translating user readable text in an input widget to a -data model stored in an application. - -# Writting your own Formatter -Writing your own formatter is easy. Just register a pair of JavaScript functions with -`angular.formatter`. One function for parsing user input text to the stored form, -and one for formatting the stored data to user-visible text. - -Here is an example of a "reverse" formatter: The data is stored in uppercase and in -reverse, while it is displayed in lower case and non-reversed. User edits are -automatically parsed into the internal form and data changes are automatically -formatted to the viewed form. - -<pre> -function reverse(text) { - var reversed = []; - for (var i = 0; i < text.length; i++) { - reversed.unshift(text.charAt(i)); - } - return reversed.join(''); -} - -angular.formatter('reverse', { - parse: function(value){ - return reverse(value||'').toUpperCase(); - }, - format: function(value){ - return reverse(value||'').toLowerCase(); - } -}); -</pre> - -@example -<doc:example> - <doc:source> - <script type="text/javascript"> - function reverse(text) { - var reversed = []; - for (var i = 0; i < text.length; i++) { - reversed.unshift(text.charAt(i)); - } - return reversed.join(''); - } - - angular.formatter('reverse', { - parse: function(value){ - return reverse(value||'').toUpperCase(); - }, - format: function(value){ - return reverse(value||'').toLowerCase(); - } - }); - </script> - - Formatted: - <input type="text" name="data" value="angular" ng:format="reverse"/> - <br/> - - Stored: - <input type="text" name="data"/><br/> - <pre>{{data}}</pre> - </doc:source> - <doc:scenario> - it('should store reverse', function(){ - expect(element('.doc-example-live input:first').val()).toEqual('angular'); - expect(element('.doc-example-live input:last').val()).toEqual('RALUGNA'); - - this.addFutureAction('change to XYZ', function($window, $document, done){ - $document.elements('.doc-example-live input:last').val('XYZ').trigger('change'); - done(); - }); - expect(element('.doc-example-live input:first').val()).toEqual('zyx'); - }); - </doc:scenario> -</doc:example> - diff --git a/docs/content/api/angular.service.ngdoc b/docs/content/api/angular.service.ngdoc index 9a191921..0d3406e5 100644 --- a/docs/content/api/angular.service.ngdoc +++ b/docs/content/api/angular.service.ngdoc @@ -1,32 +1,175 @@ @workInProgress @ngdoc overview @name angular.service + @description +# Overview +Services are substituable objects, which are wired together using dependency injection (DI). +Each service could have dependencies (other services), which are passed in constructor. +Because JS is dynamicaly typed language, dependency injection can not use static types +to identify these dependencies, so each service must explicitely define its dependencies. +This is done by `$inject` property. + + +# Built-in services +angular provides a set of services for common operations. These services can be overriden by custom +services if needed. + +Like other core angular variables and identifiers, the built-in services always start with `$`. + + * {@link angular.service.$browser $browser} + * {@link angular.service.$window $window} + * {@link angular.service.$document $document} + * {@link angular.service.$location $location} + * {@link angular.service.$log $log} + * {@link angular.service.$exceptionHandler $exceptionHandler} + * {@link angular.service.$hover $hover} + * {@link angular.service.$invalidWidgets $invalidWidgets} + * {@link angular.service.$route $route} + * {@link angular.service.$xhr $xhr} + * {@link angular.service.$xhr.error $xhr.error} + * {@link angular.service.$xhr.bulk $xhr.bulk} + * {@link angular.service.$xhr.cache $xhr.cache} + * {@link angular.service.$resource $resource} + * {@link angular.service.$cookies $cookies} + * {@link angular.service.$cookieStore $cookieStore} + +# Writing your own custom services +angular provides only set of basic services, so for any nontrivial application it will be necessary +to write one or more custom services. To do so, a factory function that creates a services needs to +be registered with angular's dependency injector. This factory function must return an object - the +service (it is not called with the `new` operator). + +**angular.service** accepts three parameters: + + - `{string} name` - Name of the service. + - `{function()} factory` - Factory function (called just once by DI). + - `{Object} config` - Configuration object with following properties: + - `$inject` - {Array.<string>} - Array of service ids that this service depends on. These + services will be passed as arguments into the factory function in the same order as specified + in the `$inject` array. Defaults to `[]`. + - `$eager` - {boolean} - If true, the service factory will be called and thus, the service will + be instantiated when angular boots. If false, service will be lazily instantiated when it is + first requested during instantiation of a dependant. Defaults to `false`. + +The `this` of the factory function is bound to the root scope of the angular application. + +angular enables services to participate in dependency injection (DI) by registering themselves with +angular's DI system (injector) under a `name` (id) as well as by declaring dependencies which need +to be provided for the factory function of the registered service. The ability to swap dependencies +for mocks/stubs/dummies in tests allows for services to be highly testable. + +Here is an example of very simple service. This service requires $window service (it's +passed as a parameter to factory function) and it's just a function. + +This service simple stores all notifications and after third one, it displays all of them by +window alert. +<pre> + angular.service('notify', function(win) { + var msgs = []; + return function(msg) { + msgs.push(msg); + if (msgs.length == 3) { + win.alert(msgs.join("\n")); + msgs = []; + } + }; + }, {$inject: ['$window']}); +</pre> + +And here is a unit test for this service. We use Jasmine spy (mock) instead of real browser's alert. +<pre> +var mock, notify; + +beforeEach(function() { + mock = {alert: jasmine.createSpy()}; + notify = angular.service('notify')(mock); +}); + +it('should not alert first two notifications', function() { + notify('one'); + notify('two'); + expect(mock.alert).not.toHaveBeenCalled(); +}); + +it('should alert all after third notification', function() { + notify('one'); + notify('two'); + notify('three'); + expect(mock.alert).toHaveBeenCalledWith("one\ntwo\nthree"); +}); + +it('should clear messages after alert', function() { + notify('one'); + notify('two'); + notify('third'); + notify('more'); + notify('two'); + notify('third'); + expect(mock.alert.callCount).toEqual(2); + expect(mock.alert.mostRecentCall.args).toEqual(["more\ntwo\nthird"]); +}); +</pre> + +# Injecting services into controllers +Using services as dependencies for controllers is very similar to using them as dependencies for +another service. + +JavaScript is dynamic language, so DI is not able to figure out which services to inject by +static types (like in static typed languages). Therefore you must specify the service name +by the `$inject` property - it's an array that contains strings with names of services to be +injected. The name must match the id that service has been registered as with angular. +The order of the services in the array matters, because this order will be used when calling +the factory function with injected parameters. The names of parameters in factory function +don't matter, but by convention they match the service ids. +<pre> +function myController($loc, $log) { + this.firstMethod = function() { + // use $location service + $loc.setHash(); + }; + this.secondMethod = function() { + // use $log service + $log.info('...'); + }; +} +// which services to inject ? +myController.$inject = ['$location', '$log']; +</pre> + +@example +<doc:example> + <doc:source> + <script type="text/javascript"> + angular.service('notify', function(win) { + var msgs = []; + return function(msg) { + msgs.push(msg); + if (msgs.length == 3) { + win.alert(msgs.join("\n")); + msgs = []; + } + }; + }, {$inject: ['$window']}); + + function myController(notifyService) { + this.callNotify = function(msg) { + notifyService(msg); + }; + } + myController.$inject = ['notify']; + </script> -The services API provides objects for carrying out common web app tasks. Service objects are -managed by angular's {@link guide/dev_guide.di dependency injection system}. - - -* {@link angular.service.$browser $browser } - Provides an instance of a browser object -* {@link angular.service.$cookieStore $cookieStore } - Provides key / value storage backed by -session cookies -* {@link angular.service.$cookies $cookies } - Provides read / write access to browser cookies -* {@link angular.service.$defer $defer } - Defers function execution and try / catch block -* {@link angular.service.$document $document } - Provides reference to `window.document` element -* {@link angular.service.$exceptionHandler $exceptionHandler } - Receives uncaught angular -exceptions -* {@link angular.service.$hover $hover } - -* {@link angular.service.$invalidWidgets $invalidWidgets } - Holds references to invalid widgets -* {@link angular.service.$location $location } - Parses the browser location URL -* {@link angular.service.$log $log } - Provides logging service -* {@link angular.service.$resource $resource } - Creates objects for interacting with RESTful -server-side data sources -* {@link angular.service.$route $route } - Provides deep-linking services -* {@link angular.service.$updateView $updateView } - Queues view updates -* {@link angular.service.$window $window } - References the browsers `window` object -* {@link angular.service.$xhr $xhr} - Generates an XHR request. - - -For information on how angular services work and how to write your own services, see {@link -guide/dev_guide.services Angular Services} in the angular Developer Guide. + <div ng:controller="myController"> + <p>Let's try this simple notify service, injected into the controller...</p> + <input ng:init="message='test'" type="text" name="message" /> + <button ng:click="callNotify(message);">NOTIFY</button> + </div> + </doc:source> + <doc:scenario> + it('should test service', function(){ + expect(element(':input[name=message]').val()).toEqual('test'); + }); + </doc:scenario> +</doc:example> diff --git a/docs/content/api/angular.validator.ngdoc b/docs/content/api/angular.validator.ngdoc deleted file mode 100644 index 96b1e76a..00000000 --- a/docs/content/api/angular.validator.ngdoc +++ /dev/null @@ -1,77 +0,0 @@ -@workInProgress -@ngdoc overview -@name angular.validator -@namespace Namespace for all filters. -@description -# Overview -Validators are a standard way to check the user input against a specific criteria. For -example, you might need to check that an input field contains a well-formed phone number. - -# Syntax -Attach a validator on user input widgets using the `ng:validate` attribute. - -<doc:example> - <doc:source> - Change me: <input type="text" name="number" ng:validate="integer" value="123"> - </doc:source> - <doc:scenario> - it('should validate the default number string', function() { - expect(element('input[name=number]').attr('class')). - not().toMatch(/ng-validation-error/); - }); - it('should not validate "foo"', function() { - input('number').enter('foo'); - expect(element('input[name=number]').attr('class')). - toMatch(/ng-validation-error/); - }); - </doc:scenario> -</doc:example> - - -# Writing your own Validators -Writing your own validator is easy. To make a function available as a -validator, just define the JavaScript function on the `angular.validator` -object. <angular/> passes in the input to validate as the first argument -to your function. Any additional validator arguments are passed in as -additional arguments to your function. - -You can use these variables in the function: - -* `this` — The current scope. -* `this.$element` — The DOM element containing the binding. This allows the filter to manipulate - the DOM in addition to transforming the input. - -In this example we have written a upsTrackingNo validator. -It marks the input text "valid" only when the user enters a well-formed -UPS tracking number. - -@css ng-validation-error - When validation fails, this css class is applied to the binding, making its borders red by - default. - -@example -<doc:example> - <doc:source> - <script> - angular.validator('upsTrackingNo', function(input, format) { - var regexp = new RegExp("^" + format.replace(/9/g, '\\d') + "$"); - return input.match(regexp)?"":"The format must match " + format; - }); - </script> - <input type="text" name="trackNo" size="40" - ng:validate="upsTrackingNo:'1Z 999 999 99 9999 999 9'" - value="1Z 123 456 78 9012 345 6"/> - </doc:source> - <doc:scenario> - it('should validate correct UPS tracking number', function() { - expect(element('input[name=trackNo]').attr('class')). - not().toMatch(/ng-validation-error/); - }); - - it('should not validate in correct UPS tracking number', function() { - input('trackNo').enter('foo'); - expect(element('input[name=trackNo]').attr('class')). - toMatch(/ng-validation-error/); - }); - </doc:scenario> -</doc:example> diff --git a/docs/content/api/angular.widget.ngdoc b/docs/content/api/angular.widget.ngdoc deleted file mode 100644 index 5fd7b259..00000000 --- a/docs/content/api/angular.widget.ngdoc +++ /dev/null @@ -1,78 +0,0 @@ -@workInProgress -@ngdoc overview -@name angular.widget -@namespace Namespace for all widgets. -@description -# Overview -Widgets allow you to create DOM elements that the browser doesn't -already understand. You create the widget in your namespace and -assign it behavior. You can only bind one widget per DOM element -(unlike directives, in which you can use any number per DOM -element). Widgets are expected to manipulate the DOM tree by -adding new elements whereas directives are expected to only modify -element properties. - -Widgets come in two flavors: element and attribute. - -# Element Widget -Let's say we would like to create a new element type in the -namespace `my` that can watch an expression and alert() the user -with each new value. - -<pre> -<my:watch exp="name"/> -</pre> - -You can implement `my:watch` like this: -<pre> -angular.widget('my:watch', function(compileElement) { - var compiler = this; - var exp = compileElement.attr('exp'); - return function(linkElement) { - var currentScope = this; - currentScope.$watch(exp, function(value){ - alert(value); - }); - }; -}); -</pre> - -# Attribute Widget -Let's implement the same widget, but this time as an attribute -that can be added to any existing DOM element. -<pre> -<div my:watch="name">text</div> -</pre> -You can implement `my:watch` attribute like this: -<pre> -angular.widget('@my:watch', function(expression, compileElement) { - var compiler = this; - return function(linkElement) { - var currentScope = this; - currentScope.$watch(expression, function(value){ - alert(value); - }); - }; -}); -</pre> - -@example -<doc:example> - <doc:source> - <script> - angular.widget('my:time', function(compileElement){ - compileElement.css('display', 'block'); - return function(linkElement){ - function update(){ - linkElement.text('Current time is: ' + new Date()); - setTimeout(update, 1000); - } - update(); - }; - }); - </script> - <my:time></my:time> - </doc:source> - <doc:scenario> - </doc:scenario> -</doc:example> 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 * |