kylefang/angular.js
1
0
Fork 0
mirror of https://github.com/zhigang1992/angular.js.git synced 2026-04-24 03:55:49 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs(compiler): update the compiler docs

Browse Source
This commit is contained in:
Misko Hevery
2011-12-14 02:55:31 +01:00
parent e2b1d9e994
commit 4804c83b7d
50 changed files with 862 additions and 788 deletions
Download Patch File Download Diff File Expand all files Collapse all files

13
docs/content/guide/dev_guide.bootstrap.ngdoc
View File

@@ -31,18 +31,19 @@ and manage the whole page. You do this as follows:
You need to declare the angular namespace declaration in the following cases:
* For all browsers if you are using XHTML.
* For Internet Explorer older than version 9 (because older versions of IE do not render widgets
* For all types of browser if you are using XHTML.
* For Internet Explorer older than version 9 (because older versions of IE do not render namespace
properly for either HTML or XHTML).
## Creating Your Own Namespaces
When you are ready to define your own {@link dev_guide.compiler.widgets widgets}, you must create
your own namespace in addition to specifying the angular namespace. You use your own namespace to
form the fully qualified name for widgets that you create.
When you are ready to define your own {@link api/angular.module.ng.$compileProvider.directive
directive}, you may chose to create your own namespace in addition to specifying the angular
namespace. You use your own namespace to form the fully qualified name for directives that you
create.
For example, you could map the alias `my` to your domain, and create a widget called `my:widget`.
For example, you could map the alias `my` to your domain, and create a directive called `my:directive`.
To create your own namespace, simply add another `xmlns` tag to your page, create an alias, and set
it to your unique domain:

38
docs/content/guide/dev_guide.compiler.directives.creating_directives.ngdoc
View File

@@ -1,38 +0,0 @@
@ngdoc overview
@name Developer Guide: Angular HTML Compiler: Directives: Creating Custom Angular Directives
@description
The following code snippet shows how to define a custom directive. You define a new directive by
extending the {@link dev_guide.compiler Angular HTML compiler}. The code snippet below is a
simplified definition of the built-in {@link api/angular.directive.ng:bind ng:bind} directive:
<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>
# Additional Compiler Methods for Custom Directives
The angular compiler exposes methods that you may need to use when writing your own widgets and
directives. For example, the `descend()` method lets you control whether the compiler ignores or
processes child elements of the element it is compiling. For information on this and other
compiler methods, see the {@link api/angular.module.ng.$compile Compiler API doc}.
## Related Docs
* {@link dev_guide.compiler.directives Understanding Angular Directives}
* {@link dev_guide.compiler.directives_widgets Comparing Directives and Widgets}
* {@link dev_guide.compiler Angular HTML Compiler}
## Related API
* {@link api/angular.directive Angular Directive API}.

47
docs/content/guide/dev_guide.compiler.directives.ngdoc
View File

@@ -1,47 +0,0 @@
@ngdoc overview
@name Developer Guide: Angular HTML Compiler: Understanding Angular Directives
@description
An angular directive is a custom HTML attribute that angular knows how to process. You add them to
a template element like any other attribute. Angular directives all have a `ng:` prefix. In the
following example, the angular directive (`ng:controller`) is a div tag:
<div ng:controller>
You use angular directives to modify DOM element properties. The element you modify can be an
existing HTML element type or a custom DOM element type that you created. You can use any number of
directives per element.
You add angular directives to a standard HTML tag as in the following example, in which we have
added the {@link api/angular.directive.ng:click ng:click} directive to a button tag:
<button ng:click="foo()">Click This</button>
The `ng:click` directive lets you specify click event handlers directly in the template. Unlike the
evil `onclick` attribute, the expression associated with the `ng:click` directive is always executed
in the context of the current angular scope.
In the next example, we add the {@link api/angular.directive.ng:bind ng:bind} directive to a
`<span>` tag:
<span ng:bind="1+2"></span>
The `ng:bind` directive tells angular to set up {@link dev_guide.templates.databinding data
binding} between the data model and the view for the specified expression. When the angular {@link
dev_guide.compiler compiler} encounters an `ng:bind` directive in a template, it passes the
attribute value to the `ng:bind` function, which in turn sets up the data binding. On any change to
the model that would change the result of the expression, the view is updated and the text of the
span element will reflect the new value. In the example above, the model is represented by two
constants, so nothing will ever change - Sorry!
## Related Topics
* {@link dev_guide.compiler Angular HTML Compiler}
* {@link dev_guide.compiler.directives.creating_directives Creating Angular Directives}
* {@link dev_guide.compiler.directives_widgets Comparing Directives and Widgets}
## Related API:
* {@link api/angular.directive Directive API}
* {@link api/angular.widget Widget API}

47
docs/content/guide/dev_guide.compiler.directives_widgets.ngdoc
View File

@@ -1,47 +0,0 @@
@ngdoc overview
@name Developer Guide: Angular HTML Compiler: Comparing Directives and Attribute Widgets
@description
Although directives and {@link dev_guide.compiler.widgets attribute widgets} appear the same in a
template (`ng:init` is a directive, `ng:repeat` is an attribute widget), there is a difference in
the order in which they are evaluated. The user of existing directives or widgets cannot determine
the order of evaluation. The evaluation order is the responsibility of the developer creating
custom directives and widgets.
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. Because we want to run the `ng:init="a=a+1` and
`ng:bind="person"` once for each `person in people`, we need to execute {@link
api/angular.widget.@ng:repeat ng:repeat} to make copies of the `<li>` element before we run the
{@link api/angular.directive.ng:init ng:init}, and {@link api/angular.directive.ng:bind ng:bind}
for each of the `<li>`copies.
If you implemented `ng:repeat` as a directive, there would be no guarantee that the attributes
`ng:repeat`, `ng:init`, and `ng:bind` would be evaluated in the order they are declared, because
the order of element attributes in HTML is not significant to the browser.
So, when creating a custom HTML attribute, you will have to consider whether a directive or a
widget is more appropriate. When the order of execution doesn't matter, directives are the right
choice. In a situation where the order matters and one attribute should be processed with a higher
priority than others, use a widget for the attribute that must be processed first.
## Related Topics
* {@link dev_guide.compiler.directives Understanding Angular Directives}
* {@link dev_guide.compiler.widgets Understanding Angular Widgets}
## Related API:
* {@link api/angular.directive Directive API}
* {@link api/angular.widget Widget API}

96
docs/content/guide/dev_guide.compiler.extending_compiler.ngdoc
View File

@@ -1,96 +0,0 @@
@ngdoc overview
@name Developer Guide: Angular HTML Compiler: Extending the Angular Compiler
@description
Let's say that we want to create a new DOM element called `<my:greeter/>` that displays a greeting.
We want this HTML source:
<pre>
<div ng:init="s='Hello'; n='World'">
<my:greeter salutation="s" name="n"></my:greeter>
</div>
</pre>
to produce this DOM:
<pre>
<div ng:init="s='Hello'; n='World'">
<my:greeter salutation="s" name="n"/>
<span class="salutation">Hello</span>
<span class="name">World</span>!
</my:greeter>
</div>
</pre>
That is, the new `<my:greeter></my:greeter>` tag's `salutation` and `name` attributes should be
transformed by the compiler such that two `<span>` tags display the values of the attributes, with
CSS classes applied to the output.
The following code snippet shows how to write a following widget definition that will be processed
by the compiler. Note that you have to declare the {@link dev_guide.bootstrap namespace} `my` 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(' ');
linkElement.append(nameSpan);
linkElement.append('!');
this.$watch(salutationExp, function(value){
salutationSpan.text(value);
});
this.$watch(nameExp, function(value){
nameSpan.text(value);
});
};
});
</pre>
Note: For more about widgets, see {@link dev_guide.compiler.widgets Understanding Angular Widgets}
and the {@link api/angular.widget widget API reference page}.
# Compilation process for `<my:greeter>`
Here are the steps that the compiler takes in processing the page that contains the widget
definition above:
## Compile Phase
1. Recursively traverse the DOM depth-first.
2. Find the angular.widget definition.
3. Find and execute the widget's compileElement function, which includes the following steps:
1. 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)).
2. Extract the salutation and name HTML attributes as angular expressions.
4. Return the aggregate link function, which includes just one link function in this example.
## Link Phase
1. Execute the aggregate link function, which includes the following steps:
1. Create a <span> element set to the salutation class
2. Create a <span> element set to the name class.
2. Add the span elements to the linkElement. (Note: be careful not to add them to the
compileElement, because that's the template.)
3. Set up watches on the expressions. When an expression changes, copy the data to the
corresponding spans.
## Related Topics
* {@link dev_guide.compiler Angular HTML Compiler}
* {@link dev_guide.compiler.understanding_compiler Understanding How the Compiler Works}
* {@link dev_guide.compiler.testing_dom_element Testing a New DOM Element}
## Related API
* {@link api/angular.module.ng.$compile $compile()}

92
docs/content/guide/dev_guide.compiler.markup.ngdoc
View File

@@ -1,92 +0,0 @@
@ngdoc overview
@name Developer Guide: Angular HTML Compiler: Understanding Angular Markup
@description
Markup in angular is a feature that you can use in templates to transform the content of DOM
elements prior to the compile phase (in which elements are compiled and link functions are
returned. See the {@link dev_guide.compiler compiler docs} for details on how the compiler
works.) The ability to make pre-compile changes to DOM elements lets you create shorthand for
{@link api/angular.widget widget} and {@link api/angular.directive directive} declarations.
Angular provides one built-in markup feature: the double curly-braces used to declare binding
points (between the model and view) for angular expressions. You can also create your own custom
markup.
# Using Double Curly-brace Markup (`{{ }}`)
The double curly-brace (`{{ }}`) markup translates an enclosed expression into an {@link
api/angular.directive.ng:bind ng:bind} directive:
<pre>
{{expression}}
</pre>
is transformed to:
<pre>
<span ng:bind="expression"></span>
</pre>
Markup is useful for the simple reason that `{{1+2}}` is easier to write and understand than `<span
ng:bind="1+2"></span>`. After markup shorthand is expanded into the DOM elements it represents, the
expanded elements are then {@link dev_guide.compiler compiled} normally.
# Creating Custom Markup
Let's say you want to define markup that transforms `---` into a horizontal rule (`<hr/>`):
<pre>
header
---
footer
</pre>
should translate to:
<pre>
header
<hr/>
footer
</pre>
Here is how you could extend the angular compiler to create the "---" markup:
<pre>
angular.markup('---', function(text, textNode, parentElement) {
var compiler = this;
var index = text.indexOf('---');
if (index > -1) {
textNode.after(text.substring(index + 3));
textNode.after(angular.element('<hr>'));
textNode.after(text.substring(0, index));
textNode.remove();
}
});
</pre>
Unlike the way the compiler processes {@link api/angular.widget widgets} and {@link
api/angular.directive directives} (matching the name of the handler function to a DOM element or
attribute name), 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.
## Attribute Markup
Attribute markup extends the angular compiler in a very similar way to markup, except that it
allows you to modify the state of 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>
## Related Topics
* {@link dev_guide.compiler Angular HTML Compiler}
## Related API
* {@link api/angular.module.ng.$compile Compiler API Reference}

9
docs/content/guide/dev_guide.compiler.ngdoc
View File

@@ -2,8 +2,8 @@
@name Developer Guide: Angular HTML Compiler
@description
The core of angular is its HTML compiler. The compiler processes angular directives, widgets, and
markup to transform a static HTML page into a dynamic web application.
The core of angular is its HTML compiler. The compiler processes angular directives allowing them
to transform a static HTML page into a dynamic web application.
The default HTML transformations that the angular compiler provides are useful for building generic
apps, but you can also extend the compiler to create a domain-specific language for building
@@ -15,12 +15,9 @@ All compilation takes place in the web browser; no server is involved.
## Related Topics
* {@link dev_guide.compiler.understanding_compiler Understanding How the Compiler Works}
* {@link dev_guide.compiler.extending_compiler Extending the Angular Compiler}
* {@link dev_guide.compiler.testing_dom_element Testing a New DOM Element}
* {@link dev_guide.compiler.widgets Understanding Angular Widgets}
* {@link dev_guide.compiler.directives Understanding Angular Directives}
* {@link dev_guide.compiler.markup Understanding Angular Markup}
## Related API
* {@link api/angular.module.ng.$compile Angular Compiler API}
* {@link api/angular.module.ng.$compileProvider.directive Directives API}

1
docs/content/guide/dev_guide.compiler.testing_dom_element.ngdoc
View File

@@ -10,7 +10,6 @@
* {@link dev_guide.compiler Angular HTML Compiler}
* {@link dev_guide.compiler.understanding_compiler Understanding How the Compiler Works}
* {@link dev_guide.compiler.extending_compiler Extending the Angular Compiler}
## Related API

66
docs/content/guide/dev_guide.compiler.understanding_compiler.ngdoc
View File

@@ -2,59 +2,27 @@
@name Developer Guide: Angular HTML Compiler: Understanding How the Compiler Works
@description
Every {@link api/angular.widget widget}, {@link api/angular.directive directive} and {@link
dev_guide.compiler.markup markup} is defined with a compile function, which the angular compiler
executes on each widget or directive it encounters. The compile function optionally returns a link
function. This compilation process happens automatically when the page is loaded when you specify
`ng:app` on the root element of the application. (See {@link dev_guide.bootstrap Initializing Angular}.)
The {@link angular.module.ng.$compile compiler} is responsible for applying
{@link angular.module.ng.$compileProvider.directive directives} to the HTML. The directives
extend the behavior of HTML elements and can effect the DOM structure, presentation, and behavior.
This allows Angular to teach the browser new tricks.
The compile and link functions are related as follows:
The compilation starts at the root element and proceeds in a depth-first order. As the compiler
visits each node it collects the directives, orders them by priority and executes their compile
function. The result of the compilation process is a linking function. The linking function
can be used on the template clones to quickly bind the directives with the scope.
* **compile function** — Registers a listener for the widget, directive, or markup expression. The
compiler calls this function exactly once.
* **link function** — Sets up the listener registered by the compile function. This function can be
called multiple times, once per cloned DOM element. For example, in the case of the {@link
api/angular.widget.@ng:repeat repeater widget} used in a list element (`<li ng:repeat="[item in
dataset]"`), the link function gets called to set up a listener on each element in the list.
The result of the compilation process is a live view. We say 'live' since any changes to the
model attached to the {@link angular.module.ng.$rootScope.Scope scope} are reflected in the view,
and any changes in the view are reflected in the scope. This makes the scope the 'single source of
truth'.
Note that angular's built-in widgets, directives, and markup have predefined compile and link
functions that you don't need to modify. When you create your own widgets, directives, or markup,
you must write compile and link functions for them. Refer to the {@link api/angular.module.ng.$compile
Compiler API} for details.
When the angular compiler compiles a page, it proceeds through 3 phases: Compile, Create Root
Scope, and Link:
1. Compile Phase
1. Recursively traverse the DOM, depth-first.
2. Look for a matching compile function of type widget, then markup, then directive.
3. If a compile function is found then execute it.
4. When the compile function completes, it should return a link function. Aggregate this link
function with all link functions returned previously by step 3.
5. Repeat steps 3 and 4 for all compile functions found.
The result of the compilation phase is an aggregate link function, which comprises all of the
individual link functions.
2. Create Root Scope Phase
* Inject all services into the root scope.
3. Link Phase
1. Execute the aggregate link function with the root scope. The aggregate link function calls
all of the individual link functions that were generated in the compile phase.
2. 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, for example, once for each iteration in a repeater.
The angular compiler exposes methods that you will need to make use of when writing your own
widgets and directives. For information on these methods, see the {@link api/angular.module.ng.$compile
Compiler API doc}.
Since directives allow attachment of behavior to the HTML, the angular philosophy is to use the
HTML as Domain Specific Language (DSL) when building an application. For example it may be useful
to declare `TabPanel` directive, or `KeyboardShortcut` directive when for an application.
For details on how directives are created see {@link angular.module.ng.$compileProvider.directive
directives}
## Related Topics

95
docs/content/guide/dev_guide.compiler.widgets.creating_widgets.ngdoc
View File

@@ -1,95 +0,0 @@
@ngdoc overview
@name Developer Guide: Angular HTML Compiler: Widgets: Creating Custom Widgets
@description
When you create your own widgets, you must set up your own namespace for them. (See
dev_guide.bootstrap Initializing Angular} for information about namespaces in angular.)
Let's say we would like to create a new element type in the namespace `my` that can watch an
expression and `alert()` the user with each new value:
<pre>
// An element widget
<my:watch exp="name"></my:watch>
</pre>
You can implement `my:watch` like this:
<pre>
angular.widget('my:watch', function(compileElement) {
var compiler = this;
var exp = compileElement.attr('exp');
return function(linkElement) {
var currentScope = this;
currentScope.$watch(exp, function(value){
alert(value);
});
};
});
</pre>
# Creating a Custom Attribute Widget
Let's implement the same widget as in the example in Defining an Element Widget, but this time as
an attribute that can be added to any existing DOM element:
<pre>
// An attribute widget (my:watch) in a div tag
<div my:watch="name">text</div>
</pre>
You can implement `my:watch` attribute like this:
<pre>
angular.widget('@my:watch', function(expression, compileElement) {
var compiler = this;
return function(linkElement) {
var currentScope = this;
currentScope.$watch(expression, function(value) {
alert(value);
});
};
});
</pre>
# Live Example of a Custom Element Widget
<doc:example>
<doc:source>
<script>
angular.widget('my:time', function(compileElement){
compileElement.css('display', 'block');
return function(linkElement){
function update() {
linkElement.text('Current time is: ' + new Date());
setTimeout(update, 1000);
}
update();
};
});
</script>
<my:time></my:time>
</doc:source>
<doc:scenario>
</doc:scenario>
</doc:example>
# Additional Compiler Methods for Custom Widgets
The angular compiler exposes methods that you may need to use of when writing your own widgets and
directives. For example, the `descend()` method lets you control whether the compiler ignores or
processes child elements of the element it is compiling. For information on this and other
compiler methods, see the {@link api/angular.module.ng.$compile Compiler API doc}.
## Related Topics
* {@link dev_guide.compiler Angular HTML Compiler}
* {@link dev_guide.compiler.directives Angular Directives}
* {@link dev_guide.compiler.widgets Angular Widgets}
* {@link dev_guide.compiler.directives.creating_directives Creating Custom Directives}
## Related API
* {@link api/angular.module.ng.$compile Compiler API}

