Detailed explanation of how to create custom instructions in AngularJS

The example in this article describes how to create custom instructions in AngularJS. Share it with everyone for your reference, the details are as follows:

This is a translation of instructions from angular developers. Mainly intended for developers who are already familiar with the basics of Angular development. This document explains when it is necessary to create your own instructions and how to create them.

What is a directive? From a high level, a directive is a description of the angular $compile service. When a specific tag (attribute, element name, or comment) appears in the DOM, it tells the compiler to append the specified behavior to the DOM.

The process is very simple. There are many useful built-in instructions inside angular, such as ngBind and ngView. Just like you create controllers and services, you can also create your own instructions. When Angular starts, Angular's compiler parses the HTML to match directives, which allows directives to register behavior or change the DOM.

Matching instructions

Before writing instructions, the first thing we need to know is how angular matches an instruction. In the following example, we say that the input element matches the ngModel instruction.

<input ng-model="foo">

The following method It will also match ngModel:

<input data-ng:model="foo">

Angular will normalize the tag name and attribute name of an element to determine which element matches which directive. We refer to directives (such as ngModel) by using standardized camelCase names in js. In HTML, attribute names delimited by '-' are often used to call instructions (such as ng-model).

Standardized processing process:

-remove the x- and data- prefixes on the element or attribute

The following examples show different ways to match the ngBind directive

<span ng-bind="name"></span> <br/>
<span ng:bind="name"></span> <br/>
<span ng_bind="name"></span> <br/>
<span data-ng-bind="name"></span> <br/>
<span x-ng-bind="name"></span> <br/>

Best Practice: Give priority to using the '-' format Name it (eg ng-bind matches ngBind). If you want to pass the HTML validation tool, you can use the 'data-' prefix (such as data-ng-bind). Other format naming exists for historical reasons, avoid using them.

The $compile service can match directives based on element names, attribute names, class names, and annotations.

All directives provided internally by Angular match attribute names, tag names, annotations, or class names. The following different ways can be parsed to

<my-dir></my-dir>
<span my-dir="exp"></span>
<!-- directive: my-dir exp -->
<span class="my-dir: exp;"></span>

Best Practice: Give priority to using tag names and attribute names to use instructions. This makes it easier to understand which element the specified element matches.

Best Practice: Annotations are usually used in the DOM API to restrict the creation of instructions that span multiple elements, such as table elements, and to limit repeated nesting, so annotations must be used. In AngularJS version 1.2, this problem is solved by using ng-repeat-start and ng-repeat-end as a better solution. This approach is recommended where possible.

Binding of text and attributes

During the compilation process, the compiler will use the $interpolate service to detect whether the matched text and attribute values ​​contain embedded expressions. These expressions are registered as watches and can be updated during the digest cycle.

<a ng-href="img/{{username}}.jpg">Hello {{username}}!</a>

ngAttr attribute binding

Browsers are sometimes very picky about the attribute values ​​they consider legal (that is, the attributes of some elements cannot be assigned arbitrarily, otherwise an error will be reported).

For example:

<svg>
 <circle cx="{{cx}}"></circle>
</svg>

When using this writing method, we will find an error reported in the console: Error: Invalid value for attribute cx="{{cx}}". This is due to the limitations of the SVG DOM API. You It cannot simply be written as cx="{{cx}}".

Using ng-attr-cx can solve this problem

If a bound attribute uses the ngAttr prefix (or ng-attr), then in the bound will be applied to the corresponding unprefixed attribute. This method allows you to bind to attributes that need to be processed by the browser immediately (such as the circle[cx] attribute of the SVG element).

So, we can write like this to fix the above problem:

<svg>
 <circle ng-attr-cx="{{cx}}"></circle>
</svg>

Create instructions

First of all, let’s talk about the API for registering instructions. Like the controller, the instructions are registered on the module. The difference is, Directives are registered through the module.directive API. module.directive accepts a standardized name and factory function. This factory function returns an object containing different configurations. This object is used to tell the $compile service how to proceed with the next step.

The factory function is only called once when the compiler matches the instruction for the first time. Usually the initialization work is performed in the factory function. This function is called using $injector.invoke, so it can be used for dependency injection like a controller.

