mirror of
https://github.com/Hopiu/angular.js.git
synced 2026-03-17 15:40:22 +00:00
58d0e8945d
* Load templates once instead of per request * show timing information * load files ending in .ngdoc and process them
53 lines
2.3 KiB
Text
53 lines
2.3 KiB
Text
@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 directives `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>
|
|
</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.
|