35
docs/content/guide/dev_guide.compiler.widgets.ngdoc
View File

@@ -1,35 +0,0 @@
@ngdoc overview
@name Developer Guide: Angular HTML Compiler: Understanding Angular Widgets
@description
Widgets are DOM elements that the browser doesn't already understand. Angular provides some
built-in widgets (such as {@link api/angular.widget.@ng:repeat ng:repeat}), and you can create your
own custom widgets.
Widgets are intended to manipulate the DOM tree by adding new elements (unlike {@link
dev_guide.compiler.directives angular directives}, which are intended to modify only element
properties).
Widgets come in two types:
* Element Widget — A custom DOM element. An example of a custom element is shown in {@link
dev_guide.compiler.widgets.creating_widgets Creating Custom Widgets}.
* Attribute Widget — A custom attribute on an existing DOM element. An attribute widget is similar
to an angular directive, with the main difference being that an attribute widget will always be
processed before any directives that are specified on the same element. Only one attribute widget
is allowed per element. An example of an attribute widget is shown in {@link
dev_guide.compiler.widgets.creating_widgets Creating Custom Widgets}.
## Related Topics
* {@link dev_guide.compiler Angular HTML Compiler}
* {@link dev_guide.compiler.directives Angular Directives}
* {@link dev_guide.compiler.widgets.creating_widgets Creating Custom Widgets}
* {@link dev_guide.compiler.directives.creating_directives Creating Custom Directives}
## Related API
* {@link api/angular.module.ng.$compile Compiler API}