Best Practice: Prioritize returning a defined object rather than returning a function.

Next, we will first understand some common examples, and then go into depth about the principles and compilation process of different configuration items.

Best Practice: 为了避免与某些未来的标准命名冲突，最好前缀化你自己的指令，比如你创建一个指令，它可能会产生冲突，加入HTML7引入相同的元素。推荐使用两三个单词的前缀(比如btfCarousel)，同样不能使用ng或者其他可能与angular未来版本起冲突的前缀。

以下的例子中，我们统一使用my前缀。

模板扩展的指令

当你有大量代表客户信息的模板。这个模板在你的代码中重复了很多次，当你改变一个地方的时候，你不得不在其他地方同时改动，这时候，你就要使用指令来简化你的模板。

我们来创建一个指令，简单的时候静态模板来替换它的内容。

<div ng-controller="Ctrl">
  <div my-customer></div>
 </div>

JS

angular.module('docsSimpleDirective', [])
 .controller('Ctrl', function($scope) {
 $scope.customer = {
  name: 'Naomi',
  address: '1600 Amphitheatre'
 };
 })
 .directive('myCustomer', function() {
 return {
  template: 'Name: {{customer.name}} Address: {{customer.address}}'
 };
 });

注意我们这里做了一些绑定，$compile编译链接

这个例子中，我们直接在template配置项里写上模板，但是随着模板大小的增加，这样非常不优雅。

Best Practice: 除非你的模板非常小，否则更好的是分割成单独的hmtl文件，然后使用templateUrl选项来加载。

假如你熟悉ngInclude，templateUrl跟它非常类似。现在我们使用templateUrl方式重写上面的例子:

<div ng-controller="Ctrl">
  <div my-customer></div>
 </div>

JS：

angular.module('docsTemplateUrlDirective', [])
 .controller('Ctrl', function($scope) {
 $scope.customer = {
  name: 'Naomi',
  address: '1600 Amphitheatre'
 };
 })
 .directive('myCustomer', function() {
 return {
  templateUrl: 'my-customer.html'
 };
 });

my-customer.html

Name: {{customer.name}} Address: {{customer.address}}

非常好，但是如果我们想让我们的指令匹配标签名？ 如果我们只是简单的把元素放在hmtl上面，会发现没有效果。

Note: 创建指令的时候，默认仅使用属性的方式。为了创建一个能由元素名字触发的指令，你需要用到restrict配置。

restrict配置可以按如下方式设置:
-'A' 仅匹配属性名字
-'E' 仅匹配元素名字
-'AE' 可以匹配到属性名字或者元素名

所以，我们可以使用 restrict: 'E'配置我们指令。

<div ng-controller="Ctrl">
  <div my-customer></div>
 </div>

JS

angular.module('docsTemplateUrlDirective', [])
 .controller('Ctrl', function($scope) {
 $scope.customer = {
  name: 'Naomi',
  address: '1600 Amphitheatre'
 };
 })
 .directive('myCustomer', function() {
 return {
  restrict: 'E',
  templateUrl: 'my-customer.html'
 };
 });

my-customer.html

Name: {{customer.name}} Address: {{customer.address}}

Note: 什么时候使用属性名或元素名呢？ 当创建一个含有自己模板的组件的时候，需要使用元素名，如果仅仅是为已有的元素添加功能的话，使用属性名。

使用元素名做为myCustomer指令是非常正确的决定，因为你不是用一些'customer'行为来点缀元素，而是定义一个具有自己行为的元素作为customer组件。

隔离指令的作用域

上面我们的myCustomer指令已经非常好了，但是它有个致命的缺陷，我们在给定的作用域内仅能使用一次。

它现在的实现是，我们每次重用该指令的时候都要为它新创一个控制器。

<div ng-controller="NaomiCtrl">
 <my-customer></my-customer>
</div>
<hr>
<div ng-controller="IgorCtrl">
 <my-customer></my-customer>
</div>

JS

