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

yet another docs batch

Browse source
This commit is contained in:
Igor Minar 2011-06-06 22:02:30 -07:00
parent 805bb5bb6e
commit c35b0a7907
48 changed files with 278 additions and 1854 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

15
docs/content/api/angular.attrMarkup.ngdoc
View file

@ -1,15 +0,0 @@
@workInProgress
@ngdoc overview
@name angular.attrMarkup
@description
Attribute markup extends the angular compiler in a very similar way as {@link angular.markup} except
that it allows you to modify the state of the attribute text rather then the content of a node.
<pre>
angular.attrMarkup('extraClass', function(attrValue, attrName, element){
if (attrName == 'additional-class') {
element.addClass(attrValue);
}
});
</pre>

53
docs/content/api/angular.directive.ngdoc
View file

@ -1,53 +0,0 @@
@workInProgress
@ngdoc overview
@name angular.directive
@namespace Namespace for all directives.
@description
A directive is an HTML attribute that you can use in an existing HTML element type or in a
DOM element type that you create as {@link angular.widget}, to modify that element's
properties. You can use any number of directives per element.
For example, you can add the ng:bind directive as an attribute of an HTML span element, as in
`<span ng:bind="1+2"></span>`. How does this work? The compiler passes the attribute value
`1+2` to the ng:bind extension, which in turn tells the {@link angular.scope} to watch that
expression and report changes. On any change it sets the span text to the expression value.
Here's how to define {@link angular.directive.ng:bind ng:bind}:
<pre>
angular.directive('ng:bind', function(expression, compiledElement) {
var compiler = this;
return function(linkElement) {
var currentScope = this;
currentScope.$watch(expression, function(value) {
linkElement.text(value);
});
};
});
</pre>
# Directive vs. Attribute Widget
Both [attribute widgets](#!angular.widget) and directives can compile a DOM element
attribute. So why have two different ways to do the same thing? The answer is that order
matters, but we have no control over the order in which attributes are read. To solve this
we apply attribute widget before the directive.
For example, consider this piece of HTML, which uses the `ng:repeat`, `ng:init`,
and `ng:bind` widget and directives:
<pre>
<ul ng:init="people=['mike', 'mary']">
<li ng:repeat="person in people" ng:init="a=a+1" ng:bind="person"></li>
</ul>
</pre>
Notice that the order of execution matters here. We need to execute
{@link angular.widget.@ng:repeat ng:repeat} before we run the
{@link angular.directive.ng:init ng:init} and `ng:bind` on the `<li/>;`. This is because we
want to run the `ng:init="a=a+1` and `ng:bind="person"` once for each person in people. We
could not have used directive to create this template because attributes are read in an
unspecified order and there is no way of guaranteeing that the repeater attribute would
execute first. Using the `ng:repeat` attribute directive ensures that we can transform the
DOM element into a template.
Widgets run before directives. Widgets may manipulate the DOM whereas directives are not
expected to do so, and so they run last.

49
docs/content/api/angular.element.ngdoc
View file

@ -1,49 +0,0 @@
@workInProgress
@ngdoc function
@name angular.element
@function
@description
Wraps a raw DOM element or HTML string as [jQuery](http://jquery.com) element.
`angular.element` is either an alias for [jQuery](http://api.jquery.com/jQuery/) function if
jQuery is loaded or a function that wraps the element or string in angular's jQuery lite
implementation.
Real jQuery always takes precedence (as long as it was loaded before `DOMContentEvent`)
Angular's jQuery lite implementation is a tiny API-compatible subset of jQuery which allows
angular to manipulate DOM. The jQuery lite implements only a subset of jQuery api, with the
focus on the most commonly needed functionality and minimal footprint. For this reason only a
limited number of jQuery methods, arguments and invocation styles are supported.
NOTE: All element references in angular are always wrapped with jQuery (lite) and are never
raw DOM references.
## Angular's jQuery lite implements these functions:
- [addClass()](http://api.jquery.com/addClass/)
- [after()](http://api.jquery.com/after/)
- [append()](http://api.jquery.com/append/)
- [attr()](http://api.jquery.com/attr/)
- [bind()](http://api.jquery.com/bind/)
- [children()](http://api.jquery.com/children/)
- [clone()](http://api.jquery.com/clone/)
- [css()](http://api.jquery.com/css/)
- [data()](http://api.jquery.com/data/)
- [hasClass()](http://api.jquery.com/hasClass/)
- [parent()](http://api.jquery.com/parent/)
- [remove()](http://api.jquery.com/remove/)
- [removeAttr()](http://api.jquery.com/removeAttr/)
- [removeClass()](http://api.jquery.com/removeClass/)
- [removeData()](http://api.jquery.com/removeData/)
- [replaceWith()](http://api.jquery.com/replaceWith/)
- [text()](http://api.jquery.com/text/)
- [trigger()](http://api.jquery.com/trigger/)
## Additionally these methods extend the jQuery and are available in both jQuery and jQuery lite
version:
- `scope()` - retrieves the current angular scope of the element.
@param {string|DOMElement} element HTML string or DOMElement to be wrapped into jQuery.
@returns {Object} jQuery object.

66
docs/content/api/angular.markup.ngdoc
View file

@ -1,66 +0,0 @@
@workInProgress
@ngdoc overview
@name angular.markup
@description
#Overview
Markups allow the angular compiler to transform content of DOM elements or portions of this content
into other text or DOM elements for further compilation. Markup extensions do not themselves produce
linking functions. Think of markup as a way to produce shorthand for a {@link angular.widget widget}
or a {@link angular.directive directive}.
#`{{}}` (double curly) built-in markup
`{{}}` markup is a built-in markup, which translates the enclosed expression into an
{@link angular.directive.ng:bind ng:bind} directive. It simply transforms
<pre>
{{expression}}
</pre>
to:
<pre>
<span ng:bind="expression"></span>
</pre>
For example `{{1+2}}` is easier to write and understand than `<span ng:bind="1+2"></span>`. The
expanded elements are then {@link guide.compiler compiled} normally.
# Custom markup
Let's say you want to define this shorthand for a horizontal rule: `---` for `<hr/>`.
In other words, this HTML:
<pre>
header
---
footer
</pre>
should translate to:
<pre>
header
<hr/>
footer
</pre>
Here's how the angular compiler could be extended to achieve this:
<pre>
angular.markup('---', function(text, textNode, parentElement) {
var compiler = this;
var index = text.indexOf('---');
if (index > -1) {
var before = compiler.text(text.substring(0, index));
var hr = compiler.element('hr');
var after = compiler.text(text.substring(index + 3));
textNode.after(after);
textNode.after(hr);
textNode.after(before);
textNode.remove();
}
});
</pre>
Unlike {@link angular.widget widgets} and {@link angular.directive directives}, in which the
compiler matches the name of handler function to a DOM element or attribute name, for markup the
compiler calls every markup handler for every text node, giving the handler a chance to transform
the text. The markup handler needs to find all the matches in the text.

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

@ -1,175 +1,32 @@
@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.
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}.
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}
* {@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.
# 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>
<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>
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.

1
docs/content/api/index.ngdoc
View file

@ -8,6 +8,7 @@
* {@link angular.widget Widgets} - Angular custom DOM element
* {@link angular.directive Directives} - Angular DOM element attributes
* {@link angular.markup Markup} and {@link angular.attrMarkup Attribute Markup}
* {@link angular.filter Filters} - Angular output filters
* {@link angular.formatter Formatters} - Angular converters for form elements
* {@link angular.validator Validators} - Angular input validators

2
docs/content/cookbook/deeplinking.ngdoc
View file

@ -44,11 +44,11 @@ In this example we have a simple app which consist of two screens:
The two partials are defined in the following URLs:
* {@link ./examples/settings.html}
* {@link ./examples/welcome.html}
<doc:example>
<doc:source>
<script>

2
docs/content/cookbook/form.ngdoc
View file

@ -109,7 +109,7 @@ ng:validate="regexp:zip"/><br/><br/>
# Things to notice
* The user data model is initialized {@link api/angular.directive.@ng:controller controller} and is
* The user data model is initialized {@link api/angular.directive.ng:controller controller} and is
available in
the {@link api/angular.scope scope} with the initial data.
* For debugging purposes we have included a debug view of the model to better understand what

105
docs/content/cookbook/formadvanced.ngdoc
View file

@ -1,105 +0,0 @@
@workInProgress
@ngdoc overview
@name Cookbook: Advanced Form
@description
Here we extend the basic form example to include common features such as reverting, dirty state
detection, and preventing invalid form submission.
<doc:example>
<doc:source>
<script>
UserForm.$inject = ['$invalidWidgets'];
function UserForm($invalidWidgets){
this.$invalidWidgets = $invalidWidgets;
this.state = /^\w\w$/;
this.zip = /^\d\d\d\d\d$/;
this.master = {
name: 'John Smith',
address:{
line1: '123 Main St.',
city:'Anytown',
state:'AA',
zip:'12345'
},
contacts:[
{type:'phone', value:'1(234) 555-1212'}
]
};
this.cancel();
}
UserForm.prototype = {
cancel: function(){
this.form = angular.copy(this.master);
},
save: function(){
this.master = this.form;
this.cancel();
}
};
</script>
<div ng:controller="UserForm">
<label>Name:</label><br/>
<input type="text" name="form.name" ng:required/> <br/><br/>
<label>Address:</label><br/>
<input type="text" name="form.address.line1" size="33" ng:required/> <br/>
<input type="text" name="form.address.city" size="12" ng:required/>,
<input type="text" name="form.address.state" size="2" ng:required ng:validate="regexp:state"/>
<input type="text" name="form.address.zip" size="5" ng:required ng:validate="regexp:zip"/><br/><br/>
<label>Phone:</label>
[ <a href="" ng:click="form.contacts.$add()">add</a> ]
<div ng:repeat="contact in form.contacts">
<select name="contact.type">
<option>email</option>
<option>phone</option>
<option>pager</option>
<option>IM</option>
</select>
<input type="text" name="contact.value" ng:required/>
[ <a href="" ng:click="form.contacts.$remove(contact)">X</a> ]
</div>
<button ng:click="cancel()" disabled="{{master.$equals(form)}}">Cancel</button>
<button ng:click="save()" disabled="{{$invalidWidgets.visible() || master.$equals(form)}}">Save</button>
<hr/>
Debug View:
<pre>form={{form}}
master={{master}}</pre>
</div>
</doc:source>
<doc:scenario>
it('should enable save button', function(){
expect(element(':button:contains(Save)').attr('disabled')).toBeTruthy();
input('form.name').enter('');
expect(element(':button:contains(Save)').attr('disabled')).toBeTruthy();
input('form.name').enter('change');
expect(element(':button:contains(Save)').attr('disabled')).toBeFalsy();
element(':button:contains(Save)').click();
expect(element(':button:contains(Save)').attr('disabled')).toBeTruthy();
});
it('should enable cancel button', function(){
expect(element(':button:contains(Cancel)').attr('disabled')).toBeTruthy();
input('form.name').enter('change');
expect(element(':button:contains(Cancel)').attr('disabled')).toBeFalsy();
element(':button:contains(Cancel)').click();
expect(element(':button:contains(Cancel)').attr('disabled')).toBeTruthy();
expect(element(':input[name=form.name]').val()).toEqual('John Smith');
});
</doc:scenario>
</doc:example>
#Things to notice
* Cancel & save buttons are only enabled if the form is dirty -- there is something to cancel or
save.
* Save button is only enabled if there are no validation errors on the form.
* Cancel reverts the form changes back to original state.
* Save updates the internal model of the form.
* Debug view shows the two models. One presented to the user form and the other being the pristine
copy master.

97
docs/content/guide/bootstrap.ngdoc
View file

@ -1,97 +0,0 @@
@workInProgress
@ngdoc overview
@name Developer Guide: Bootstrap
@description
# Bootstrap
This section explains how to bootstrap your application to the angular environment using either
the `angular.js` or `angular.min.js` script.
## The bootstrap code
Note that there are two versions of the bootstrap code that you can use:
* `angular-0.0.0.js` - this file is unobfuscated, uncompressed, and thus human-readable.
* `angular-0.0.0.min.js` - this is a compressed and obfuscated version of angular-debug.js.
In this section and throughout the Developer Guide, feel free to use `angular.min.js` instead of
`angular.js` when working through code examples.
## ng:autobind
The simplest way to get an angular application up and running is by inserting a script tag in your
HTML file that bootstraps the `angular.js` code and uses the special `ng:autobind` attribute,
like in this snippet of HTML:
<doc:example>
<doc:source>
Hello {{'World'}}!
</doc:source>
</doc:example>
The `ng:autobind` attribute tells angular to compile and manage the whole HTML document. The
compilation occurs in the page's onLoad handler. Note that you don't need to explicitly add an
onLoad event; auto bind mode takes care of all the magic for you.
## Manual bind
Using autobind mode is a handy way to start using angular, but advanced users who want more
control over the initialization process might prefer to use manual bind mode instead.
The best way to get started with manual bind mode is to look at the magic behind `ng:autobind`
by writing out each step of the autobind process explicitly. Note that the following code is
equivalent to the code in the previous section.
<pre>
<!DOCTYPE HTML>
<html xmlns:ng="http://angularjs.org">
<script type="text/javascript" src="http://code.angularjs.org/angular-0.0.0.min.js"></script>
<script type="text/javascript">
(function(window, previousOnLoad){
window.onload = function(){
try { (previousOnLoad||angular.noop)(); } catch(e) {}
angular.compile(window.document)();
};
})(window, window.onload);
</script>
<body>
Hello {{'World'}}!
</body>
</html>
</pre>
This is the sequence that your code should follow if you're writing your own manual binding code:
* After the page is loaded, find the root of the HTML template, which is typically the root of
the document.
* Run the HTML compiler, which converts the templates into an executable, bi-directionally
bound application.
# XML Namespace
**IMPORTANT:** When using angular you must declare the `ng` namespace using the `xmlns` tag.
If you don't declare the namespace, Internet Explorer does not render widgets properly.
<pre>
<html xmlns:ng="http://angularjs.org">
</pre>
# Create your own namespace
If you want to define your own widgets, you must create your own namespace and use that namespace
to form the fully qualified widget name. For example, you could map the alias my to your domain
and create a widget called my:widget. To create your own namespace, simply add another xmlns tag
to your page, create an alias, and set it to your unique domain:
<pre>
<html xmlns:my="http://mydomain.com">
</pre>
# Global Object
The angular script creates a single global variable `angular` in the global namespace. All APIs are
bound to fields of this global object.

163
docs/content/guide/compiler.ngdoc
View file

@ -1,163 +0,0 @@
@workInProgress
@ngdoc overview
@name Developer Guide: Compiler
@description
#Compiler
While angular might look like just a cool way to build web applications, the core of angular is
actually an HTML compiler. The default HTML transformations that this compiler provides are useful
for building generic apps, but you can also use them to create a domain-specific language for
building specific types of web applications.
The compiler allows you to add behavior to existing HTML through widgets, directives, and text
markup.
All of this compilation happens in the web browser, meaning no server is involved.
# The compilation process
This section describes the steps that angular's HTML compiler goes through. If you use
`ng:autobind` in your application, this compilation process happens automatically when the
application is initialized (e.g. when the user loads the app in a browser). If you're an advanced
user using manual bind mode, you can decide when and how often the compilation happens.
First, a bit of background of what the compilation step is for. Every type of
{@link angular.widget widget}, {@link angular.markup markup}, and
{@link angular.directive directive} in angular is defined with a compile function, and that
compile function returns an optional link function. Here is the relationship between the two:
* **compile function** - registers a listener for the widget, markup, or directive's expression.
This function is called exactly once.
* **link function** - sets up the listener. This function can be called multiple times, once per
cloned DOM element (e.g. repeating element).
Note that angular's built-in widgets, markup, and directives have predefined compile and link
functions that you don't need to modify. However, if you're writing your own widgets, markup, or
directives, you write compile and link functions. Refer to the Compiler API for more information.
When the HTML compiler compiles a page, it goes through 3 phases: Compile, Create Root Scope, and
Link.
## 1. Compile Phase
* Recursively traverse the DOM, depth-first.
* Look for a matching compile function of type widget, then markup, then directive.
* If a compile function is found then execute it.
* When the compile function completes, it should return a link function. Aggregate this link
function with all link functions returned previously by step 1c.
* Repeat steps 1c and 1d for all compile functions found. The result of the compilation step is
the aggregate link function, which comprises all of the individual link functions.
## 2. Create Root Scope
* Inject all of the services into the root scope.
## 3. Link Phase
* Execute the aggregate link function with the root scope. The aggregate link function calls all
the individual link functions that were generated in the compile phase.
* If there are any clones of the DOM caused by repeating elements, call the link function multiple
times, one for each repeating item.
Note that while the compile function is executed exactly once, the link function can be executed
multiple times: once for each iteration in a repeater.
# Example
The compilation process is best understood through example. Let's say that in your namespace my,
you want to create a new DOM element <my:greeter/>, which should display a greeting.
If we want this HTML source:
<pre>
<div ng:init="salutation='Hello'; name='World'">
<my:greeter salutation="salutation" name="name"/>
</div>
</pre>
To produce this DOM:
<pre>
<div ng:init="salutation='Hello'; name='World'">
<my:greeter salutation="salutation" name="name"/>
<span class="salutation">Hello</span>
<span class="name">World</span>!
</my:greeter>
</div>
</pre>
Write this widget definition (assuming you've already declared the my namespace in the page):
<pre>
angular.widget('my:greeter', function(compileElement){
var compiler = this;
compileElement.css('display', 'block');
var salutationExp = compileElement.attr('salutation');
var nameExp = compileElement.attr('name');
return function(linkElement){
var salutationSpan = angular.element('<span class="salutation"></span');
var nameSpan = angular.element('<span class="name"></span>');
linkElement.append(salutationSpan);
linkElement.append(compiler.text(' '));
linkElement.append(nameSpan);
linkElement.append(compiler.text('!'));
this.$watch(salutationExp, function(value){
salutationSpan.text(value);
});
this.$watch(nameExp, function(value){
nameSpan.text(value);
});
};
});
</pre>
Note: For more about widgets, see {@link angular.widget Widget}.
## Compilation process for this example
Here are the steps that the compiler goes through for the page that contains this widget definition:
### Compile Phase
* Recursively traverse the DOM depth-first.
* Find the angular.widget definition.
* Find and execute the widget's compileElement function, which includes the following steps:
* Add a style element with attribute display: block; to the template DOM so that the browser
knows to treat the element as block element for rendering. (Note: because this style element
was added on the template compileElement, this style is automatically applied to any clones
of the template (i.e. any repeating elements)).
* Extract the salutation and name HTML attributes as angular expressions.
* Return the aggregate link function, which includes just one link function in this example.
### Link Phase
* Execute the aggregate link function, which includes the following steps:
* Create a <span> element set to the salutation class
* Create a <span> element set to the name class.
* Add the span elements to the linkElement. (Note: be careful not to add them to the
compileElement, because that's the template.)
* Set up watches on the expressions. When an expression changes, copy the data to the
corresponding spans.
## Compiler API
If you define your own widgets, markup, or directives, you need to access the compiler API.
This section describes the methods on the compiler that you can call.
Note: As of 12 August 2010, these methods are subject to change.
Recall that the compile function's this is a reference to the compiler.
* `compile(element)` - returns `linker` - Invoke new instance of compiler to compile a DOM element
and return a linker function. You can apply the linker function to the original element or a
clone of the original element. The linker function returns a scope.
* `comment(commentText)` - returns `element` - Create a comment element.
* `element(elementName)` - returns `element` - Create an element by name.
* `text(text)` - returns `element` - Create a text element.
* `descend([set])` - returns `descend` - State Get or set the current descend state. If true the
compiler will descend to children elements.
* `directives([set])` - returns `directive` - State Get or set the current directives processing
state. The compiler will process directives only when directives set to true.

46
docs/content/guide/css.ngdoc
View file

@ -1,46 +0,0 @@
@workInProgress
@ngdoc overview
@name Developer Guide: CSS
@description
# CSS
angular includes built-in CSS classes, which in turn have predefined CSS styles.
# Built-in CSS classes
## `ng-exception`
**Usage:** angular applies this class to a DOM element if that element contains an Expression that
threw an exception when evaluated.
**Styling:** The built-in styling of the ng-exception class displays an error message surrounded
by a solid red border, for example:
> <div class="ng-exception">Error message</div>
You can try to evaluate malformed expressions in {@link guide.expression expression} to see the
`ng-exception` class' styling.
## `ng-validation-error`
**Usage:** angular applies this class to an input widget element if that element's input does not
pass validation. Note that you set the validation criteria on the input widget element using the
Ng:validate or Ng:required directives.
**Styling:** The built-in styling of the ng-validation-error class turns the border of the input
box red and includes a hovering UI element that includes more details of the validation error. You
can see an example in {@link angular.widget.@ng:validate ng:validate example}.
## How to override the styles for built-in classes
To override the styles for these built-in classes, you can do any of the following:
Download the source code, edit angular.css, and host the source on your own server.
Create a local css file, overriding any styles that you'd like, and link to it from your HTML file
as you normally would:
<pre>
<link href="yourfile.css" rel="stylesheet" type="text/css">
</pre>

41
docs/content/guide/data-binding.ngdoc
View file

@ -1,41 +0,0 @@
@workInProgress
@ngdoc overview
@name Developer Guide: Data Binding
@description
# Data Binding
Data-binding allows you to treat the model as the single-source-of-truth of your application, and
consider the view as only a projection of the model, at all times. The process of copying the model
values to the view, and any changes to the view by the user to the model, is known as data-binding.
## Classical Template Systems
<img class="right" src="img/One_Way_Data_Binding.png"/>
At the highest level, angular looks like a just another templating system. But there is one
important reason why angular templating system is different and makes it very good fit for
application development: two-way data binding.
Most templating systems bind data in only one direction: they merge a template and model together
into a view, as illustrated in the diagram to the right. After the merge occurs, any changes to
the model or in related sections of the view are NOT automatically reflected in the view. Worse,
any changes that the user makes to the view are not reflected in the model. This means that the
developer has to write code that constantly syncs the view with the model and the model with the
view.
# angular Template Systems
<img class="right" src="img/Two_Way_Data_Binding.png"/>
The way angular templates works is different, as illustrated in the diagram on the right. They are
different because first the template (which is the uncompiled HTML along with any additional markup
or directives) is compiled on the browser, and second, the compilation step produces a live view.
We say live because any changes to the view are immediately reflected in the model, and any changes
in the model are propagated to the view. This makes the model always the single-source-of-truth for
the application state, greatly simplifying the programing model for the developer. You can think of
the view as simply an instant projection of your model.
Because the view is just a projection of the model, the controller is completely separated from the
view and unaware of it. This makes testing a snap because it is easy to test your controller in
isolation without the view and the related DOM/browser dependency.
For details about how data binding works in angular, see {@link angular.scope Scope}.

14
docs/content/guide/dev_guide.compiler.widgets.creating_widgets.ngdoc
View file

@ -51,13 +51,13 @@ an attribute that can be added to any existing DOM element:
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);
});
};
var compiler = this;
return function(linkElement) {
var currentScope = this;
currentScope.$watch(expression, function(value){
alert(value);
});
};
});
</pre>

2
docs/content/guide/dev_guide.expressions.ngdoc
View file

@ -169,7 +169,7 @@ JavaScript method instead.
Built-in types have methods like `[].push()`, but the richness of these methods is limited.
Consider the example below, which allows you to do a simple search over a canned set of contacts.
The example would be much more complicated if we did not have the `Array:$filter()`. There is no
built-in method on `Array` called {@link api/angular.array.filter $filter} and angular doesn't add
built-in method on `Array` called {@link api/angular.Array.filter $filter} and angular doesn't add
it to `Array.prototype` because that could collide with other JavaScript frameworks.

2
docs/content/guide/dev_guide.mvc.understanding_controller.ngdoc
View file

@ -101,7 +101,7 @@ instances).
You can associate controllers with scope objects explicitly via the {@link api/angular.scope.$new
scope.$new} api or implicitly via the {@link api/angular.directive.@ng:controller ng:controller
scope.$new} api or implicitly via the {@link api/angular.directive.ng:controller ng:controller
directive} or {@link api/angular.service.$route $route service}.

2
docs/content/guide/dev_guide.mvc.understanding_view.ngdoc
View file

@ -13,7 +13,7 @@ the DOM based on information in the template, controller and model.
In the angular implementation of MVC, the view has knowledge of both the model and the controller.
The view knows about the model where two-way data-binding occurs. The view has knowledge of the
controller through angular directives, such as {@link api/angular.directive.@ng:controller
controller through angular directives, such as {@link api/angular.directive.ng:controller
ng:controller} and {@link api/angular.widget.ng:view ng:view}, and through bindings of this form:
`{{someControllerFunction()}}`. In these ways, the view can call functions in an associated
controller function.

2
docs/content/guide/dev_guide.scopes.understanding_scopes.ngdoc
View file

@ -39,7 +39,7 @@ code, observe how the value of `name` changes, based on the HTML element it is d
expect(using('.doc-example-live').repeater('li').row(0)).
toEqual(['Igor']);
expect(using('.doc-example-live').repeater('li').row(1)).
toEqual(['Misko']);g/@
toEqual(['Misko']);
expect(using('.doc-example-live').repeater('li').row(2)).

304
docs/content/guide/di.ngdoc
View file

@ -1,304 +0,0 @@
@workInProgress
@ngdoc overview
@name Developer Guide: Dependency Injection
@description
Dependency injection (DI) is one of the core design patterns in angular and angular applications. DI
allows you to replace almost any part of angular framework or angular application with a custom
implementation, allowing for a highly flexible, maintainable and testable code-base.
Dependency injection is a very common pattern in Java and other statically typed languages. While
undervalued among JavaScript developers, we feel strongly that DI in JavaScript allows us to achieve
the same benefits as in other languages.
This document will focus on using dependency injection in angular. It is outside of the scope of
this document to explain details of dependency injection. For more information on this topic, please
refer to these links:
* {@link http://en.wikipedia.org/wiki/Dependency_injection DI - Wikipedia}
* {@link http://martinfowler.com/articles/injection.html Inversion of Control by Martin Fowler}
* Java
* {@link http://code.google.com/p/google-guice/ Guice}
* {@link http://www.devshed.com/c/a/Java/The-Spring-Framework-Understanding-IoC/ Spring}
* {@link http://picocontainer.org/injection.html picoContainer}
* .NET
* {@link http://msdn.microsoft.com/en-us/magazine/cc163739.aspx MSDN Design Patterns - Dependency Inject}
* {@link http://www.springframework.net/ Spring.NET}
# Dependency Injection in angular
Angular's dependency injection story begins with a `service`. Service in angular lingo is a
JavaScript object, function, or value that is created by angular's injector via a provided factory
function. The factory function is registered with angular via {@link angular.service}.
<pre>
// register a factory for a uniqueId service.
angular.service('uniqueId', function(){
// calling the factory function creates the instance function
var id = 0;
return function(){
// calling the counter instance function will return and increment the count
return ++id;
}
});
</pre>
At run-time we can access the `uniqueId` service by looking it up with the service locator like
this:
<pre>
// create new root scope which has the injector function `$service()`
var scope = angular.scope();
// use the `$service` function to look up the service instance function
var idGenerator = scope.$service('uniqueId');
expect(idGenerator()).toBe(1);
// subsequent lookups using the same root scope return the service instance
var idGenerator2 = scope.$service('uniqueId');
expect(idGenerator).toBe(idGenerator2);
// since it is same instance calling idGenerator2 returns 2;
expect(idGenerator2()).toBe(2);
</pre>
The {@link angular.service service} registry seems like a lot of work, so what are the benefits? To
answer this question, it’s important to realize that in large scale applications there are a lot of
services which are often dependent on each other, as in this example:
<pre>
angular.service('gadgetFactory', function(uniqueId){
return function(){
return {gadgetId: uniqueId()};
};
}, {$inject: ['uniqueId']});
</pre>
Specifically, notice that the `gadgetFactory` takes `uniqueId` service in its arguments. It also
declares this dependency with the `$inject` property. There are several benefits to this approach:
* There is no need for a `main` method for an application responsible for instantiating and wiring
these services. The order of service instantiation and wiring can be inferred by examining the
`$inject` annotations.
* It is easy to replace any one service with a different implementation without having to track down
all of the dependencies. This is useful in:
* Tests: when mocks of services are needed (for example using mock {@link angular.service.$xhr}.)
* Customization: when the service bundled with angular does not do exactly what the application
requires.
More importantly, as we'll soon learn, controllers and other components of angular applications can
also declare their dependencies on services and these will be provided without explicitly looking
them up, but let's not get ahead of ourselves.
Lastly, it is important to realize that all angular services are singletons – application singletons
to be more precise. This means that there is only one instance of a given service per injector. And
since angular is lethally allergic to the global state, it's absolutely possible to create multiple
injectors each with its own instance of a given service (but that is not typically needed, except in
tests where this property is crucially important).
## Service Locator and Scope
The {@link angular.injector injector} is responsible for resolving the service dependencies in the
application. It gets created and configured with the creation of a root scope in your application.
The injector is responsible for caching the instances of services, but this cache is bound to the
scope. This means that different root scopes will have different instances of the injector. While
typical angular applications will only have one root scope (and hence the services will act like
application singletons), in tests it is important to not share singletons across test invocations
for isolation reasons. We get this isolation by having each test create its own separate root scope.
<pre>
// crate a root scope
var rootScope = angular.scope();
// accesss the service locator
var myService = rootScope.$service('myService');
</pre>
# Dependency Injection in Controllers
So far we have been talking about injector as a service locator. This is because we have been
explicitly calling the `$service` method to gain access to the service. Service locator is not
dependency injection since the caller is still responsible for retrieving the dependencies. *True
dependency injection is like Chuck Norris. Chuck does not ask for dependencies; he declares them.*
The most common place to use dependency injection in angular applications is in
{@link angular.directive.@ng:controller controllers}. Here’s a simple example:
<pre>
function MyController($route){
// configure the route service
$route.when(...);
}
MyController.$inject = ['$route'];
</pre>
In this example, the `MyController` constructor function takes one argument, the
{@link angular.service.$route $route} service. Angular is then responsible for supplying the
instance of `$route` to the controller when the constructor is instantiated. There are two ways to
cause controller instantiation – by configuring routes with the $route service or by referencing the
controller from the HTML template, such as:
<pre>
<!doctype html>
<html xmlns:ng="http://angularjs.org" ng:controller="MyController">
<script src="http://code.angularjs.org/angular.min.js" ng:autobind></script>
<body>
...
</body>
</html>
</pre>
When angular is instantiating your controller, it needs to know what services, if any, should be
injected (passed in as arguments) into the controller. Since there is no reflection in JavaScript,
we have to supply this information to angular in the form of an additional property on the
controller constructor function called `$inject`. Think of it as annotations for JavaScript.
<pre>
MyController.$inject = ['$route'];
</pre>
The information in `$inject` is then used by the {@link angular.injector injector} to call the
function with the correct arguments.
# Using Dependency Injection pragmatically
At times you’ll need to use dependency injection pragmatically, usually when instantiating
controllers manually or writing unit tests. This section explains how to go about it.
## Retrieving Services
The simplest form of dependency injection is manual retrieval of scopes, known as service locator.
We say manual because we are asking the injector for an instance of the service (rather then having
the injector provide them to the function). This should be rare since most of the time the dependent
services should be injected into the controller using the `$inject` property array.
<pre>
// create a root scope. The root scope will automatically have
// `$service` method defined which is configured with all services.
// Each instance of root scope will have separate instances of services.
var rootScope = angular.scope();
// ask for a service explicitly
var $window = rootScope.$service('$window');
</pre>
## Creating Controllers using Dependency Injection
In a typical angular application the dependency injection is most commonly used when creating
controllers.
<pre>
// declare our own service by registering a factory function.
angular.service('counter', function(){
var count = 0;
return function(){ return count++; };
});
// example of a controller which depends on '$window' and 'counter' service
// notice that there is an extra unbound parameter 'name' which will not
// be injected and must be supplied by the caller.
function MyController($window, counter, name) {
}
// we must declare the dependencies explicitly and in the same order as in
// the constructor function. This information is used by the dependency
// injection to supply the arguments.
// Notice the lack of 'name' argument which makes it an unbound argument.
MyController.$inject = ['$window', 'counter'];
// Create a root scope which creates the the injector
var rootScope = angular.scope();
// use the '$new()' method instead of standard 'new' keyword operator to
// create an instance of MyController and have the dependency injection
// supply the arguments to the controller. The dependency injection only
// supplies the bound arguments in `$inject` all addition arguments are
// curried from the '$new', in our case 'Alexandria' is the argument which
// will be curried to the 'name' argument, while '$window' and 'counter'
// are supplied by the dependency injection.
var myController = rootScope.$new(MyController, 'Alexandria');
// NOTE: the returning controller will be a child scope of parent scope,
// in this case the root scope.
</pre>
## Calling functions and Curring of arguments
NOTE: this section is quite lame. The concept it is trying to describe is more closely related to
scope#new than scope#$service. We need a better example to discuss here. Ideally a parent controller
creating a child controller imperatively via $new where the child controller's constructor function
declares a portion of its dependencies via $inject property, but another portion is supplied by the
caller of $new (e.g. parentCtrl.$new(ChildCtrl, configParam1, configParam2);
Finally, you may need to call functions but have the `$inject` properties of the function be
supplied by the injector.
<pre>
// create a root scope with the `$service` injector.
var rootScope = angular.scope();
// given a function such as
function greet ($window, name) {
$window.alert(this.salutation + ' ' + name);
}
greet.$inject = ['$window'];
// you can call function 'greet' such that the injector supplies the
// '$window' and the caller supplies the function 'this' and the 'name'
// argument.
var fnThis = {salutation: 'Hello'}
rootScope.$service(greet, fnThis, 'world');
</pre>
# Inferring `$inject`
**EXPERIMENTAL: this is an experimental feature, see the important note at the end of this section
for drawbacks.**
We resort to `$inject` and our own annotation because there is no way in JavaScript to get a list of
arguments. Or is there? It turns out that calling `.toString()` on a function returns the function
declaration along with the argument names as shown below:
<pre>
function myFn(a,b){}
expect(myFn.toString()).toEqual('function myFn(a,b){}');
</pre>
This means that angular can infer the function names after all and use that information to generate
the `$inject` annotation automatically. Therefore the following two function definitions are
equivalent:
<pre>
// given a user defined service
angular.service('serviceA', ...);
// inject '$window', 'serviceA', curry 'name';
function fnA($window, serviceA, name){};
fnA.$inject = ['$window', 'serviceA'];
// inject '$window', 'serviceA', curry 'name';
function fnB($window, serviceA_, name){};
// implies: fnB.$inject = ['$window', 'serviceA'];
</pre>
If angular does not find an `$inject` annotation on the function, then it calls the `.toString()`
and tries to infer what should be injected using the following rules:
* any argument starting with `$` is angular service and will be added to `$inject` property array.
* any argument ending with `_` will be added to the `$inject` property array but we strip the `_`
* all arguments following an argument which has neither `$` nor `_` , must not have `$` nor `_`
(these are free arguments for {@link http://en.wikipedia.org/wiki/Currying curring})
**IMPORTANT**
Minifiers/obfuscators change the names of function arguments and will therefore break the `$inject`
inference. For this reason, either explicitly declare the `$inject` or do not use
minifiers/obfuscators. In the future, we may provide a pre-processor which will scan the source code
and insert the `$inject` into the source code so that it can be minified/obfuscated.

207
docs/content/guide/expression.ngdoc
View file

@ -1,207 +0,0 @@
@workInProgress
@ngdoc overview
@name Developer Guide: Expression
@description
# Expressions
Expressions are the bindings that you write in HTML and embed in templates in order to create
views in angular. They are not equivalent to JavaScript expressions.
For example, these are all valid expressions in angular:
* `1+2={{1+2}}`
* `3*10|currency`
* `Hello {{name}}!`
* `Hello {{'World'}}!`
# angular expressions vs. JS expressions
It might be tempting to think of angular view expressions as JavaScript expressions, but that is
not entirely correct. angular does not use a simple JavaScript eval of the expression text. You
can think of angular expressions as JavaScript expressions with these differences:
* **Attribute Evaluation:** evaluation of all attributes are against the current scope, not to
the global window as in JavaScript.
* **Forgiving:** expression evaluation is forgiving to undefined and null, unlike in JavaScript.
* **No Control Flow Statements:** you cannot do the following from an angular expression:
conditionals, loops, or throw.
* **Type Augmentation:** the scope expression evaluator augments built-in types.
* **Filters:** you can add filters to an expression, for example to convert raw data into a
human-readable format.
* **The $:** angular reserves this prefix to differentiate its API names from others.
If you want to run arbitrary JavaScript code, make it a controller method and call that. If you
want to eval an angular expression from JavaScript, use the Scope:$eval() method.
## Example
<doc:example>
<doc:source>
1+2={{1+2}}
</doc:source>
<doc:scenario>
it('should calculate expression in binding', function(){
expect(binding('1+2')).toEqual('3');
});
</doc:scenario>
</doc:example>
You can try evaluating different expressions here:
<doc:example>
<doc:source>
<div ng:init="exprs=[]" class="expressions">
Expression:
<input type='text' name="expr" value="3*10|currency" size="80"/>
<button ng:click="exprs.$add(expr)">Evaluate</button>
<ul>
<li ng:repeat="expr in exprs">
[ <a href="" ng:click="exprs.$remove(expr)">X</a> ]
<tt>{{expr}}</tt> => <span ng:bind="$parent.$eval(expr)"></span>
</li>
</ul>
</div>
</doc:source>
<doc:scenario>
it('should allow user expression testing', function(){
element('.expressions :button').click();
var li = using('.expressions ul').repeater('li');
expect(li.count()).toBe(1);
expect(li.row(0)).toEqual(["3*10|currency", "$30.00"]);
});
</doc:scenario>
</doc:example>
# Attribute Evaluation
Evaluation of all attributes are against the current scope. Unlike JavaScript, where names
default to global window properties, angular expressions have to use $window to refer to the
global object. E.g. if you want to call alert(), which is defined on window, an expression must
use $window.alert(). This is done intentionally to prevent accidental access to the global state
(a common source of subtle bugs).
<doc:example>
<doc:source>
<div class="example2" ng:init="$window = $service('$window')">
Name: <input name="name" type="text" value="World"/>
<button ng:click="($window.mockWindow || $window).alert('Hello ' + name)">Greet</button>
</div>
</doc:source>
<doc:scenario>
it('should calculate expression in binding', function(){
var alertText;
this.addFutureAction('set mock', function($window, $document, done) {
$window.mockWindow = {
alert: function(text){ alertText = text; }
};
done();
});
element(':button:contains(Greet)').click();
expect(this.addFuture('alert text', function(done) {
done(null, alertText);
})).toBe('Hello World');
});
</doc:scenario>
</doc:example>
## Forgiving
Expression evaluation is forgiving to undefined and null. In JavaScript, evaluating a.b.c throws
an exception if a is not an object. While this makes sense for a general purpose language, the
expression evaluations are primarily used for data binding, which often look like this: `{{a.b.c}}`.
It makes more sense to show nothing than to throw an exception if a is undefined (e.g. perhaps
we are waiting for the server response, and it will become defined soon). If expression
evaluation wasn't forgiving we'd have to write bindings that clutter the code, for example:
`{{((a||{}).b||{}).c}}`
Similarly, invoking a function a.b.c() on undefined or null simply returns undefined.
Assignments work the same way in reverse. a.b.c = 10 creates the intermediary objects even if a
is undefined.
## No Control Flow Statements
You cannot write a control flow statement in an expression. The reason behind this is core to
the angular philosophy that application logic should be in controllers, not in the view. If you
need a conditional (including ternary operators), loop, or to throw from a view expression,
delegate to a JavaScript method instead.
## Type Augmentation
Built-in types have methods like [].push(), but the richness of these methods is limited. Consider
the example below, which allows you to do a simple search over a canned set of contacts. The
example would be much more complicated if we did not have the Array:$filter(). There is no
built-in method on Array called $filter and angular doesn't add it to Array.prototype because that
could collide with other JavaScript frameworks.
For this reason the scope expression evaluator augments the built-in types to make them act like
they have extra methods. The actual method for $filter() is angular.Array.filter(). You can call
it from JavaScript.
Extensions: You can further extend the expression vocabulary by adding new methods to
`angular.Array` or `angular.String`, etc.
<doc:example>
<doc:source>
<div ng:init="friends = [
{name:'John', phone:'555-1212'},
{name:'Mary', phone:'555-9876'},
{name:'Mike', phone:'555-4321'},
{name:'Adam', phone:'555-5678'},
{name:'Julie', phone:'555-8765'}]"></div>
Search: <input name="searchText"/>
<table class="example3">
<tr><th>Name</th><th>Phone</th><tr>
<tr ng:repeat="friend in friends.$filter(searchText)">
<td>{{friend.name}}</td>
<td>{{friend.phone}}</td>
</tr>
</table>
</doc:source>
<doc:scenario>
it('should filter the list', function(){
var tr = using('table.example3').repeater('tr.ng-attr-widget');
expect(tr.count()).toBe(5);
input('searchText').enter('a');
expect(tr.count()).toBe(2);
});
</doc:scenario>
</doc:example>
## Filters
When presenting data to the user, you might need to convert the data from its raw format to a
user-friendly format. For example, you might have a data object that needs to be formatted
according to the locale before displaying it to the user. You can pass expressions through a
chain of filters like this:
<pre>
name | uppercase
</pre>
The expression evaluator simply passes the value of name to angular.filter.uppercase.
Chain filters using this syntax:
<pre>
value | filter1 | filter2
</pre>
You can also pass colon-delimited arguments to filters, for example, to display the number 123
with 2 decimal points: 123 | number:2
# The $
You might be wondering, what is the significance of the $ prefix? It is simply a prefix that
angular chooses to differentiate its API names from others. If angular didn't use $, then
evaluating a.length() would return undefined because neither a nor angular define such a property.
Consider that in a future version of angular we might choose to add a length method, in which case
the behavior of the expression would change. Worse yet, you the developer could create a length
property and then we would have collision. This problem exists because angular augments existing
objects with additional behavior. By prefixing its additions with $ we are reserving our namespace
so that angular developers and developers who use angular can develop in harmony without
collisions.

2
docs/content/guide/index.ngdoc
View file

@ -12,7 +12,7 @@ If you are completely or relatively unfamiliar with angular, you may want to che
of the following documents before returning here to the Developer Guide:
* {@link intro/started Getting Started}
* {@link misc/started Getting Started}
* {@link tutorial/index Angular Tutorial}

337
docs/content/guide/overview.ngdoc
View file

@ -1,337 +0,0 @@
@ngdoc overview
@name Developer Guide: Overview
@description
* <a href="#H1_1">What Is Angular?</a>
* <a href="#H1_3">The Angular Philosophy</a>
* <a href="#H1_2">Anatomy Of An Angular App</a>
* <a href="#H1_4">Why You Want Angular</a>
* <a href="#H1_5">Angular's Ancestors</a>
* <a href="#H1_6">Watch a Presentation About Angular</a>
<a name="H1_1"></a>
# What Is Angular?
The short answer: angular is a new, powerful, client-side technology that makes it much easier for
you to create dynamic web sites and complex web apps, all without leaving the comfort of your HTML
/ JavaScript home.
The long answer: it kind of depends on where you're coming from...
* If you're a web designer, you might perceive angular to be a sweet {@link guide.template
templating} system, that doesn't get in your way and provides you with lots of nice built-ins that
make it easier to do what you want to do.
* If you're a web developer, you might be thrilled that angular functions as an excellent web
framework, one that assists you all the way through the development cycle.
* If you want to go deeper, you can immerse yourself in angular's extensible HTML {@link
guide.compiler compiler} that runs in your browser. This compiler teaches your browser new tricks.
So then, angular's not just a templating system, but you can create fantastic templates with it;
angular's not just a web framework, but it has a very nice one; and angular's not just an
extensible HTML compiler, but it has one of those too. Let's put it this way: angular includes
these parts along with some others; it evolved naturally from earlier occurrences of these forms;
and thus angular is something far greater than the sum of its parts. It sounds like... it's alive!
## An Intro By Way of Example
Let's say that you are a web designer, and you've spent many thous — erm, hundreds of hours
designing web sites. But at this point, the thought of doing DOM updates, writing listeners, and
writing input validators, all to do something as simple as implementing a form!? You either don't
want to go there in the first place or you've been there and the thrill is gone.
You could even be muttering to yourself as you hack another callback, "This is like building my own
bike from scratch every time I want to ride to the store." But let's say a clever friend, who keeps
tabs on these sorts of things, told you to check out angular.
So now here you are checking out angular, and here is a simple example. Note that it features only
the templating aspect of angular, but this should suffice for now to quickly demonstrates how much
easier life can be with angular:
<doc:example>
<doc:source>
<h2>Bigg Bike Shop</h2>
<hr>
<b>Invoice:</b>
<br/>
<br/>
<table>
<tr><td> </td><td> </td>
<tr><td>Quantity</td><td>Cost</td></tr>
<tr>
<td><input name="qty" value="1" ng:validate="integer:0" ng:required/></td>
<td><input name="cost" value="19.95" ng:validate="number" ng:required/></td>
</tr>
</table>
<hr>
<b>Total:</b> {{qty * cost | currency}}
<hr>
</doc:source>
<!--
<doc:scenario>
it('should show of angular binding', function(){
expect(binding('qty * cost')).toEqual('$19.95');
input('qty').enter('2');
input('cost').enter('5.00');
expect(binding('qty * cost')).toEqual('$10.00');
});
</doc:scenario>
-->
</doc:example>
Go ahead, try out the Live Preview above. "Well I _declare_! It's a fully functioning form, with
an instantly updating display, and input validation." Speaking of being declarative, let's walk
through the example and look at the angular-related lines to see what's going on around here.
In line __2__ of the example, we let the browser know about the angular namespace:
2 <html xmlns:ng="http://angularjs.org">
This ensures angular runs nicely in all major browsers.
In line __3__ we do two angular setup tasks inside a `<script>` tag:
1. We pull in `angular.js`.
2. The angular {@link angular.directive.ng:autobind ng:autobind} directive tells angular to {@link
guide.compiler compile} and manage the whole HTML document.
3 <script src="file:///Users/krculp/angular.js/build/angular.min.js" ng:autobind></script>
Lines __14__ and __15__ set up one side of angular's very cool two-way data binding, as well as
demonstrate some easy input validation:
14 Quantity: <input name="qty" value="1" ng:validate="integer:0" ng:required/>
15 Cost: <input name="cost" value="199.95" ng:validate="number" ng:required/>
These input widgets look normal enough, but consider these points:
* Remember the `ng:autobind` directive from line 3? When this page loaded, angular bound the names
of the input widgets (`qty` and `cost`) to variables of the same name. Think of those variables as
the "Model" part of the Model-View-Controller design pattern.
* Note the angular directives, {@link angular.widget.@ng:validate ng:validate} and {@link
angular.widget.@ng:required ng:required}. You may have noticed that when you enter invalid data or
leave the the input fields blank, the borders turn a plainly irritated red color, and the display
value disappears. These `ng:` directives make it easier to implement field validators than coding
them in JavaScript, no? Yes.
And finally, the mysterious line #__19__:
19 Total: {{qty * cost | currency}}
What's with the curly braces? Those curly braces are your friend. This notation, `{{ _expression_
}}`, is a bit of built-in angular {@link angular.markup markup}, a shortcut that you use to display
data. The expression within curly braces gets transformed by the angular compiler into an angular
directive ({@link angular.directive.ng:bind ng:bind}). The expression itself can be a combination
of both an expression and a {@link angular.filter filter}: `{{ expression | filter }}`.
In our example above, we're saying, "Bind the data we got from the input widgets to the display,
multiply them together, and format the resulting number into something that looks like money."
<a name="H1_3"></a>
# The Angular Philosophy
Angular is built around the belief that declarative code is better than imperative when it comes to
building UIs and wiring software components together, while imperative code is clearly the way to
go for expressing business logic.
Not to put too fine a point on it, but if you wanted to add a new label to your application, you
could do it by simply adding text to the HTML template, saving the code, and refreshing your
browser (this here is declarative):
<pre>
<span class="label">Hello</span>
</pre>
Or, as In programmatic systems (like {@link http://code.google.com/webtoolkit/ GWT}), you would
have to write the code and then run the code like this:
<pre>
var label = new Label();
label.setText('Hello');
label.setClass('label');
parent.addChild(label);
</pre>
That looks like, let's see, do some math, factor out the `<pre>`s, carry the one, ummm... a little
bit of markup versus four times as much code.
More Angular Philosophy:
* It is a very good idea to decouple DOM manipulation from app logic. This dramatically improves
the testability of the code.
* It is a really, _really_ good idea to regard app testing as equal in importance to app writing.
Testing difficulty is dramatically affected by the way the code is structured.
* It is an excellent idea to decouple the client side of an app from the server side. This allows
development work to progress in parallel, and allows for reuse of both sides.
* It is very helpful indeed if the framework guides developers through the entire journey of
building an app: from designing the UI, through writing the business logic, to testing.
* It is always good to make common tasks trivial and difficult tasks possible.
Now that we're homing in on what angular is, perhaps now would be a good time to list a few things
what angular isn't:
* It's not a Library. You don't just call its functions, although it does provide you with some
utility APIs.
* It's not a DOM Manipulation Library. angular uses jQuery to manipulate the DOM behind the scenes,
rather than give you functions to manipulate the DOM with yourself.
* It's not a Widget Library. There are lots of existing widget libraries that you can integrate
with angular.
* It's not "Just Another Templating System". A part of angular is a templating system. The
templating subsystem of angular is different from the traditional approach for these reasons:
* It Uses HTML/CSS syntax: This makes it easy to read and can be edited with existing HTML/CSS
authoring tools.
* It Extends HTML vocabulary: Angular allows you to create new HTML tags, which expand into
dynamic UI components.
* It Executes in the browser: Removes the round trip to the server for many operations and
creates instant feedback for users as well as developers.
* It Has Bidirectional data binding: The model is the single source of truth. Programmatic
changes to the model are automatically reflected in the view. Any changes by the user to the view
are automatically reflected in the model.
<a name="H1_2"></a>
# Anatomy Of An Angular App
This section describes the parts of an angular app in more detail.
## Templates
{@link guide.template Templates} are the part of angular that makes it easy and fun to create the
UI for your web apps. With angular's templates you can create a dynamic UI using only HTML and
CSS, but now you can add your own elements, attributes, and markup. The angular compiler reads the
"angularized" HTML when your page loads, and follows the instructions in there to generate a
dynamic page for you. This is the View part of MVC. "But wait there's more": since the compiler is
extensible, you can build your own declarative language on top of HTML!
## Application Logic and Behavior
Application Logic and Behavior, which you define in JavaScript, is the C in MVC. With angular you
write the logic (the controllers) for your app, but because angular takes care of reflecting the
state of the model in the view, you don't have to write listeners or DOM manipulators. This feature
makes your application logic very easy to write, test, maintain, and understand.
## Data
In an angular app, all of your data is referenced from inside of a {@link angular.scope scope}.
The scope is the data Model, the M in the MVC pattern. A scope is a JavaScript object that has
watcher functions that keep tabs on the data that is referenced from that scope. The data could be
one or more Javascript objects, arrays, or primitives, it doesn't matter. What matters is that
these are all referenced by the scope.
This "scope thing" is how angular takes care of keeping your data model and your UI in sync.
Whenever something occurs to change the state of the scope, angular immediately reflects that
change in the UI, and vice versa.
In addition to the three components described above (the MVC bits), angular comes with a set of
{@link angular.service Services} that are very helpful for building web apps. The services include
the following features:
* You can extend and add application-specific behavior to services.
* Services include Dependency-Injection, XHR, caching, URL routing, and browser abstraction.
The following illustration shows the parts of an angular application and how they work together:
<img class="left" src="img/angular_parts.png" border="0" />
<a name="H1_4"></a>
# Why You Want Angular
Angular frees you from the following pain:
* **Registering callbacks:** Registering callbacks clutters your code, making it hard to see the
forest for the trees. Removing common boilerplate code such as callbacks is a good thing. It vastly
reduces the amount of JavaScript coding _you_ have to do, and it makes it easier to see what your
application does.
* **Manipulating HTML DOM programatically:** Manipulating HTML DOM is a cornerstone of AJAX
applications, but it's cumbersome and error-prone. By declaratively describing how the UI should
change as your application state changes, you are freed from low level DOM manipulation tasks. Most
applications written with angular never have to programatically manipulate the DOM, although you
can if you want to, knock yourself out.
* **Marshaling data to and from the UI:** CRUD operations make up the majority of AJAX
applications. The flow of marshaling data from the server to an internal object to an HTML form,
allowing users to modify the form, validating the form, displaying validation errors, returning to
an internal model, and then back to the server (gah!) creates a lot of boilerplate code. Angular
eliminates almost all of this boilerplate, leaving code that describes the overall flow of the
application rather than all of the implementation details.
* **Writing tons of initialization code just to get started:** Typically you need to write a lot of
plumbing just to get a basic "Hello World" AJAX app working. With angular you can bootstrap your
app easily using services, which are auto-injected into your application in a {@link
http://code.google.com/p/google-guice/ Guice}-like dependency-injection style. This allows you to
get started developing features quickly. As a bonus, you get full control over the initialization
process in automated tests.
<a name="H1_5"></a>
# Angular's Ancestors
Where does angular come from? What events led to the inevitability of the appearance of something
like angular?
## First There Was HTML
HTML was initially designed long, long ago, in the great year of 1989, with the intention to create
a markup language for sharing scientific documents over the network. Yes, yes, certainly there was
SGML even before that, but it was so difficult that even esteemed scientists balked at using it.
Thankfully, Tim Berners-Lee saved all of us from that pain with his much friendlier HTML.
`<HTML><BODY>Thank You, TB-L!</BODY></HTML>`.
## Then There Was JavaScript
Fast forward to 1995: JavaScript was invented. This was done with the best of intentions! But in
practice it initially served mainly to annoy Internet users with cheap effects that "enhanced"
static HTML documents.
Fast forward to the mid 2000s, when a new breed of back-then-considered-rich web applications
started to appear on the web. These were built with HTML, JavaScript, and CSS, and featured less
annoying and more impressive effects. Can you recall the first time you saw apps like Gmail, or
Google Maps, and you couldn't believe everything that was going on in the browser?
## And JavaScript Prevailed
As of this writing, in 2011, people are building still richer and more interactive web applications
that often rival their desktop counterparts. And yet they are essentially still working with
technology and programming primitives that were used decades ago for the creation of static
documents with cheap graphic effects. At the same time, the web is HUGE now, and we
can't just abandon the technologies it was built with. Applets, Flash and Silverlight tried it, and
in some ways succeeded. Yet many would argue that in reality they failed, because they tried to
work _around_ the web instead of working _with_ it.
## And Then There Was Angular
Angular recognizes the strengths of the existing "static" web technologies, as well as their
deficiencies. At the same time, angular is learning from the failures of other technologies that
tried, or are trying, to work around the web.
For these reasons angular plays to the strengths of established web technologies, instead of
bypassing them. Angular sets out the goal of increasing the abstraction and programming primitives
that developers use to build web applications, so as to better reflect the needs of modern web
applications and their developers.
<a name="H1_6"></a>
# Watch a Presentation About Angular
Here is an early presentation on angular, but note that substantial development has occurred since
the talk was given in July of 2010.
<object width="480" height="385">
<param name="movie" value="http://www.youtube.com/v/elvcgVSynRg&amp;hl=en_US&amp;fs=1"></param>
<param name="allowFullScreen" value="true"></param>
<param name="allowscriptaccess" value="always"></param>
<embed src="http://www.youtube.com/v/elvcgVSynRg&amp;hl=en_US&amp;fs=1"
type="application/x-shockwave-flash" allowscriptaccess="always"
allowfullscreen="true" width="480" height="385"></embed>
</object>
{@link
https://docs.google.com/present/edit?id=0Abz6S2TvsDWSZDQ0OWdjaF8yNTRnODczazdmZg&hl=en&authkey=CO-b7oID
Presentation}
|
{@link
https://docs.google.com/document/edit?id=1ZHVhqC0apbzPRQcgnb1Ye-bAUbNJ-IlFMyPBPCZ2cYU&hl=en&authkey=CInnwLYO
Source}

22
docs/content/guide/template.ngdoc
View file

@ -1,22 +0,0 @@
@workInProgress
@ngdoc overview
@name Developer Guide: Template
@description
#Template
You can think of a template in angular as a domain-specific language that you can use to easily
build the view of your web application. You create a template by writing HTML and CSS, and you can
add any constructs that you want to the HTML. This means that you can attach rendering and behavior
to any HTML element, attribute or markup text.
In addition to writing HTML and CSS, you can also use the following angular constructs to create
your template:
* **Directive** - XML attributes that augment an existing DOM element.
* **Markup** - Lets you create shorthand for a widget or a directive. For example, markup is what
allows you to use the double curly brace notation {{}} to bind expressions to
elements.
* **Filter** - Lets you format your data for display to the user.
* **Widget** - Lets you create new DOM elements that the browser doesn't already understand.
* **Validator** - Lets you validate user input.
* **Formatter** - Lets you format the input object into a user readable view.

8
docs/content/guide/testing.ngdoc
View file

@ -1,8 +0,0 @@
@workInProgress
@ngdoc overview
@name Developer Guide: Testing
@description
# Testing Angular Applications
to be written...

33
docs/content/misc/testimonials.ngdoc
View file

@ -1,33 +0,0 @@
@ngdoc overview
@name Testimonials
@description
## John Hardy
> Also I want to pass on my compliments to Misko and Igor for this fantastic project. I'm currently
> rewriting a server-side web application to use this system. I am constantly astounded at how much
> simpler it is to do it this way and I still consider myself a learner.
> This is without question the most productive approach to building webapps that I have seen.
> The last time I had a coding epiphany was discovering the power and simplicity of JQuery. This is
> way better than that.
> I'm interested in promoting this library as widely as possible. I understand that you are still
> developing it and I still have a long way to go before I really understand everything but I think
> you really have something here.
## Jerry Jeremiah
> angular is the best thing I have used in a long time. I am having so much fun, even thought it is
> probably obvious that dynamic web sites are new to me (my experience is more in the back end
> embedded world...)
## Dobrica Pavlinusic
> Thanks to great help I received at this list, I was basically able to accomplish my goal to write
> simple conference submission application within a week of first git clone of angular source from
> github.
> I think it might be useful to summarize my experience here, especially for people who are still
> wondering if angular is worth a try. Executive summary is: **yes it is!**

4
docs/content/tutorial/index.ngdoc
View file

@ -18,9 +18,9 @@ use of extensions or plugins.
* You will see examples of how to use client-side data binding and dependency injection to build
dynamic views of data that change immediately in response to user actions.
* You will see how Angular creates listeners on your data without the need for DOM manipulation.
* You will see how angular creates listeners on your data without the need for DOM manipulation.
* You will learn a better, easier way to test your web apps.
* You will learn how to use Angular services to make common web tasks, such as getting data into
* You will learn how to use angular services to make common web tasks, such as getting data into
your app, easier.

10
docs/content/tutorial/step_00.ngdoc Executable file → Normal file
View file

@ -8,7 +8,7 @@
You are now ready to build the phone cat application. In this step, you will become familiar with
You are now ready to build the phonecat application. In this step, you will become familiar with
the most important source code files, learn how to start the development servers bundled with
angular-seed, and run the application in the browser.
@ -20,7 +20,7 @@ angular-seed, and run the application in the browser.
<ol>
<li><p>In angular-phonecat directory, run this command:</p>
<pre><code>git checkout -f step-0</code></pre>
<p>This resets your workspace to Step 0 of the tutorial app.</p>
<p>This resets your workspace to step 0 of the tutorial app.</p>
<p>You must repeat this for every future step in the tutorial and change the number to
the number of the step you are on. This will cause any changes you made within
your working directory to be lost.</p></li>
@ -56,7 +56,7 @@ directory.</li>
<ol>
<li><p>Open msysGit bash and run this command (in angular-phonecat directory):</p>
<pre><code>git checkout -f step-0</code></pre>
<p>This resets your workspace to Step 0 of the tutorial app.</p>
<p>This resets your workspace to step 0 of the tutorial app.</p>
<p>You must repeat this for every future step in the tutorial and change the number to
the number of the step you are on. This will cause any changes you made within
your working directory to be lost.</p></li>
@ -90,7 +90,7 @@ directory.</li>
<ol>
<li><p>In angular-phonecat directory, run this command:</p>
<pre><code>./goto_step.sh 0</code></pre>
<p>This resets your workspace to Step 0 of the tutorial app.</p>
<p>This resets your workspace to step 0 of the tutorial app.</p>
<p>You must repeat this for every future step in the tutorial and change the number to
the number of the step you are on. This will cause any changes you made within
your working directory to be lost.</p></li>
@ -124,7 +124,7 @@ href="http://localhost:8000/app/index.html">http://localhost:8000/app/index.html
<ol>
<li><p>Open windows command line and run this command (in angular-phonecat directory):</p>
<pre><code>goto_step.bat 0</code></pre>
<p>This resets your workspace to Step 0 of the tutorial app.</p>
<p>This resets your workspace to step 0 of the tutorial app.</p>
<p>You must repeat this for every future step in the tutorial and change the number to
the number of the step you are on. This will cause any changes you made within
your working directory to be lost.</p></li>

0
docs/content/tutorial/step_01.ngdoc Executable file → Normal file
View file

30
docs/content/tutorial/step_02.ngdoc Executable file → Normal file
View file

@ -66,15 +66,15 @@ widget} and two {@link guide/dev_guide.expressions angular expressions} enclosed
`{{phone.name}}` and `{{phone.snippet}}`:
* The `ng:repeat="phone in phones"` statement in the `<li>` tag is an angular repeater. It
tells angular to create a `<li>` element for each phone in the phones list, using the first `<li>`
tag as the template.
* The `ng:repeat="phone in phones"` statement in the `<li>` tag is an angular repeater. It tells
angular to create a `<li>` element for each phone in the phones list, using the first `<li>` tag as
the template.
<img src="img/tutorial/tutorial_02_final.png">
* The curly braces around `phone.name` and `phone.snippet` are an example of {@link
* The curly braces around `phone.name` and `phone.snippet` are an example of {@link
guide/dev_guide.compiler.markup angular markup}. The curly markup is shorthand for the angular
directive {@link api/angular.directive.ng:bind ng:bind}. The `ng:bind` directives indicate to
angular that these are template binding points. Binding points are locations in the template where
@ -117,20 +117,18 @@ the model and the view. Note in the following how we connected the dots between
data, and logic components:
* The name of our controller function (in the JavaScript file `controllers.js`) matches the
{@link api/angular.directive.@ng:controller ng:controller} directive in the `<body>` tag
(`PhoneListCtrl`).
* We instantiated our data within the scope of our controller function, and our template
binding points are located within the block bounded by the `<body ng:controller="PhoneListCtrl">`
tag.
* The name of our controller function (in the JavaScript file `controllers.js`) matches the {@link
api/angular.directive.ng:controller ng:controller} directive in the `<body>` tag (`PhoneListCtrl`).
* We instantiated our data within the scope of our controller function, and our template binding
points are located within the block bounded by the `<body ng:controller="PhoneListCtrl">` tag.
Angular scopes are a crucial concept in angular; you can think of scopes as the glue that makes
the template, model and controller all work together. Angular uses scopes, along with the
information contained in the template, data model, and controller, to keep the model and view
separated but in sync. Any changes to the model are reflected in the view; any changes that occur
in the view are reflected in the model. To learn more about angular scopes, see the {@link
api/angular.scope angular scope documentation}.
Angular scopes are a crucial concept in angular; you can think of scopes as the glue that makes the
template, model and controller all work together. Angular uses scopes, along with the information
contained in the template, data model, and controller, to keep the model and view separated but in
sync. Any changes to the model are reflected in the view; any changes that occur in the view are
reflected in the model. To learn more about angular scopes, see the {@link api/angular.scope
angular scope documentation}.

6
docs/content/tutorial/step_03.ngdoc Executable file → Normal file
View file

@ -59,7 +59,7 @@ __`app/index.html`:__
</pre>
We added a standard HTML `<input>` tag and use angular's {@link api/angular.array.filter $filter}
We added a standard HTML `<input>` tag and use angular's {@link api/angular.Array.filter $filter}
function to process the input for the `ng:repeater`.
@ -80,7 +80,7 @@ the DOM to reflect the current state of the model.
<img src="img/tutorial/tutorial_03_final.png">
* Use of `$filter`. The {@link api/angular.array.filter $filter} method, uses the `query` value, to
* Use of `$filter`. The {@link api/angular.Array.filter $filter} method, uses the `query` value, to
create a new array that contains only those records that match the `query`.
@ -207,7 +207,7 @@ element with `id` `"status"` and content with the `query` binding into the `inde
make the test pass.
* Add a `wait();` statement into an end-to-end test and rerun it. You'll see the runner pausing,
* Add a `pause()` statement into an end-to-end test and rerun it. You'll see the runner pausing,
giving you the opportunity to explore the state of your application displayed in the browser. The
app is live! Change the search query to prove it. This is great for troubleshooting end-to-end
tests.

7
docs/content/tutorial/step_04.ngdoc Executable file → Normal file
View file

@ -71,9 +71,9 @@ two provided sorting options.
<img src="img/tutorial/tutorial_04-06_final.png">
* We then chained the `$filter` method with {@link api/angular.array.orderBy `$orderBy`} method to
* We then chained the `$filter` method with {@link api/angular.Array.orderBy `$orderBy`} method to
further process the input into the repeater. `$orderBy` is a utility method similar to {@link
api/angular.array.filter `$filter`}, but instead of filtering an array, it reorders it.
api/angular.Array.filter `$filter`}, but instead of filtering an array, it reorders it.
Angular creates a two way data-binding between the select element and the `orderProp` model.
@ -201,7 +201,8 @@ Let's turn our attention to the end-to-end test.
__`test/e2e/scenarios.js`:__
<pre>
...
it('should be possible to control phone order via the drop down select box', function() {
it('should be possible to control phone order via the drop down select box',
function() {
// let's narrow the dataset to make the test assertions shorter

2
docs/content/tutorial/step_05.ngdoc Executable file → Normal file
View file

@ -103,7 +103,7 @@ To use a service in angular, you simply declare the names of the services you ne
the controller's constructor function, as follows:
function PhoneListCtrl($xhr) {
function PhoneListCtrl($xhr) {...}
Angular's dependency injector provides services to your controller when the controller is being

0
docs/content/tutorial/step_06.ngdoc Executable file → Normal file
View file

0
docs/content/tutorial/step_07.ngdoc Executable file → Normal file
View file

0
docs/content/tutorial/step_08.ngdoc Executable file → Normal file
View file

0
docs/content/tutorial/step_09.ngdoc Executable file → Normal file
View file

2
docs/src/ngdoc.js
View file

@ -578,7 +578,7 @@ function metadata(docs){
var KEYWORD_PRIORITY = {
'.index': 1,
'.guide': 2,
'.guide.overview': 1,
'.dev_guide.overview': 1,
'.angular': 7,
'.angular.Array': 7,
'.angular.Object': 7,

4
docs/src/templates/docs.css
View file

@ -41,6 +41,10 @@ h4 {
margin: 2em 0 1em 0;
}
li {
margin: 0.3em 0 0.3em 0;
}
/*----- Upgrade IE Prompt -----*/

2
src/Injector.js
View file

@ -5,7 +5,7 @@
*
* @description
* Creates an inject function that can be used for dependency injection.
* (See {@link guide/di dependency injection})
* (See {@link guide/dev_guide.di dependency injection})
*
* The inject function can be used for retrieving service instances or for calling any function
* which has the $inject property so that the services can be automatically provided. Angular

24
src/Scope.js
View file

@ -117,19 +117,19 @@ function errorHandlerFor(element, error) {
*
* Angular scope objects provide the following methods:
*
* * {@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()} -
* * {@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()} -
*
* For more information about how angular scope objects work,, see {@link guide/scopes Angular Scope
* Objects} in the angular Developer Guide.
* For more information about how angular scope objects work, see {@link guide/dev_guide.scopes
* Angular Scope Objects} in the angular Developer Guide.
*/
function createScope(parent, providers, instanceCache) {
function Parent(){}

6
src/angular-mocks.js vendored
View file

@ -68,10 +68,10 @@
*
* 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
* * {@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.
* * {@link angular.mock.service.$log $log } - A mock implementation of the angular service log.
*/
angular.mock = {};

94
src/directives.js
View file

@ -5,39 +5,41 @@
* @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}.
* specified in, but are not intended to add elements to the DOM as are
* {@link angular.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
* * {@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`,
* * {@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
* * {@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
* * {@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
* * {@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 angular.widget.@ng:repeat} to affect even rows in a collection.
* * {@link angular.directive.ng:class-odd ng:class-odd} - Like `ng:class`, but works with {@link
* angular.widget.@ng:repeat} to affect odd rows.
* * {@link angular.directive.ng:click ng:click} - Executes custom behavior when element is clicked.
* * {@link angular.directive.ng: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
* * {@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.
* * {@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.
* see {@link guide/dev_guide.compiler.directives Understanding Angular Directives} in the angular
* Developer Guide.
*/
/**
@ -50,7 +52,7 @@
* before the template enters execution mode during bootstrap.
*
* @element ANY
* @param {expression} expression {@link guide/expression Expression} to eval.
* @param {expression} expression {@link guide/dev_guide.expressions Expression} to eval.
*
* @example
<doc:example>
@ -76,7 +78,7 @@ angularDirective("ng:init", function(expression){
/**
* @workInProgress
* @ngdoc directive
* @name angular.directive.@ng:controller
* @name angular.directive.ng:controller
*
* @description
* The `ng:controller` directive assigns behavior to a scope. This is a key aspect of how angular
@ -94,8 +96,8 @@ angularDirective("ng:init", function(expression){
*
* @element ANY
* @param {expression} expression Name of a globally accessible constructor function or an
* {@link guide/expression expression} that on the current scope evaluates to a constructor
* function.
* {@link guide/dev_guide.expressions expression} that on the current scope evaluates to a
* constructor function.
*
* @example
* Here is a simple form for editing user contact information. Adding, removing, clearing, and
@ -182,7 +184,7 @@ angularDirective("ng:controller", function(expression){
* without displaying the result to the user.
*
* @element ANY
* @param {expression} expression {@link guide/expression Expression} to eval.
* @param {expression} expression {@link guide/dev_guide.expressions Expression} to eval.
*
* @example
* Notice that `{{` `obj.multiplied = obj.a * obj.b` `}}` has a side effect of assigning
@ -231,7 +233,7 @@ angularDirective("ng:eval", function(expression){
* `<span ng:bind="expression"></span>` at bootstrap time.
*
* @element ANY
* @param {expression} expression {@link guide/expression Expression} to eval.
* @param {expression} expression {@link guide/dev_guide.expressions Expression} to eval.
*
* @example
* You can try it right here: enter text in the text box and watch the greeting change.
@ -390,10 +392,11 @@ var REMOVE_ATTRIBUTES = {
* @name angular.directive.ng:bind-attr
*
* @description
* The `ng:bind-attr` attribute specifies that {@link guide/data-binding databindings} should be
* created between element attributes and given expressions. Unlike `ng:bind` the `ng:bind-attr`
* contains a JSON key value pairs representing which attributes need to be mapped to which
* {@link guide/expression expressions}.
* The `ng:bind-attr` attribute specifies that
* {@link guide/dev_guide.templates.databinding databindings} should be created between element
* attributes and given expressions. Unlike `ng:bind` the `ng:bind-attr` contains a JSON key value
* pairs representing which attributes need to be mapped to which
* {@link guide/dev_guide.expressions expressions}.
*
* You don't usually write the `ng:bind-attr` in the HTML since embedding
* <tt ng:non-bindable>{{expression}}</tt> into the attribute directly as the attribute value is
@ -480,7 +483,7 @@ angularDirective("ng:bind-attr", function(expression){
* element is clicked.
*
* @element ANY
* @param {expression} expression {@link guide/expression Expression} to eval upon click.
* @param {expression} expression {@link guide/dev_guide.expressions Expression} to eval upon click.
*
* @example
<doc:example>
@ -531,7 +534,7 @@ angularDirective("ng:click", function(expression, element){
* server and reloading the current page).
*
* @element form
* @param {expression} expression {@link guide/expression Expression} to eval.
* @param {expression} expression {@link guide/dev_guide.expressions Expression} to eval.
*
* @example
<doc:example>
@ -594,7 +597,7 @@ function ngClass(selector) {
* conditionally.
*
* @element ANY
* @param {expression} expression {@link guide/expression Expression} to eval.
* @param {expression} expression {@link guide/dev_guide.expressions Expression} to eval.
*
* @example
<doc:example>
@ -635,8 +638,8 @@ angularDirective("ng:class", ngClass(function(){return true;}));
* and takes affect only on odd (even) rows.
*
* @element ANY
* @param {expression} expression {@link guide/expression Expression} to eval. Must be inside
* `ng:repeat`.
* @param {expression} expression {@link guide/dev_guide.expressions Expression} to eval. Must be
* inside `ng:repeat`.
*
* @example
<doc:example>
@ -673,8 +676,8 @@ angularDirective("ng:class-odd", ngClass(function(i){return i % 2 === 0;}));
* and takes affect only on odd (even) rows.
*
* @element ANY
* @param {expression} expression {@link guide/expression Expression} to eval. Must be inside
* `ng:repeat`.
* @param {expression} expression {@link guide/dev_guide.expressions Expression} to eval. Must be
* inside `ng:repeat`.
*
* @example
<doc:example>
@ -710,8 +713,8 @@ angularDirective("ng:class-even", ngClass(function(i){return i % 2 === 1;}));
* conditionally.
*
* @element ANY
* @param {expression} expression If the {@link guide/expression expression} is truthy then the element
* is shown or hidden respectively.
* @param {expression} expression If the {@link guide/dev_guide.expressions expression} is truthy
* then the element is shown or hidden respectively.
*
* @example
<doc:example>
@ -751,8 +754,8 @@ angularDirective("ng:show", function(expression, element){
* of the HTML conditionally.
*
* @element ANY
* @param {expression} expression If the {@link guide/expression expression} truthy then the element
* is shown or hidden respectively.
* @param {expression} expression If the {@link guide/dev_guide.expressions expression} truthy then
* the element is shown or hidden respectively.
*
* @example
<doc:example>
@ -791,8 +794,9 @@ angularDirective("ng:hide", function(expression, element){
* The ng:style allows you to set CSS style on an HTML element conditionally.
*
* @element ANY
* @param {expression} expression {@link guide/expression Expression} which evals to an object whose
* keys are CSS style names and values are corresponding values for those CSS keys.
* @param {expression} expression {@link guide/dev_guide.expressions Expression} which evals to an
* object whose keys are CSS style names and values are corresponding values for those CSS
* keys.
*
* @example
<doc:example>

20
src/filters.js
View file

@ -12,16 +12,18 @@
*
* 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}
* * {@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.
* For more information about how angular filters work, and how to create your own filters, see
* {@link guide/dev_guide.templates.filters Understanding Angular Filters} in the angular Developer
* Guide.
*/
/**

15
src/formatters.js
View file

@ -9,15 +9,16 @@
*
* 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
* * {@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.
* see {@link guide/dev_guide.templates.formatters Understanding Angular Formatters} in the angular
* Developer Guide.
*/
function formatter(format, parse) {return {'format':format, 'parse':parse || format};}

52
src/jqLite.js
View file

@ -2,6 +2,58 @@
//JQLite
//////////////////////////////////
/**
* @workInProgress
* @ngdoc function
* @name angular.element
* @function
*
* @description
* Wraps a raw DOM element or HTML string as [jQuery](http://jquery.com) element.
* `angular.element` is either an alias for [jQuery](http://api.jquery.com/jQuery/) function if
* jQuery is loaded or a function that wraps the element or string in angular's jQuery lite
* implementation.
*
* Real jQuery always takes precedence (as long as it was loaded before `DOMContentEvent`)
*
* Angular's jQuery lite implementation is a tiny API-compatible subset of jQuery which allows
* angular to manipulate DOM. The jQuery lite implements only a subset of jQuery api, with the
* focus on the most commonly needed functionality and minimal footprint. For this reason only a
* limited number of jQuery methods, arguments and invocation styles are supported.
*
* NOTE: All element references in angular are always wrapped with jQuery (lite) and are never
* raw DOM references.
*
* ## Angular's jQuery lite implements these functions:
*
* - [addClass()](http://api.jquery.com/addClass/)
* - [after()](http://api.jquery.com/after/)
* - [append()](http://api.jquery.com/append/)
* - [attr()](http://api.jquery.com/attr/)
* - [bind()](http://api.jquery.com/bind/)
* - [children()](http://api.jquery.com/children/)
* - [clone()](http://api.jquery.com/clone/)
* - [css()](http://api.jquery.com/css/)
* - [data()](http://api.jquery.com/data/)
* - [hasClass()](http://api.jquery.com/hasClass/)
* - [parent()](http://api.jquery.com/parent/)
* - [remove()](http://api.jquery.com/remove/)
* - [removeAttr()](http://api.jquery.com/removeAttr/)
* - [removeClass()](http://api.jquery.com/removeClass/)
* - [removeData()](http://api.jquery.com/removeData/)
* - [replaceWith()](http://api.jquery.com/replaceWith/)
* - [text()](http://api.jquery.com/text/)
* - [trigger()](http://api.jquery.com/trigger/)
*
* ## Additionally these methods extend the jQuery and are available in both jQuery and jQuery lite
* version:
*
*- `scope()` - retrieves the current angular scope of the element.
*
* @param {string|DOMElement} element HTML string or DOMElement to be wrapped into jQuery.
* @returns {Object} jQuery object.
*/
var jqCache = {},
jqName = 'ng-' + new Date().getTime(),
jqId = 1,

49
src/markups.js
View file

@ -1,3 +1,52 @@
/**
* @workInProgress
* @ngdoc overview
* @name angular.markup
* @description
*
* Angular markup transforms content of DOM elements or portions of this content into other text or
* DOM elements for further compilation.
*
* Markup extensions do not themselves produce linking functions. Think of markup as a way to
* produce shorthand for a {@link angular.widget widget} or a {@link angular.directive directive}.
*
* The most prominent example of an markup in angular is the built-in double curly markup
* `{{expression}}`, which is a shorthand for `<span ng:bind="expression"></span>`.
*
* Create custom markup like this:
*
* <pre>
* angular.markup('newMarkup', function(text, textNode, parentElement){
* //tranformation code
* });
* </pre>
*
* For more information about angular markup, see {@link guide/dev_guide.compiler.markup
* Understanding Angular Markup} in the angular Developer Guide.
*/
/**
* @workInProgress
* @ngdoc overview
* @name angular.attrMarkup
* @description
*
* Attribute markup extends the angular compiler in a very similar way as {@link angular.markup}
* except that it allows you to modify the state of the attribute text rather then the content of a
* node.
*
* Create custom attribute markup like this:
*
* <pre>
* angular.attrMarkup('newAttrMarkup', function(attrValue, attrName, element){
* //tranformation code
* });
* </pre>
*
* For more information about angular attribute markup, see {@link guide/dev_guide.compiler.markup
* Understanding Angular Markup} in the angular Developer Guide.
*/
function parseBindings(string) {
var results = [];
var lastIndex = 0;

21
src/validators.js
View file

@ -9,23 +9,24 @@
*
* Following is the list of built-in angular validators:
*
* * {@link angular.Validator.asynchronous asynchronous()} - Provides asynchronous validation via a
* * {@link angular.validator.asynchronous asynchronous()} - Provides asynchronous validation via a
* callback function.
* * {@link angular.Validator.date date()} - Checks user input against default date format:
* * {@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
* * {@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
* * {@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
* * {@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.
* * {@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.
* see {@link guide/dev_guide.templates.validators Understanding Angular Validators} in the angular
* Developer Guide.
*/
extend(angularValidator, {

22
src/widgets.js
View file

@ -9,20 +9,20 @@
*
* 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
* * {@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
* * {@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
* * {@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.
* For more information about angular widgets, see {@link guide/dev_guide.compiler.widgets
* Understanding Angular Widgets} in the angular Developer Guide.
*/
/**