10
docs/content/guide/dev_guide.expressions.ngdoc
View File

@@ -58,12 +58,8 @@ You can try evaluating different expressions here:
this.exprs.push(expr);
};
$scope.removeExp = function(contact) {
for ( var i = 0, ii = this.exprs.length; i < ii; i++) {
if (contact === this.exprs[i]) {
this.exprs.splice(i, 1);
}
}
$scope.removeExp = function(index) {
this.exprs.splice(index, 1);
};
}
</script>
@@ -73,7 +69,7 @@ You can try evaluating different expressions here:
<button ng:click="addExp(expr)">Evaluate</button>
<ul>
<li ng:repeat="expr in exprs">
[ <a href="" ng:click="removeExp(expr)">X</a> ]
[ <a href="" ng:click="removeExp($index)">X</a> ]
<tt>{{expr}}</tt> => <span ng:bind="$parent.$eval(expr)"></span>
</li>
</ul>

20
docs/content/guide/dev_guide.forms.ngdoc
View File

@@ -17,7 +17,7 @@ Forms consist of all of the following:
# Form
A form groups a set of widgets together into a single logical data-set. A form is created using
the {@link api/angular.widget.form &lt;form&gt;} element that calls the
the {@link api/angular.module.ng.$compileProvider.directive.form &lt;form&gt;} element that calls the
{@link api/angular.module.ng.$formFactory $formFactory} service. The form is responsible for managing
the widgets and for tracking validation information.
@@ -54,8 +54,8 @@ A form is:
# Widgets
In Angular, a widget is the term used for the UI with which the user input. Examples of
bult-in Angular widgets are {@link api/angular.widget.input input} and
{@link api/angular.widget.select select}. Widgets provide the rendering and the user
bult-in Angular widgets are {@link api/angular.module.ng.$compileProvider.directive.input input} and
{@link api/angular.module.ng.$compileProvider.directive.select select}. Widgets provide the rendering and the user
interaction logic. Widgets should be declared inside a form, if no form is provided an implicit
form {@link api/angular.module.ng.$formFactory $formFactory.rootForm} form is used.
@@ -187,7 +187,7 @@ The following example demonstrates:
<hr/>
Debug View:
<pre>form={{form|json}}</pre>
<pre>master={{master}|json}</pre>
<pre>master={{master|json}}</pre>
<pre>userForm={{userForm|json}}</pre>
<pre>addressForm={{addressForm|json}}</pre>
</div>
@@ -289,15 +289,15 @@ This example shows how to implement a custom HTML editor widget in Angular.
scope.$parseModel = function() {
// need to protect for script injection
try {
this.$viewValue = $sanitize(
this.$modelValue || '');
scope.$viewValue = $sanitize(
scope.$modelValue || '');
if (this.$error.HTML) {
// we were invalid, but now we are OK.
this.$emit('$valid', 'HTML');
scope.$emit('$valid', 'HTML');
}
} catch (e) {
// if HTML not parsable invalidate form.
this.$emit('$invalid', 'HTML');
scope.$emit('$invalid', 'HTML');
}
}
@@ -312,7 +312,7 @@ This example shows how to implement a custom HTML editor widget in Angular.
});
}
angular.module.formModule = function($compileProvider){
angular.module('formModule', [], function($compileProvider){
$compileProvider.directive('ngHtmlEditorModel', function ($formFactory) {
return function(scope, element, attr) {
var form = $formFactory.forElement(element),
@@ -330,7 +330,7 @@ This example shows how to implement a custom HTML editor widget in Angular.
});
};
});
};
});
</script>
<form name='editorForm' ng:controller="EditorCntl">
<div ng:html-editor-model="htmlContent"></div>