angular.module('docsScopeProblemExample', [])
 .controller('NaomiCtrl', function($scope) {
 $scope.customer = {
  name: 'Naomi',
  address: '1600 Amphitheatre'
 };
 })
 .controller('IgorCtrl', function($scope) {
 $scope.customer = {
  name: 'Igor',
  address: '123 Somewhere'
 };
 })
 .directive('myCustomer', function() {
 return {
  restrict: 'E',
  templateUrl: 'my-customer.html'
 };
 });

my-customer.html

Name: {{customer.name}} Address: {{customer.address}}

这很明显不是一个好的解决方案。

我们想要做的是能够把指令的作用域与外部的作用域隔离开来，然后映射外部的作用域到指令内部的作用域。可以通过创建isolate scope来完成这个目的。这样的话，我们使用指令的scope配置。

<div ng-controller="Ctrl">
 <my-customer customer="naomi"></my-customer>
 <hr>
 <my-customer customer="igor"></my-customer>
</div>

JS

angular.module('docsIsolateScopeDirective', [])
 .controller('Ctrl', function($scope) {
 $scope.naomi = { name: 'Naomi', address: '1600 Amphitheatre' };
 $scope.igor = { name: 'Igor', address: '123 Somewhere' };
 })
 .directive('myCustomer', function() {
 return {
  restrict: 'E',
  scope: {
  customer: '=customer'
  },
  templateUrl: 'my-customer.html'
 };
 });

my-customer.html

Name: {{customer.name}} Address: {{customer.address}}

首先看hmtl，第一个绑定内部作用域的customer到naomi。这个naomi我们在控制器中已经定义好了。第二个是绑定customer到igor。

现在看看scope是如何配置的。

//...
scope: {
 customer: '=customer'
},
//...

属性名(customer)是myCustomer指令上isolated scope的变量名。它的值(=customer)告诉编译器绑定到customer属性。

Note: 指令作用域配置中的'=attr'属性名是被规范化过后的名字，比如要绑定

//...
scope: {
 // same as '=customer'
 customer: '='
},
//...

<div ng-controller="Ctrl">
  <my-customer customer="naomi"></my-customer>
</div>

angular.module('docsIsolationExample', [])
 .controller('Ctrl', function($scope) {
 $scope.naomi = { name: 'Naomi', address: '1600 Amphitheatre' };
 $scope.vojta = { name: 'Vojta', address: '3456 Somewhere Else' };
 })
 .directive('myCustomer', function() {
 return {
  restrict: 'E',
  scope: {
  customer: '=customer'
  },
  templateUrl: 'my-customer-plus-vojta.html'
 };
 });

Name: {{customer.name}} Address: {{customer.address}}
<hr>
Name: {{vojta.name}} Address: {{vojta.address}}

<div ng-controller="Ctrl2">
 Date format: <input ng-model="format"> <hr/>
 Current time is: <span my-current-time="format"></span>
</div>

angular.module('docsTimeDirective', [])
 .controller('Ctrl2', function($scope) {
 $scope.format = 'M/d/yy h:mm:ss a';
 })
 .directive('myCurrentTime', function($timeout, dateFilter) {
 function link(scope, element, attrs) {
  var format,
   timeoutId;
  function updateTime() {
  element.text(dateFilter(new Date(), format));
  }
  scope.$watch(attrs.myCurrentTime, function(value) {
  format = value;
  updateTime();
  });
  function scheduleUpdate() {
  // save the timeoutId for canceling
  timeoutId = $timeout(function() {
   updateTime(); // update DOM
   scheduleUpdate(); // schedule the next update
  }, 1000);
  }
  element.on('$destroy', function() {
  $timeout.cancel(timeoutId);
  });
  // start the UI update process.
  scheduleUpdate();
 }
 return {
  link: link
 };
 });

<div ng-controller="Ctrl">
 <my-dialog>Check out the contents, {{name}}!</my-dialog>
</div>

angular.module('docsTransclusionDirective', [])
 .controller('Ctrl', function($scope) {
 $scope.name = 'Tobias';
 })
 .directive('myDialog', function() {
 return {
  restrict: 'E',
  transclude: true,
  templateUrl: 'my-dialog.html'
 };
 });

