# $.template

`$.template()` renders HTML templates with JavaScript mixed inside them.

Example:

```html
<script type="text/html">Your platform is <%= navigator.userAgent %></script>
<script>
  $('body').template()
</script>
```

renders all `script[type="text/html"]` as [lodash templates](https://lodash.com/docs/#template).
This displays `Your platform is ...` and shows the userAgent just below the script tag.

- Anything inside `<% ... %>` is executed as Javascript.
- Anything inside `<%= ... %>` is evaluated and rendered in-place.

The template can use all global variables. You can pass additional variables
using as `.template({var1: value, var2: value, ...})`. For example:

<!-- render:html -->
```html
<script type="text/html" class="example">
  <% list.forEach(function(item) { %>
    <div><%= item %></div>
  <% }) %>
</script>
<script>
  $('script.example').template({list: ['a', 'b', 'c']})
</script>
```

To re-render the template, run `.template(data)` again with different data.


## $.template animation

When using `type="text/html"`, templates are re-rendered. To *update* existing
elements, use `data-engine="vdom"` instead. This only changes attributes or
elements that need change. This allows us to animate attributes via CSS.

You need to include [morphdom](https://github.com/patrick-steele-idem/morphdom)
for this to work.

For example, this shows a circle in SVG bouncing around smoothly.

<!-- render:html -->
```html
<style>
  circle { transition: all 1s ease; }
</style>
<script src="../../ui/morphdom/dist/morphdom-umd.min.js"></script>
<script type="text/html" data-engine="vdom" class="bouncing-ball">
  <svg width="500" height="50">
    <circle cx="<%= x %>" cy="<%= y %>" r="5" fill="red"/>
  </svg>
</script>
<script>
  setInterval(function() {
    var x = Math.random() * 500
    var y = Math.random() * 50
    $('.bouncing-ball').template({x: x, y: y})    // Update the template to animate
  }, 1000)
</script>
```

You can also specify a `data-engine` via an option. For example:

```js
$('script.animate').template(data, {engine: 'vdom'})
```


## $.template targets

To re-use the template or render the same template on a different DOM node,
run `.template(data, {target: selector})`. This allows you to declare templates
once and apply them across the body. For example:

<!-- render:html -->
```html
<div class="panel1 bg-primary text-white px-3"></div>
<div class="panel2 bg-success text-white px-3"></div>
<script type="text/html" class="targeted">
  The same template is rendered in <%- heading %>
</script>
<script>
$('script.targeted')
    .template({heading: 'panel 1'}, {target: '.panel1'})
    .template({heading: 'panel 2'}, {target: '.panel2'})
</script>
```

The target can also be specified via a `data-target=".panel1"` on the script
template. This is the same as specifying `{target: '.panel'}`. For example:

```html
<script class="chart" data-target=".panel1">...</script>
<script class="chart" data-target=".panel2">...</script>
```


## $.template append

To append instead of replacing, use `data-append="true"`. Every time `.template`
is called, it appends rather than replaces. For example:

<!-- render:html -->
```html
<script type="text/html" class="list" data-append="true">
  <li>New item #<%- n %> appended</li>
</script>
<script>
$('script.list')
  .template({n: 1})
  .template({n: 2})
</script>
```

You can also specify this as `.template(data, {append: true})`. You can also
append to an [existing target](#template-targets). For example:

<!-- render:html -->
```html
<ul class="existing-list">
  <li>Existing item</li>
  <!-- Every time .template() is called, the result is added as a list item here -->
</ul>
<script>
$('script.list')
    .template({n: 1}, {append: true, target: '.existing-list'})
    .template({n: 2}, {append: true, target: '.existing-list'})
</script>
```


## $.template external source

Template containers can have an `src=` attribute that loads the template from a file:

<!-- render:html -->
```html
<script type="text/html" src="template.html" class="source"></script>
<script>
  $('script.source').template()
</script>
```

If the `src=` URL returns a HTTP error, the HTML *inside* the script is rendered
as a template. The template can use:

- all data passed by the `$().template()` function, and
- an [xhr](http://api.jquery.com/Types/#jqXHR) object - which has error details.

For example:

<!-- render:html -->
```html
<script type="text/html" src="missing.html" class="missing">
  Template returned HTTP error code: <%= xhr.status %>.
  Data is <%= data %>
</script>
<script>
  $('script.missing').template({data: [1, 2, 3]})
</script>
```

## $.template selector

`$(...).template()` renders all `script[type="text/html"]` nodes in or under the
selected node. Use `data-selector=` attribute to change the selector. For
example:

<!-- render:html -->
```html
<section data-selector=".render">
  <script type="text/html" class="no-render">This will not render</script>
  <script type="text/html" class="render">This will render</script>
</section>
<script>
  $('section[data-selector]').template()
</script>
```

You can also use the `selector: ...` option. For example:

<!-- render:html -->
```html
<div class="selector-target"></div>
<script type="text/html" class="try no-render">This will not render</script>
<script type="text/html" class="try render">This will render</script>
<script>
  $('script.try').template({}, {selector: '.render', target: '.selector-target'})
</script>
```


## $.template events

- `template` is fired on the source when the template is rendered. Attributes:
    - `templatedata`: the passed data
    - `target`: the target nodes rendered, as a jQuery object

For example:

<!-- render:html -->
```html
<script type="text/html" class="event">
  <pre>Event e.templatedata = <span class="data">filled by event handler</span></pre>
</script>
<script>
$('script.event')
  .on('template', function(e) {       // When the template is rendered,
    $(e.target).find('.data')         // find the <pre> tag inside target nodes
      .html(JSON.stringify(e.templatedata)) // and enter the template data
  })
  .template({x: 1})                   // Trigger template AFTER .on('template')
</script>
```