dev_guide.compiler.markup.ngdoc

@workInProgress
@ngdoc overview
@name Developer Guide: Angular HTML Compiler: Understanding Angular Markup
@description

Markup in angular is a feature that you can use in templates to transform the content of DOM
elements prior to the compile phase (in which elements are compiled and link functions are
returned.  See the {@link dev_guide.compiler compiler docs} for details on how the compiler
works.)  The ability to make pre-compile changes to DOM elements lets you create shorthand for
{@link api/angular.widget widget} and {@link api/angular.directive directive} declarations.

Angular provides one built-in markup feature: the double curly-braces used to declare binding
points (between the model and view) for angular expressions.  You can also create your own custom
markup.

# Using Double Curly-brace Markup (`{{ }}`)

The double curly-brace (`{{ }}`) markup translates an enclosed expression into an {@link
api/angular.directive.ng:bind ng:bind} directive:

<pre>
{{expression}}
</pre>

is transformed to:

<pre>
<span ng:bind="expression"></span>
</pre>

Markup is useful for the simple reason that `{{1+2}}` is easier to write and understand than `<span
ng:bind="1+2"></span>`. After markup shorthand is expanded into the DOM elements it represents, the
expanded elements are then {@link dev_guide.compiler compiled} normally.


# Creating Custom Markup

Let's say you want to define markup that transforms `---` into a horizontal rule (`<hr/>`):

<pre>
header
---
footer
</pre>

should translate to:
<pre>
header
<hr/>
footer
</pre>

Here is how you could extend the angular compiler to create the "---" markup:

<pre>
angular.markup('---', function(text, textNode, parentElement) {
    var compiler = this;
    var index = text.indexOf('---');
    if (index > -1) {
        textNode.after(text.substring(index + 3));
        textNode.after(angular.element('<hr>'));
        textNode.after(text.substring(0, index));
        textNode.remove();
    }
});
</pre>

Unlike the way the compiler processes {@link api/angular.widget widgets} and {@link
api/angular.directive directives} (matching the name of the handler function to a DOM element or
attribute name), the compiler calls every markup handler for every text node, giving the handler a
chance to transform the text. The markup handler needs to find all the matches in the text.

## Attribute Markup

Attribute markup extends the angular compiler in a very similar way to markup, except that it
allows you to modify the state of attribute text rather then the content of a node.

<pre>
angular.attrMarkup('extraClass', function(attrValue, attrName, element){
 if (attrName == 'additional-class') {
   element.addClass(attrValue);
 }
});
</pre>


## Related Topics

* {@link dev_guide.compiler Angular HTML Compiler}

## Related API

* {@link api/angular.compile Compiler API Reference}