angular.js/docs/content/api/angular.markup.ngdoc

@workInProgress
@ngdoc overview
@name angular.markup

@description
#Overview
Markups allow the angular compiler to transform content of DOM elements or portions of this content
into other text or DOM elements for further compilation. Markup extensions do not themselves produce
linking functions. Think of markup as a way to produce shorthand for a {@link angular.widget widget}
 or a {@link angular.directive directive}.

#`{{}}` (double curly) built-in markup
`{{}}` markup is a built-in markup, which translates the enclosed expression into an
{@link angular.directive.ng:bind ng:bind} directive. It simply transforms

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

to:

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

For example `{{1+2}}` is easier to write and understand than `<span ng:bind="1+2"></span>`. The
expanded elements are then {@link guide.compiler compiled} normally.

# Custom markup
Let's say you want to define this shorthand for a horizontal rule: `---` for `<hr/>`.

In other words, this HTML:
<pre>
header
---
footer
</pre>

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

Here's how the angular compiler could be extended to achieve this:
<pre>
angular.markup('---', function(text, textNode, parentElement) {
  var compiler = this;
  var index = text.indexOf('---');
  if (index > -1) {
    var before = compiler.text(text.substring(0, index));
    var hr = compiler.element('hr');
    var after = compiler.text(text.substring(index + 3));
    textNode.after(after);
    textNode.after(hr);
    textNode.after(before);
    textNode.remove();
  }
});
</pre>

Unlike {@link angular.widget widgets} and {@link angular.directive directives}, in which the
compiler matches the name of handler function to a DOM element or attribute name, for markup 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.