Saturday, October 26, 2013

Angularjs directive documentation

It looks like the Angular documentation for directives has changed, but unfortunately a lot of valuable information has been lost in the process. I reproduce part of the original documentation below:
(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. The priority is used to sort the directives before theircompile functions get called. Higher priority goes first. The order of directives within the same priority is undefined.
  • terminal - If set to true then the current priority 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 same priority 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 no attr 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 property localName will reflect the interpolated value of hello {{name}}. As the name attribute changes so will the localName property on the widget scope. The name 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 the attr attribute. If no attr name is specified then the attribute name is assumed to be the same as the local name. Given  and widget definition of scope: { localModel:'=myAttr' }, then widget scope property localModel will reflect the value of parentModel on the parent scope. Any changes to parentModel will be reflected inlocalModel and any changes in localModel will reflect in parentModel.
      • & or &attr - provides a way to execute an expression in the context of the parent scope. If no attr name is specified then the attribute name is assumed to be the same as the local name. Given  and widget definition of scope: { localFn:'&myAttr' }, then isolate scope property localFn will point to a function wrapper for the count = count + valueexpression. 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 is increment(amount) then we can specify the amount value by calling the localFn as localFn({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 (see require 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:
    1. controller: ['$scope', '$element', '$attrs', '$transclude', function($scope, $element, $attrs, $transclude) { ... }]
  • require - Require another controller be passed into current directive linking function. The require 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 of EACM 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 as template 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 to true 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 an isolate scope, but the transclusion is not a child, but a sibling of the isolate 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 the compile property is not defined.