2
docs/content/guide/dev_guide.i18n.ngdoc
View File

@@ -22,7 +22,7 @@ http://docs.angularjs.org/#!/api/angular.module.ng.$filter.number number} and {@
http://docs.angularjs.org/#!/api/angular.module.ng.$filter.currency currency} filters.
Additionally, Angular supports localizable pluralization support provided by the {@link
api/angular.widget.ng:pluralize ng:pluralize widget}.
api/angular.module.ng.$compileProvider.directive.ng:pluralize ng:pluralize widget}.
All localizable Angular components depend on locale-specific rule sets managed by the {@link
api/angular.module.ng.$locale $locale service}.

36
docs/content/guide/dev_guide.mvc.understanding_controller.ngdoc
View File

@@ -24,8 +24,8 @@ constructor). Constructors are always applied to an existing scope object.
You set up the initial state of a scope by creating model properties. For example:
function GreetingCtrl() {
this.greeting = 'Hola!';
function GreetingCtrl($scope) {
$scope.greeting = 'Hola!';
}
The `GreetingCtrl` controller creates a `greeting` model which can be referred to in a template.
@@ -43,7 +43,7 @@ As discussed in the {@link dev_guide.mvc.understanding_model Model} section of t
objects (or primitives) assigned to the scope become model properties. Any functions assigned to
the scope, along with any prototype methods of the controller type, become functions available in
the template/view, and can be invoked via angular expressions and `ng:` event handlers (e.g. {@link
api/angular.directive.ng:click ng:click}). These controller methods are always evaluated within the
api/angular.module.ng.$compileProvider.directive.ng:click ng:click}). These controller methods are always evaluated within the
context of the angular scope object that the controller function was applied to (which means that
the `this` keyword of any controller method is always bound to the scope that the controller
augments). This is how the second task of adding behavior to the scope is accomplished.
@@ -78,7 +78,7 @@ instances).
# Associating Controllers with Angular Scope Objects
You can associate controllers with scope objects explicitly via the {@link api/angular.module.ng.$rootScope.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.module.ng.$compileProvider.directive.ng:controller ng:controller
directive} or {@link api/angular.module.ng.$route $route service}.
@@ -105,9 +105,9 @@ string "very". Depending on which button is clicked, the `spice` model is set to
<p>The food is {{spice}} spicy!</p>
</body>
function SpicyCtrl() {
this.spice = 'very';
this.chiliSpicy = function() {
function SpicyCtrl($scope) {
$scope.spice = 'very';
$scope.chiliSpicy = function() {
this.spice = 'chili';
}
}
@@ -144,9 +144,9 @@ previous example.
<p>The food is {{spice}} spicy!</p>
</body>
function SpicyCtrl() {
this.spice = 'very';
this.spicy = function(spice) {
function SpicyCtrl($scope) {
$scope.spice = 'very';
$scope.spicy = function(spice) {
this.spice = spice;
}
}
@@ -171,18 +171,18 @@ have a look at an example:
<p ng:controller="BabyCtrl">Good {{timeOfDay}}, {{name}}!</p>
</body>
function MainCtrl() {
this.timeOfDay = 'morning';
this.name = 'Nikki';
function MainCtrl($scope) {
$scope.timeOfDay = 'morning';
$scope.name = 'Nikki';
}
function ChildCtrl() {
this.name = 'Mattie';
function ChildCtrl($scope) {
$scope.name = 'Mattie';
}
function BabyCtrl() {
this.timeOfDay = 'evening';
this.name = 'Gingerbreak Baby';
function BabyCtrl($scope) {
$scope.timeOfDay = 'evening';
$scope.name = 'Gingerbreak Baby';
}
</pre>

8
docs/content/guide/dev_guide.mvc.understanding_model.ngdoc
View File

@@ -20,17 +20,17 @@ following ways:
* Make a direct property assignment to the scope object in JavaScript code; this most commonly
occurs in controllers:
function MyCtrl() {
function MyCtrl($scope) {
// create property 'foo' on the MyCtrl's scope
// and assign it an initial value 'bar'
this.foo = 'bar';
$scope.foo = 'bar';
}
* Use an {@link dev_guide.expressions angular expression} with an assignment operator in templates:
<button ng:click="{{foos='ball'}}">Click me</button>
* Use {@link api/angular.directive.ng:init ng:init directive} in templates (for toy/example apps
* Use {@link api/angular.module.ng.$compileProvider.directive.ng:init ng:init directive} in templates (for toy/example apps
only, not recommended for real applications):
<body ng:init=" foo = 'bar' ">
@@ -45,7 +45,7 @@ when processing the following template constructs:
The code above creates a model called "query" on the current scope with the value set to "fluffy
cloud".
* An iterator declaration in {@link api/angular.widget.@ng:repeat ng:repeater}:
* An iterator declaration in {@link api/angular.module.ng.$compileProvider.directive.@ng:repeat ng:repeater}:
<p ng:repeat="phone in phones"></p>

4
docs/content/guide/dev_guide.mvc.understanding_view.ngdoc
View File

@@ -9,8 +9,8 @@ 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
ng:controller} and {@link api/angular.widget.ng:view ng:view}, and through bindings of this form:
controller through angular directives, such as {@link api/angular.module.ng.$compileProvider.directive.ng:controller
ng:controller} and {@link api/angular.module.ng.$compileProvider.directive.ng:view ng:view}, and through bindings of this form:
`{{someControllerFunction()}}`. In these ways, the view can call functions in an associated
controller function.

4
docs/content/guide/dev_guide.overview.ngdoc
View File

@@ -101,7 +101,7 @@ These input widgets look normal enough, but consider these points:
* 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" component of the
Model-View-Controller design pattern.
* Note the angular/HTML widget, {@link api/angular.widget.input input}.
* Note the angular/HTML widget, {@link api/angular.module.ng.$compileProvider.directive.input input}.
You may have noticed that when you enter invalid data
or leave the the input fields blank, the borders turn red color, and the display value disappears.
These widgets make it easier to implement field validation than coding them in JavaScript,
@@ -113,7 +113,7 @@ And finally, the mysterious `{{ double curly braces }}`:
This notation, `{{ _expression_ }}`, is a bit of built-in angular {@link dev_guide.compiler.markup
markup}, a shortcut for displaying data to the user. The expression within curly braces gets
transformed by the angular compiler into an angular directive ({@link api/angular.directive.ng:bind
transformed by the angular compiler into an angular directive ({@link api/angular.module.ng.$compileProvider.directive.ng:bind
ng:bind}). The expression itself can be a combination of both an expression and a {@link
dev_guide.templates.filters filter}: `{{ expression | filter }}`. Angular provides filters for
formatting display data.

39
docs/content/guide/dev_guide.scopes.internals.ngdoc
View File

@@ -46,11 +46,11 @@ reside on a child scope, if a property read does not find the property on a scop
recursively check the parent scope, grandparent scope, etc. all the way to the root scope before
defaulting to undefined.
{@link api/angular.directive Directives} associated with elements (ng:controller, ng:repeat,
ng:include, etc.) create new child scopes that inherit properties from the current parent scope.
Any code in Angular is free to create a new scope. Whether or not your code does so is an
implementation detail of the directive, that is, you can decide when or if this happens.
Inheritance typically mimics HTML DOM element nesting, but does not do so with the same
{@link angular.module.ng.$compileProvider.directive directives} associated with elements
(ng:controller, ng:repeat, ng:include, etc.) create new child scopes that inherit properties from
the current parent scope. Any code in Angular is free to create a new scope. Whether or not your
code does so is an implementation detail of the directive, that is, you can decide when or if this
happens. Inheritance typically mimics HTML DOM element nesting, but does not do so with the same
granularity.
A property write will always write to the current scope. This means that a write can hide a parent
@@ -117,24 +117,25 @@ scopes come into play throughout and get a sense of their interactions.
1. At application compile time, a root scope is created and is attached to the root `<HTML>` DOM
element.
2. During the compilation phase, the {@link dev_guide.compiler compiler} matches {@link
api/angular.directive directives} against the DOM template. The directives usually fall into one of
two categories:
- Observing {@link api/angular.directive directives}, such as double-curly expressions
`{{expression}}`, register listeners using the {@link api/angular.module.ng.$rootScope.Scope#$watch $watch()} method.
This type of directive needs to be notified whenever the expression changes so that it can update
the view.
- Listener directives, such as {@link api/angular.directive.ng:click ng:click}, register a
listener with the DOM. When the DOM listener fires, the directive executes the associated
expression and updates the view using the {@link api/angular.module.ng.$rootScope.Scope#$apply $apply()} method.
angular.module.ng.$compileProvider.directive directives} against the DOM template. The directives
usually fall into one of two categories:
- Observing {@link angular.module.ng.$compileProvider.directive directives}, such as double-curly
expressions `{{expression}}`, register listeners using the {@link
api/angular.module.ng.$rootScope.Scope#$watch $watch()} method. This type of directive needs to
be notified whenever the expression changes so that it can update the view.
- Listener directives, such as {@link api/angular.module.ng.$compileProvider.directive.ng:click
ng:click}, register a listener with the DOM. When the DOM listener fires, the directive executes
the associated expression and updates the view using the {@link
api/angular.module.ng.$rootScope.Scope#$apply $apply()} method.
3. When an external event (such as a user action, timer or XHR) is received, the associated {@link
dev_guide.expressions expression} must be applied to the scope through the {@link
api/angular.module.ng.$rootScope.Scope#$apply $apply()} method so that all listeners are updated correctly.
### Directives that create scopes
In most cases, {@link api/angular.directive directives} and scopes interact but do not create new
instances of scope. However, some directives, such as {@link api/angular.directive.ng:controller
ng:controller} and {@link api/angular.widget.@ng:repeat ng:repeat}, create new child scopes using
In most cases, {@link angular.module.ng.$compileProvider.directive directives} and scopes interact but do not create new
instances of scope. However, some directives, such as {@link api/angular.module.ng.$compileProvider.directive.ng:controller
ng:controller} and {@link api/angular.module.ng.$compileProvider.directive.@ng:repeat ng:repeat}, create new child scopes using
the {@link api/angular.module.ng.$rootScope.Scope#$new $new()} method and then attach the child scope to the
corresponding DOM element. You can retrieve a scope for any DOM element by using an
`angular.element(aDomElement).scope()` method call.)
@@ -143,7 +144,7 @@ corresponding DOM element. You can retrieve a scope for any DOM element by using
### Controllers and scopes
Scopes and controllers interact with each other in the following situations:
- Controllers use scopes to expose controller methods to templates (see {@link
api/angular.directive.ng:controller ng:controller}).
api/angular.module.ng.$compileProvider.directive.ng:controller ng:controller}).
- Controllers define methods (behavior) that can mutate the model (properties on the scope).
- Controllers may register {@link api/angular.module.ng.$rootScope.Scope#$watch watches} on the model. These watches
execute immediately after the controller behavior executes, but before the DOM gets updated.
@@ -169,7 +170,7 @@ $watch-ers firing and view getting updated. Similarly, when a request to fetch d
is made and the response comes back, the data is written into the model (scope) within an $apply,
which then pushes updates through to the view and any other dependents.
A widget that creates scopes (such as {@link api/angular.widget.@ng:repeat ng:repeat}) via `$new`,
A widget that creates scopes (such as {@link api/angular.module.ng.$compileProvider.directive.@ng:repeat ng:repeat}) via `$new`,
doesn't need to worry about propagating the `$digest` call from the parent scope to child scopes.
This happens automatically.

2
docs/content/guide/dev_guide.scopes.ngdoc
View File

@@ -14,7 +14,7 @@ the contexts in which Angular creates data-bindings between the model and the vi
In addition to providing the context in which data is evaluated, Angular scope objects watch for
model changes. The scope objects also notify all components interested in any model changes (for
example, functions registered through {@link api/angular.module.ng.$rootScope.Scope#$watch $watch}, bindings created by
{@link api/angular.directive.ng:bind ng:bind}, or HTML input elements).
{@link api/angular.module.ng.$compileProvider.directive.ng:bind ng:bind}, or HTML input elements).
Angular scope objects:

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

@@ -45,7 +45,7 @@ code, observe how the value of `name` changes, based on the HTML element it is d
</doc:scenario>
</doc:example>
The angular {@link api/angular.widget.@ng:repeat ng:repeat} directive creates a new scope for each
The angular {@link api/angular.module.ng.$compileProvider.directive.@ng:repeat ng:repeat} directive creates a new scope for each
element that it repeats (in this example the elements are list items). In the `<ul>` element, we
initialized `name` to "Hank", and we created an array called `names` to use as the data source for
the list items. In each `<li>` element, `name` is overridden. Outside of the `<li>` repeater, the

52
docs/content/guide/dev_guide.services.$location.ngdoc
View File

@@ -434,40 +434,40 @@ In this examples we use `<base href="/base/index.html" />`
this.$location = $location;
}
angular.widget('ng:address-bar', function(tpl) {
return function(elm) {
var browser = browsers[elm.attr('browser')],
input = angular.element('<input type="text" />').val(browser.url()),
delay;
input.bind('keypress keyup keydown', function() {
if (!delay) {
delay = setTimeout(fireUrlChange, 250);
}
});
browser.url = function(url) {
return input.val(url);
};
elm.append('Address: ').append(input);
function fireUrlChange() {
delay = null;
browser.urlChange(input.val());
}
};
});
function initEnv(name) {
var root = angular.element(document.getElementById(name + '-mode'));
angular.bootstrap(root, [function($locationProvider, $provide){
angular.bootstrap(root, [function($compileProvider, $locationProvider, $provide){
$locationProvider.html5Mode = true;
$locationProvider.hashPrefix = '!';
$provide.value('$browser', browsers[name]);
$provide.value('$document', root);
$provide.value('$sniffer', {history: name == 'html5'});
$compileProvider.directive('ngAddressBar', function() {
return function(scope, elm, attrs) {
var browser = browsers[attrs.browser],
input = angular.element('<input type="text" />').val(browser.url()),
delay;
input.bind('keypress keyup keydown', function() {
if (!delay) {
delay = setTimeout(fireUrlChange, 250);
}
});
browser.url = function(url) {
return input.val(url);
};
elm.append('Address: ').append(input);
function fireUrlChange() {
delay = null;
browser.urlChange(input.val());
}
};
});
}]);
root.bind('click', function(e) {
e.stopPropagation();

15
docs/content/guide/dev_guide.templates.css-styling.ngdoc
View File

@@ -9,24 +9,13 @@ Angular sets these CSS classes. It is up to your application to provide useful s
* `ng-invalid`, `ng-valid`
- **Usage:** angular applies this class to an input widget element if that element's input does
notpass validation. (see {@link api/angular.widget.input input} widget).
notpass validation. (see {@link api/angular.module.ng.$compileProvider.directive.input input} widget).
* `ng-pristine`, `ng-dirty`
- **Usage:** angular {@link api/angular.widget.input input} widget applies `ng-pristine` class
- **Usage:** angular {@link api/angular.module.ng.$compileProvider.directive.input input} widget applies `ng-pristine` class
to a new input widget element which did not have user interaction. Once the user interacts with
the input widget the class is changed to `ng-dirty`.
# Marking CSS classes
* `ng-widget`, `ng-directive`
- **Usage:** angular sets these class on elements where {@link api/angular.widget widget} or
{@link api/angular.directive directive} has bound to.
* Old browser support
- Pre v9, IE browsers could not select `ng:include` elements in CSS, because of the `:`
character. For this reason angular also sets `ng-include` class on any element which has `:`
character in the name by replacing `:` with `-`.
## Related Topics

4
docs/content/guide/dev_guide.templates.ngdoc
View File

@@ -13,7 +13,7 @@ These are the types of angular elements and element attributes you can use in a
* {@link dev_guide.compiler.directives Directive} — An attribute that augments an existing DOM
element.
* {@link dev_guide.compiler.widgets Widget} — A custom DOM element. An example of a built-in widget
is {@link api/angular.widget.@ng:repeat ng:repeat}.
is {@link api/angular.module.ng.$compileProvider.directive.@ng:repeat ng:repeat}.
* {@link dev_guide.compiler.markup Markup} — Shorthand for a widget or a directive. The double
curly brace notation `{{ }}` to bind expressions to elements is built-in angular markup.
* {@link dev_guide.templates.filters Filter} — Formats your data for display to the user.
@@ -44,7 +44,7 @@ In a simple single-page app, the template consists of HTML, CSS, and angular dir
in just one HTML file (usually `index.html`). In a more complex app, you can display multiple views
within one main page using "partials", which are segments of template located in separate HTML
files. You "include" the partials in the main page using the {@link api/angular.module.ng.$route
$route} service in conjunction with the {@link api/angular.widget.ng:view ng:view} directive. An
$route} service in conjunction with the {@link api/angular.module.ng.$compileProvider.directive.ng:view ng:view} directive. An
example of this technique is shown in the {@link tutorial/ angular tutorial}, in steps seven and
eight.