Skip to content
This repository was archived by the owner on Apr 12, 2024. It is now read-only.

Peach #336

Closed
wants to merge 10 commits into from
Closed

Peach #336

Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
77 changes: 42 additions & 35 deletions docs/angular.directive.ngdoc
Original file line number Diff line number Diff line change
Expand Up @@ -4,50 +4,57 @@
@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.
An angular directive is an HTML attribute. You can use directives to modify a DOM element's
properties. The element you modify can be an existing HTML element type, or a DOM element type
that you create as an {@link angular.widget}. 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.
For example, you could add the {@link angular.directive.ng:bind ng:bind} directive as an attribute
of an HTML span element, as in:

<span ng:bind="1+2"></span>

How does this work? The angular {@link guide.compiler compiler} passes the attribute value `1+2`
to the `ng:bind` extension, which in turn tells the {@link angular.scope} to watch that expression
in the data model and report changes. On any change to the expression in the model, the scope 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);
});
};
});
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.
# Directives vs. Attribute Widgets
Directives and attribute widgets look the same in a template (`ng:init` is a directive,
`ng:repeat` is an attribute widget), but they behave slightly differently.

[Attribute widgets](#!angular.widget) and directives can both compile a DOM element
attribute, so why have two different ways to do the same thing? The answer is that the order in
which attribute directives get processed matters, but we have no control over the order in which
attributes are read. To solve this, we use an attribute widget. Widgets always run before
directives in a particular element. So we apply an attribute widget before any directives when we
need to control the order in which attributes are processed. Widgets may manipulate the DOM,
whereas directives are not expected to do so, and so directives run after widgets.

For example, consider this piece of HTML, which uses the directives `ng:repeat`, `ng:init`,
and `ng:bind`:
For example, consider this piece of HTML, which uses `ng:repeat`, `ng:init`, and `ng:bind`:
<pre>
<ul ng:init="people=['mike', 'mary']">
<li ng:repeat="person in people" ng:init="a=a+1" ng:bind="person"></li>
</ul>
<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.directive.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.
{@link angular.directive.ng:init ng:init} and {@link angular.directive.ng:bind 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 a directive to implement the repeater in 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 widget ensures that we can
transform the DOM element into the template we intended.
5 changes: 2 additions & 3 deletions docs/angular.element.ngdoc
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
@function

@description
Wraps a raw DOM element or HTML string as [jQuery](http://jquery.com) element.
Wraps a raw DOM element or HTML string as a [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.
Expand Down Expand Up @@ -40,8 +40,7 @@ raw DOM references.
- [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:
## These methods extend jQuery and are available in both jQuery and jQuery lite versions:

- `scope()` - retrieves the current angular scope of the element.

Expand Down
34 changes: 18 additions & 16 deletions docs/angular.markup.ngdoc
Original file line number Diff line number Diff line change
Expand Up @@ -4,39 +4,41 @@

@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}.
Markups allow the angular compiler to transform the content of DOM elements (or portions of the
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
# The Double Curly Braces Markup
The `{{ }}` markup is built-in to angular. It translates an enclosed expression into an
{@link angular.directive.ng:bind ng:bind} directive:

<pre>
{{expression}}
</pre>

to:
is translated 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
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
# Custom Markup
Let's say you want to define this shorthand for a horizontal rule: `---` for `<hr/>`.

In other words, this HTML:
In other words, you want this HTML:

<pre>
header
---
footer
</pre>

should translate to:
to translate to:

<pre>
header
<hr/>
Expand All @@ -60,7 +62,7 @@ angular.markup('---', function(text, textNode, parentElement) {
});
</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.
For {@link angular.widget widgets} and {@link angular.directive directives}, the compiler matches
the name of the handler function to a DOM element or attribute name. But 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.
33 changes: 17 additions & 16 deletions docs/guide.bootstrap.ngdoc
Original file line number Diff line number Diff line change
Expand Up @@ -62,36 +62,37 @@ equivalent to the code in the previous section.

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
1. 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
1. 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.
**IMPORTANT:** When using angular, you must declare the `ng` namespace using the `xmlns` tag in
the following scenarios:

<pre>
<html xmlns:ng="http://angularjs.org">
</pre>
* If you are using XHTML
* If you are targeting IE older than 9 (regardless of whether you are using XHTML or HTML).

If you don't declare the `ng` namespace in either of these scenarios, your browser will not render
widgets properly. To declare the `ng` namespace:

<html xmlns:ng="http://angularjs.org">


# 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:
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>
<html xmlns:my="http://mydomain.com">


# 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.

The angular script creates a single global variable `angular` in the global namespace. All APIs
are bound to fields of this global object.
42 changes: 42 additions & 0 deletions docs/guide.building.ngdoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
@workInProgress
@ngdoc overview
@name Developer Guide: Building Angular Apps
@description


# Bootstrapping Angular
## Bootstrap Automatically
## Bootstrap Manually
# Working With Angular Templates
## Expressions
## Directives (and widgets, markup)
## CSS
# Working With the Data Model
## Creating a Data Model
### Implicit
### Explicit
## Server Communications
### $xhr
### $resource
# Working With Controllers
## Creating
### Declaring
### Coding in JavaScript
### Instantiating
## Using DI With Controllers
### Declaring dependencies for the Injector
# Working With Angular Services
## Using DI With Services
## Creating / Registering a service
## Instantiating
## Built-in Services
### List, Describe, Examples, Links to API
## Writing Your Own Services
# Working With Advanced Dependency Injection
## Inferring dependencies from the signature of the factory function or constructor
## "Currying" of arguments
# Extending the Angular HTML Compiler
## Extension points (widgets, directives, markup, filters)
## The apis
## How to create custom extensions
## How to test all of these custom extensions
Loading