Docs: Multiple definitions for 'template'.

[Izhaki]

In the Templates docs

In Angular, templates are written with HTML that contains Angular-specific elements and attributes.

OK, so essentially this are HTML snippets, with some custom markup.

In the directive definition object

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 Directives Guide for an example.

Per #8062, this definition is ill to the bone. It should probably say:

Replaces the contents of the element on which the directive is declared with the markup provided in the template property.

But that's now the second template definition, that somehow still works with the first one.

But if the following is a template:

<my-directive></my-directive>

Than the directive template is essentially a template to replace parts of the template above.

Wouldn't changing the template property to contents be better?

In Compile API

Compiles an HTML string or DOM into a template.

Ok, isn't, given the first definition, the HTML string (I guess that's the directive's template) and the DOM are already templates? In other words - for something to be compiled, it must be a template in the first place.

This definition contradicts the first definition, and I can't see way out of this given the first definition.

tElement - template element - The element where the directive has been declared. It is safe to do template transformation on the element and child elements only.

I guess it is titled template element since it has Angular markup, thus it is a template. But given the second definition, this is somewhat confusing.

It then goes on to say:

template instance and the link instance may be different objects if the template has been cloned.

I guess by 'template instance' the meaning is the (pre-linked, or 'complied') template 'blueprint', which may be cloned; and the 'link instance' the meaning is 'the post-linked (rendered) markup'.

The 'if the template has been cloned' makes sense with the first definition

Summary

It seems there are at least 3 definitions for template:

• An HTML that has Angular markup.
• A contents replacement markup in a directive.
• Something that is produced when Angular compiles HTML or DOM

@caitp

[caitp]

It seems there are at least 3 definitions for template:

• An HTML that has Angular markup.
• A contents replacement markup in a directive.
• Something that is produced when Angular compiles HTML or DOM

This isn't quite right, we're generally talking about 2 things when we say template --- and they're both really the same thing, just in different contexts.

So a template is really just markup, that's all it is --- with or without "special elements or attributes".

The two meanings really just distinguish between, in imperative terms, the "caller" and "callee". For instance, if you have an index.html which contains the following:

<main ng-controller="MainCtrl">
  <div my-panel="title">
    <p>...</p>
    <button ng-click="next()">Next</button>
  </div>
</main>

and myPanel has a template on its own like

<div class="panel panel-default">
  <h1 class="panel-heading">{{sectionTitle}}</h1>
  <section class="panel-body">
    <!-- transcluded content goes here -->
  </section>
</div>

Then we really have two templates (chunks of markup), with one being the application template which "invokes" (in imperative terms) the myPanel directive template. They're really the same thing, just different sides of the same coin.

The value you pass to $compile() can also be thought of as a template, but this is really no different from the application template example shown above --- it's a calling template which may (or may not) invoke directive templates which replace and transclude content at their whim.

So, updating the description is fine, but lets not make it too complicated and claim that there are N different meanings for the same term --- a template is just markup, that's all.

[Izhaki]

Thanks @caitp for the detailed reply.

This does clarify some things, but I'm not sure I get this completely, and doubt this will make things clearer for Angular newbies.

I feel that the main issue with the docs is that it was written by people who are Angular experts - they know Angular to the last bit, and often that low-level knowledge makes its way to the docs, serving as completely cryptic text for those new to Angular.

While I think I can read between the lines, let me pretend being the 'dumb' for a minute...

So a template is really just markup, that's all it is --- with or without "special elements or attributes".

OK, so why not call it markup in the first place?

Perhaps I'm thinking C++ here or just in pure dictionary definitions:

Something that serves as a model for others to copy

I can understand that if something is to be cloned, or if it involves some expressions will be bound to the scope, you can call the original markup a template. But how is the app template in your first code example actually a template?

And if a template is just markup, then:

In Angular, templates are written with HTML that contains Angular-specific elements and attributes.

That's incorrect.

Replaces the contents of the element on which the directive is declared with the markup provided in the template property.

That's fine.

Compiles an HTML string or DOM into a template.

So really we compile a template into a template.

Sorry if this seems like nitpicking, but like many, I really struggle with the docs.

[caitp]

Well, they could certainly be written better (and you are invited to contribute to the documentation if you feel it's unclear). Technical writing and user documentation is not easy, and programmers are not necessarily the best people to do it.

[Izhaki]

Sure, but in order to contribute to the docs I'd like to ensure I get it alright.

I still don't understand what is a template. If it is just markup, why call it template?

[caitp]

Well, it's a string of HTML, but there can be interpolation {{foo}}..., you can have structural directives which can change the resulting DOM, so the output markup isn't necessarily an exact copy.

<div>
  <p>Hello, world!</p>
</div>

and

<div ng-init="text = 'Hello, world!'">
  <p>{{text}}</p>
</div>

both output essentially the same DOM (with some very minor attribute/class differences), but render visually identical output, though one is essentially just copied verbatim, and the other has a bit more going on in it.

This is similar to ES6 template literals (also called quasi-literals):

var foo = 3, bar = 6;

console.log(`${foo} + ${bar} = ${foo + bar}`);
// -> Prints "3 + 6 = 9", not "${foo} + ${bar} = ${foo + bar}"

console.log(`jQuery is a DOM manipulation, querying and event handling library`);
// -> Prints "jQuery is a DOM manipulation, querying and event handling library"

The first case changes the output, the second case doesn't --- so it's not quite a string literal, but it's not quite a guarantee of change either. Angular templates are similar to this.

[Izhaki]

OK, I see your point.

Would be nice to get feedback on the following (very very provisional) proposal:

---

Angular facilitates a change in behaviour, content and look between the original HTML markup and that of the rendered DOM. Any markup that is part of such change is considered a template.

Typically, we consider a template to be markup that involves Angular directives or interpolation:

<div my-client>
    <div>{person.name}</div>
    <div>{person.address}</div>
</div>

But the value of the template property is also a template

myApp.directive( 'mark-disabled', function() {
    return {
        template: 'disabled'
    }
});

since wherever the mark-disabled directive is thrown into the HTML the same output will render - the plain 'disabled' string can potentially become a repeating pattern.

---

While it is clear to me, I doubt it will to someone reading this first time. But it's a start alright.