<div class="alert" ng-transclude>
</div>

<div ng-controller="Ctrl">
 <my-dialog>Check out the contents, {{name}}!</my-dialog>
</div>

angular.module('docsTransclusionDirective', [])
 .controller('Ctrl', function($scope) {
 $scope.name = 'Tobias';
 })
 .directive('myDialog', function() {
 return {
  restrict: 'E',
  transclude: true,
  templateUrl: 'my-dialog.html',
  link: function (element, scope) {
  scope.name = 'Jeff';
  }
 };
 });

<div class="alert" ng-transclude>
</div>

<div ng-controller="Ctrl">
  <my-dialog ng-hide="dialogIsHidden" on-close="dialogIsHidden = true">
  Check out the contents, {{name}}!
  </my-dialog>
</div>

angular.module('docsIsoFnBindExample', [])
 .controller('Ctrl', function($scope, $timeout) {
 $scope.name = 'Tobias';
 $scope.hideDialog = function () {
  $scope.dialogIsHidden = true;
  $timeout(function () {
  $scope.dialogIsHidden = false;
  }, 2000);
 };
 })
 .directive('myDialog', function() {
 return {
  restrict: 'E',
  transclude: true,
  scope: {
  'close': '&onClose'
  },
  templateUrl: 'my-dialog-close.html'
 };
 });

<div class="alert">
 <a href class="close" ng-click="close()">×</a>
 <div ng-transclude></div>
</div>

angular.module('dragModule', []).
 directive('myDraggable', function($document) {
 return function(scope, element, attr) {
  var startX = 0, startY = 0, x = 0, y = 0;
  element.css({
  position: 'relative',
  border: '1px solid red',
  backgroundColor: 'lightgrey',
  cursor: 'pointer'
  });
  element.on('mousedown', function(event) {
  // Prevent default dragging of selected content
  event.preventDefault();
  startX = event.screenX - x;
  startY = event.screenY - y;
  $document.on('mousemove', mousemove);
  $document.on('mouseup', mouseup);
  });
  function mousemove(event) {
  y = event.screenY - startY;
  x = event.screenX - startX;
  element.css({
   top: y + 'px',
   left: x + 'px'
  });
  }
  function mouseup() {
  $document.unbind('mousemove', mousemove);
  $document.unbind('mouseup', mouseup);
  }
 }
 });

<my-tabs>
  <my-pane title="Hello">
  <h5 id="creating-custom-directives_source_hello">Hello</h5>
  <p>Lorem ipsum dolor sit amet</p>
  </my-pane>
  <my-pane title="World">
  <h5 id="creating-custom-directives_source_world">World</h5>
  <em>Mauris elementum elementum enim at suscipit.</em>
  <p><a href ng-click="i = i + 1">counter: {{i || 0}}</a></p>
  </my-pane>
</my-tabs>

angular.module('docsTabsExample', [])
 .directive('myTabs', function() {
 return {
  restrict: 'E',
  transclude: true,
  scope: {},
  controller: function($scope) {
  var panes = $scope.panes = [];
  $scope.select = function(pane) {
   angular.forEach(panes, function(pane) {
   pane.selected = false;
   });
   pane.selected = true;
  };
  this.addPane = function(pane) {
   if (panes.length == 0) {
   $scope.select(pane);
   }
   panes.push(pane);
  };
  },
  templateUrl: 'my-tabs.html'
 };
 })
 .directive('myPane', function() {
 return {
  require: '^myTabs',
  restrict: 'E',
  transclude: true,
  scope: {
  title: '@'
  },
  link: function(scope, element, attrs, tabsCtrl) {
  tabsCtrl.addPane(scope);
  },
  templateUrl: 'my-pane.html'
 };
 });

<div class="tabbable">
 <ul class="nav nav-tabs">
 <li ng-repeat="pane in panes" ng-class="{active:pane.selected}">
  <a href="" ng-click="select(pane)">{{pane.title}}</a>
 </li>
 </ul>
 <div class="tab-content" ng-transclude></div>
</div>

<div class="tab-pane" ng-show="selected" ng-transclude>
</div>