ENH: $.template accepts dispose event

docs/template.md

@@ -135,7 +135,6 @@ $('script.list')
 </script>
 ```
 
-
 ## $.template external source
 
 Template containers can have an `src=` attribute that loads the template from a file:
@@ -197,11 +196,36 @@ You can also use the `selector: ...` option. For example:
 ```
 
 
+## $.template dispose
+
+Deletes the output of a rendered template, use `$('...').template('dispose')`.
+This removes the DOM elements last generated by the template.
+
+This is useful for deleting error messages or previous output that's no longer
+relevant.
+
+```js
+  $.getJSON('data').then(function (data) {
+    // When we get data, show the dashboard, dispose any previous error
+    $('script.dashboard').template({ data: data })
+    $('script.error').template('dispose')
+  }).fail(function (xhr, error, msg) {
+    // If there's an error, dispose any previous dashboard, show the error
+    $('script.dashboard').template('dispose')
+    $('script.error').template({ error: msg })
+  })
+```
+
+When [appending](#template-append), this only deletes the last rendered
+template. But this behavior may change.
+
+
 ## $.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
+When a template is rendered or disposed, `template` is fired on the source. Attributes:
+
+- `templatedata`: the passed data argument
+- `target`: the target nodes rendered or disposed, as a jQuery object
 
 For example:
 

src/template.js

@@ -8,6 +8,13 @@ export function template(data, options) {
   // Store this in .data('template.function')
   findall(this, selector).each(function () {
     var $this = $(this)
+    // If we want to dispose the last target, just dispose it.
+    if (data === 'dispose')
+      return $this.trigger({
+        type: 'template',
+        templatedata: data,
+        target: $this.data(_prev_created).remove()
+      })
     var renderer = $this.data(_renderer)
     // If there's no template function cached, cache it
     if (!renderer) {

test/test-template.html

@@ -157,6 +157,7 @@
     })
   </script>
 
+  <!-- Renders to target DOM element -->
   <script class="target-dom" data-target=".target1" type="text/html">1 + 1 = <%= 1 + 1 %></script>
   <script class="target-dom" type="text/html">2 + 2 = <%= 2 + 2 %></script>
   <div class="target1"></div>
@@ -176,6 +177,7 @@
     })
   </script>
 
+  <!-- Appends with data-append even if { append: false } -->
   <script class="append-dom" data-append="true" type="text/html"><i class="new-dom"><%= n %></i><i class="new-dom"><%= n %></i></script>
   <script class="append-dom" data-append="true" data-target=".append-dom-target" type="text/html"><i class="new-dom-target"><%= n %></i><i class="new-dom-target"><%= n %></i></script>
   <div class="append-dom-target"></div>
@@ -199,6 +201,7 @@
     })
   </script>
 
+  <!-- Appends with { append: true } -->
   <script class="append-js" type="text/html"><i class="new-js"><%= n %></i><i class="new-js"><%= n %></i></script>
   <script class="append-js" data-target=".append-js-target" type="text/html"><i class="new-js-target"><%= n %></i><i class="new-js-target"><%= n %></i></script>
   <div class="append-js-target"></div>
@@ -222,6 +225,23 @@
     })
   </script>
 
+  <!-- Disposes output -->
+  <div class="dispose-root">
+    <script type="text/html" class="dashboard"><p class="dashboard">Dashboard</p></script>
+  </div>
+  <script>
+    tape('$().template("dispose") disposes rendered templates', function (t) {
+      t.plan(4)
+      $('.dispose-root').one('template', function (e) {
+        t.equal($('.dispose-root p.dashboard').length, 1)
+      }).template()
+      $('.dispose-root script.dashboard').one('template', function (e) {
+        t.equal($('.dispose-root p.dashboard').length, 0)
+        t.equal(e.templatedata, 'dispose')
+        t.ok(e.target.is('p.dashboard'))
+      }).template('dispose')
+    })
+  </script>
 
   <h1>Morphdom templates</h1>
   <div class="morphdom-t1">