Developer Guide: Angular HTML Compiler: Widgets: Creating Custom Widgets

Work in Progress This page is currently being revised. It might be incomplete or contain inaccuracies.

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:

// An element widget
<my:watch exp="name"/>

You can implement my:watch like this:

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);
   });
 };
});

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:

// An attribute widget (my-watch) in a div tag
<div my-watch="name">text</div>

You can implement my:watch attribute like this:

angular.widget('@my:watch', function(expression, compileElement) {
  var compiler = this;
  return function(linkElement) {
    var currentScope = this;
    currentScope.$watch(expression, function(value){
      alert(value);
    });
  };
});

Live Example of a Custom Element Widget

<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>

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 Compiler API doc.

Related Topics

Related API