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

api doc fixes from ken

Browse source
This commit is contained in:
Igor Minar 2011-06-06 14:44:49 -07:00
parent bd9a7b9fd7
commit 3069566073
13 changed files with 372 additions and 493 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

87
docs/content/api/angular.filter.ngdoc
View file

@ -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>

82
docs/content/api/angular.formatter.ngdoc
View file

@ -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>

187
docs/content/api/angular.service.ngdoc
View file

@ -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.
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}.
# 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 } - 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.
* {@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).
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.
**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>
<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>

77
docs/content/api/angular.validator.ngdoc
View file

@ -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>

78
docs/content/api/angular.widget.ngdoc
View file

@ -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>
&lt;my:watch exp="name"/&gt;
</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>
&lt;div my:watch="name"&gt;text&lt;/div&gt;
</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>

141
src/Scope.js
View file

@ -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.
* 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.
*
* A few other characteristics of scopes:
* Angular scope objects provide the following methods:
*
* - 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.
* * {@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()} -
*
* # 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.
*
* 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.
*
* 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.
*
* 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(){}

17
src/angular-mocks.js vendored
View file

@ -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 = {};

49
src/apis.js
View file

@ -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:
* __* 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 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)`.
*
* - **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 {@link angular.Object} functions
* augment the `Array` type in angular expressions as well.
* Because Array type is a subtype of the Object type, all angular.Object functions augment
* theArray type in angular expressions as well.
*
* - **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)`.
* * __JavaScript code:__ 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 = {

42
src/directives.js
View file

@ -1,3 +1,45 @@
/**
* @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

26
src/filters.js
View file

@ -1,3 +1,29 @@
/**
* @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

22
src/formatters.js
View file

@ -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;

30
src/validators.js
View file

@ -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; },

27
src/widgets.js
View file

@ -1,3 +1,30 @@
/**
* @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