(source: http://code.angularjs.org/1.0.7/docs/guide/directive)
Directive Definition Object
The directive definition object provides instructions to the
compiler
. The attributes are:name
- Name of the current scope. Optional and defaults to the name at registration.priority
- When there are multiple directives defined on a single DOM element, sometimes it is necessary to specify the order in which the directives are applied. Thepriority
is used to sort the directives before theircompile
functions get called. Higherpriority
goes first. The order of directives within the same priority is undefined.terminal
- If set to true then the currentpriority
will be the last set of directives which will execute (any directives at the current priority will still execute as the order of execution on samepriority
is undefined).scope
- If set to:true
- then a new scope will be created for this directive. If multiple directives on the same element request a new scope, only one new scope is created. The new scope rule does not apply for the root of the template since the root of the template always gets a new scope.{}
(object hash) - then a new 'isolate' scope is created. The 'isolate' scope differs from normal scope in that it does not prototypically inherit from the parent scope. This is useful when creating reusable components, which should not accidentally read or modify data in the parent scope.
The 'isolate' scope takes an object hash which defines a set of local scope properties derived from the parent scope. These local properties are useful for aliasing values for templates. Locals definition is a hash of local scope property to its source:@
or@attr
- bind a local scope property to the value of DOM attribute. The result is always a string since DOM attributes are strings. If noattr
name is specified then the attribute name is assumed to be the same as the local name. Given
and widget definition ofscope: { localName:'@myAttr' }
, then widget scope propertylocalName
will reflect the interpolated value ofhello {{name}}
. As thename
attribute changes so will thelocalName
property on the widget scope. Thename
is read from the parent scope (not component scope).=
or=attr
- set up bi-directional binding between a local scope property and the parent scope property of name defined via the value of theattr
attribute. If noattr
name is specified then the attribute name is assumed to be the same as the local name. Given
and widget definition ofscope: { localModel:'=myAttr' }
, then widget scope propertylocalModel
will reflect the value ofparentModel
on the parent scope. Any changes toparentModel
will be reflected inlocalModel
and any changes inlocalModel
will reflect inparentModel
.&
or&attr
- provides a way to execute an expression in the context of the parent scope. If noattr
name is specified then the attribute name is assumed to be the same as the local name. Given
and widget definition ofscope: { localFn:'&myAttr' }
, then isolate scope propertylocalFn
will point to a function wrapper for thecount = count + value
expression. Often it's desirable to pass data from the isolated scope via an expression and to the parent scope, this can be done by passing a map of local variable names and values into the expression wrapper fn. For example, if the expression isincrement(amount)
then we can specify the amount value by calling thelocalFn
aslocalFn({amount: 22})
.
controller
- Controller constructor function. The controller is instantiated before the pre-linking phase and it is shared with other directives if they request it by name (seerequire
attribute). This allows the directives to communicate with each other and augment each other's behavior. The controller is injectable with the following locals:$scope
- Current scope associated with the element$element
- Current element$attrs
- Current attributes object for the element$transclude
- A transclude linking function pre-bound to the correct transclusion scope:function(cloneLinkingFn)
.
To avoid errors after minification the bracket notation should be used:- controller: ['$scope', '$element', '$attrs', '$transclude', function($scope, $element, $attrs, $transclude) { ... }]
require
- Require another controller be passed into current directive linking function. Therequire
takes a name of the directive controller to pass in. If no such controller can be found an error is raised. The name can be prefixed with:?
- Don't raise an error. This makes the require dependency optional.^
- Look for the controller on parent elements as well.
restrict
- String of subset ofEACM
which restricts the directive to a specific directive declaration style. If omitted directives are allowed on attributes only.E
- Element name:A
- Attribute:C
- Class:M
- Comment:
template
- replace the current element with the contents of the HTML. The replacement process migrates all of the attributes / classes from the old element to the new one. See the Creating Components section below for more information.templateUrl
- Same astemplate
but the template is loaded from the specified URL. Because the template loading is asynchronous the compilation/linking is suspended until the template is loaded.replace
- if set totrue
then the template will replace the current element, rather than append the template to the element.transclude
- compile the content of the element and make it available to the directive. Typically used withngTransclude
. The advantage of transclusion is that the linking function receives a transclusion function which is pre-bound to the correct scope. In a typical setup the widget creates anisolate
scope, but the transclusion is not a child, but a sibling of theisolate
scope. This makes it possible for the widget to have private state, and the transclusion to be bound to the parent (pre-isolate
) scope.true
- transclude the content of the directive.'element'
- transclude the whole element including any directives defined at lower priority.
compile
: This is the compile function described in the section below.link
: This is the link function described in the section below. This property is used only if thecompile
property is not defined.