Skip to content

G
g1
Commit 87cc1f6b authored by S Anand's avatar S Anand
Browse files
Options

ENH: $.template supports virtualdom. Fixes #126

parent 33e015bd
Pipeline #71676 passed with stage
    in 2 minutes and 53 seconds
    Hide whitespace changes
    Inline Side-by-side
    Showing with 339 additions and 89 deletions
    docs/template.md
    View file @ 87cc1f6b
    ......@@ -34,9 +34,46 @@ using as `.template({var1: value, var2: value, ...})`. For example:
    To re-render the template, run `.template(data)` again with different data.
    ## $.template options
    ## $.template animation
    To re-use the template, i.e. render the same template on a different DOM node,
    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.
    ```html
    <style>
    circle { transition: all 1s ease; }
    </style>
    <script src="../node_modules/morphdom/dist/morphdom-umd.min.js"></script>
    <script type="text/html">
    <svg width="100" height="100">
    <circle cx="<%= x %>" cy="<%= y %>" r="5" fill="red"/>
    </svg>
    </script>
    <script>
    setInterval(function() {
    var x = Math.random() * 100
    var y = Math.random() * 100
    $('body').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:
    ......@@ -47,19 +84,54 @@ $('script.chart')
    .template({}, {target: '.no-heading'})
    ```
    The target can also be specified via a `data-target=".dashboard1"` on the script
    template. This is the same as specifying `{target: '.dashboard'}`. For example:
    ```html
    <script class="chart" data-target=".dashboard1">...</script>
    <script class="chart" data-target=".dashboard2">...</script>
    ```
    ## $.template append
    To append instead of replacing, run `.template(data, {append: true})`. Every
    time `.template` is called, it appends rather than replaces. For example:
    ```js
    $('script.list')
    .template({heading: 'Item 1'}, {append: true}), // Appends the heading
    .template({heading: 'Item 2'}, {append: true}), // instead of replacing it
    ```
    You can also specify this as `<script data-append="true">`. This helps append to
    an existing target. For example:
    ```html
    <script class="list" data-append="true" data-target=".existing-list">...</script>
    <ul class="existing list">
    <li>Existing item</li>
    <!-- Every time .template() is called, the result is added as a list item here -->
    </ul>
    ```
    ## $.template attributes
    ## $.template external source
    Containers support these attributes:
    Template containers can have an `src=` attribute that loads the template from a file:
    - `data-selector` defines the triggers, i.e. which nodes $.template applies to. Default: `script[type="text/html"]`
    - `src` optionally loads the template from a file or URL. e.g. `<script type="text/html" src="template.html"></script>`
    ```html
    <script type="text/html" src="template.html"></script>
    <script>
    $('body').template()
    </script>
    ```
    If the `src=` URL returns a HTTP error, the HTML *inside* the script is rendered as
    a template. The template can use:
    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
    - an [xhr](http://api.jquery.com/Types/#jqXHR) object - which has error details.
    For example:
    ......@@ -73,6 +145,29 @@ For example:
    </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:
    ```html
    <section data-selector="script.lodash-template">
    <script class="lodash-template">...</script>
    </section>
    <script>
    $('section').template()
    </script>
    ```
    You can also render a template by selecting it directly. For example:
    ```html
    <script>
    $('script.lodash-template').template()
    </script>
    ```
    ## $.template events
    ......
    package.json
    View file @ 87cc1f6b
    ......@@ -45,6 +45,7 @@
    "leaflet": "1.3",
    "lodash": "4",
    "moment": "2",
    "morphdom": "2",
    "numeral": "2",
    "popper.js": "1",
    "puppeteer": "0.13",
    ......
    src/template.js
    View file @ 87cc1f6b
    import { findall } from './_util.js'
    var _renderer = 'template.render',
    _target = 'template.target'
    // Bind a template renderer to the node $this.data('template.render')
    // The _renderer function
    // - runs the html template, parses the result, and create a target node
    // - appends the target node after $this (clearing any previous target nodes)
    // - stores the target node in $this.data('template.target')
    // - triggers a template event (with .templatedata, .target)
    // - returns the target node
    function make_template($this, html, data, default_options) {
    var template = _.template(html)
    var $target
    if (!default_options)
    default_options = {}
    function renderer(data, options) {
    // Parse the template output and create a node collection
    // $.parseHTML ensures that "hello" is parsed as HTML, not a selector
    $target = $($.parseHTML(template(data)))
    // Get options. DOM over-rides JS options
    var append = $this.data('append') || (options ? options.append : default_options.append)
    var target = $this.data('target') || (options ? options.target : default_options.target)
    // Render into target node if specified
    // Else, render immediately after source node
    if (typeof target != 'undefined') {
    if (append)
    $(target).append($target)
    else
    $(target).html($target)
    } else {
    // Clear old target nodes if any
    var $old_target = $this.data(_target)
    if ($old_target)
    $old_target.remove()
    // Add the target HTML. "before" ensures that future appends are one below the other
    $this.before($target)
    // Store the target nodes for future reference
    if (!append)
    $this.data(_target, $target)
    }
    // Trigger the template event
    $this.trigger({type: 'template', templatedata: data, target: $target})
    return $target
    }
    $this.data(_renderer, renderer)
    return renderer(data)
    }
    export function template(data, options) {
    var selector = this.data('selector') || 'script[type="text/html"]'
    ......@@ -63,9 +15,9 @@ export function template(data, options) {
    // If the AJAX load succeeds, render the loaded template
    // Else render the contents, with an additional xhr variable
    $.get(src)
    .done(function(html) { make_template($this, html, data, options) })
    .fail(function(xhr) {
    make_template($this, $this.html(), _.extend({xhr: xhr}, data, options))
    .done(function (html) { make_template($this, html, data, options) })
    .fail(function (xhr) {
    make_template($this, $this.html(), _.extend({ xhr: xhr }, data, options))
    })
    } else
    // If no src= is specified, just render the contents
    ......@@ -76,3 +28,111 @@ export function template(data, options) {
    })
    return this
    }
    var _renderer = 'template.render'
    var _prev_target = 'template.prev_target'
    // Bind a template renderer to the node $this.data('template.render')
    // This renderer function accepts (data, options) and creates
    // - runs the html template, parses the result, and create a target node
    // - appends the target node after $this (clearing any previous target nodes)
    // - stores the target node in $this.data('template.target')
    // - triggers a template event (with .templatedata, .target)
    // - returns the target node
    function make_template($this, html, data, default_options) {
    var compiled_template = _.template(html)
    var $target
    if (!default_options)
    default_options = {}
    function renderer(data, options) {
    html = compiled_template(data)
    // Get options. DOM data-* over-rides JS options
    var append = $this.data('append') || (options ? options.append : default_options.append)
    var target = $this.data('target') || (options ? options.target : default_options.target)
    var engine = $this.data('engine') || (options ? options.engine : default_options.engine)
    if (!engine || typeof engine == 'string')
    engine = template.engines[engine] || template.engines['default']
    // If we're appending the contents, just add the text
    if (append) {
    // If we're appending to a target node, just append to it.
    if (target)
    $(target).append($($.parseHTML(html)))
    // If no target node, add BEFORE template. Future appends will be in sequence
    else
    $this.before($($.parseHTML(html)))
    }
    // If we're not appending, replace the contents using the renderer
    else {
    // The engine must return the target nodes. See template.engines spec below
    $target = engine($this, target, html)
    // Store the target nodes for future reference. See template.engines spec below
    $this.data(_prev_target, $target)
    }
    // Trigger the template event. Use "templatedata" since ".data" is reserved
    $this.trigger({ type: 'template', templatedata: data, target: $target })
    return $target
    }
    $this.data(_renderer, renderer)
    return renderer(data)
    }
    // $.fn.template.engines is a registry of rendering engines. Each entry is a
    // function that accepts 3 parameters:
    // $this: the <script> element
    // target: the target selector or node to render into. May be undefined
    // html: the HTML to render at the target (or around $this if target is missing)
    // It returns the target nodes created as a jQuery object. This is used in 2 ways:
    // - the template event.target attribute is this return value
    // - $this.data(_prev_target) is set to this return value
    template.engines = {}
    // The default engine uses jQuery
    template.engines['default'] = template.engines['jquery'] = function ($this, target, html) {
    // Parse the template output and create a node collection
    // $.parseHTML ensures that "hello" is parsed as HTML, not a selector
    var $target = $($.parseHTML(html))
    // If target exists, replace the HTML. Otherwise, create new nodes before the template.
    if (target)
    $(target).html($target)
    else {
    // Remove any previous targets and re-create the output
    var $oldtarget = $this.data(_prev_target)
    if ($oldtarget)
    $oldtarget.remove()
    $this.before($target)
    }
    return $target
    }
    /* globals morphdom */
    template.engines['vdom'] = function ($this, target, html) {
    // If no target is specified, use the previous target, if any
    target = target || $this.data(_prev_target)
    // If a target is specified, wrap the HTML with the target node.
    // For example, <div id="target">...</div> will wrap the HTML with
    // <div id="target"></div>
    var $target, tag_open, tag_close
    if (target) {
    $target = $(target)
    var node = $target.get(0)
    tag_open = '<' + node.nodeName
    $.each(node.attributes, function () {
    tag_open += ' ' + this.name + '=' + this.value
    })
    tag_open += '>'
    tag_close = '</' + node.nodeName + '>'
    }
    // If a target is not specified, Create the target node before the template.
    // Wrap the HTML and the node with <div> to ensure that it's a single node.
    // Morphdom requires a single node.
    else {
    tag_open = '<div>'
    tag_close = '</div>'
    $target = $(tag_open + tag_close).insertBefore($this)
    }
    $target.each(function () {
    morphdom(this, tag_open + html + tag_close)
    })
    return $target
    }
    test/test-template.html
    View file @ 87cc1f6b
    ......@@ -4,14 +4,19 @@
    <title>template tests</title>
    <script src="../node_modules/jquery/dist/jquery.min.js"></script>
    <script src="../node_modules/lodash/lodash.min.js"></script>
    <script src="../node_modules/morphdom/dist/morphdom-umd.min.js"></script>
    <script src="../dist/template.min.js"></script>
    <script src="tape.js"></script>
    <style>
    circle, rect { transition: all 0.5s ease; }
    </style>
    </head>
    <body>
    <script>
    tape.onFinish(function () { window.renderComplete = true })
    </script>
    <h1>Lodash templates</h1>
    <script type="text/html" id="t1">Your platform is <%= navigator.userAgent %></script>
    <script>
    function strip(text) {
    ......@@ -22,20 +27,28 @@
    return node ? strip(node.textContent) : ''
    }
    tape('$().template() renders plain text with variables', function(t) {
    t.plan(2)
    $('#t1').one('template.g1', function(e) {
    t.equal(e.target.length, 1)
    t.equal(text(e.target), 'Your platform is ' + navigator.userAgent)
    })
    .template()
    $('#t1')
    .one('template.g1', function (e) {
    t.equal(e.target.length, 1)
    t.equal(text(e.target), 'Your platform is ' + navigator.userAgent)
    })
    .template()
    .one('template.g1', function (e) {
    t.equal(e.target.length, 1)
    t.equal(text(e.target), 'Your platform is abc')
    t.end()
    })
    .template({navigator: {userAgent: 'abc'}})
    })
    </script>
    <script type="text/html" id="t2">
    <% list.forEach(function(item) { %>
    <div><%= item %></div>
    <% }) %>
    </script>
    <div id="t2">
    <script type="text/html">
    <% list.forEach(function(item) { %>
    <div><%= item %></div>
    <% }) %>
    </script>
    </div>
    <script>
    tape('$().template(data) passes data to the template', function (t) {
    var suffixes = ['x', 'y']
    ......@@ -48,10 +61,8 @@
    var text = $divs.map(function () { return this.innerHTML }).get().join(' ')
    t.equal(text, list.join(' '), 'Template content is correct')
    t.deepEqual(e.templatedata, {list: list})
    e.target
    .filter('div')
    .attr('class', 'item')
    t.equal($('.item').length, 3, 'Repeated calls over-write the same node')
    $divs.attr('class', 'my-unique-item')
    t.equal($('.my-unique-item').length, 3, 'Repeated calls over-write the same node')
    }).template({ list: list })
    })
    })
    ......@@ -106,7 +117,7 @@
    })
    </script>
    <section class="root1">
    <section id="root1">
    <script type="text/html"><%= 1 + 1 %></script>
    <script type="text/html"><%= 2 + 2 %></script>
    </section>
    ......@@ -115,20 +126,20 @@
    var results = ['2', '4']
    t.plan(results.length)
    var index = 0
    $('.root1').on('template', function (e) {
    $('#root1').on('template', function (e) {
    t.equal(text(e.target), results[index++])
    }).template()
    })
    </script>
    <section class="root2" data-selector="script.template">
    <section id="root2" data-selector="script.template">
    <script type="text/html"><div class="result"><%= 1 + 1 %></div></script>
    <script type="text/html" class="template"><div class="result"><%= 2 + 2 %></div></script>
    </section>
    <script>
    tape('$().template() accepts data-selector to select sub-elements', function (t) {
    // The second template (with .template) is triggered, not the first one
    $('.root2').on('template', function (e) {
    $('#root2').on('template', function (e) {
    t.equal(e.target.filter('.result').text(), '4')
    t.end()
    }).template()
    ......@@ -154,35 +165,113 @@
    })
    </script>
    <script class="append-dom" data-append="true" type="text/html"><span class="appended-dom"><%= n %></span></script>
    <script class="append-dom" data-append="true" data-target=".append-dom-target" type="text/html"><span class="appended-dom-target"><%= n %></span></script>
    <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>
    <script>
    tape('$().template() with data-append="true" appends data to target', function (t) {
    var count = 5
    for (var i = 0; i < count; i++) {
    $('script.append-dom').template({ n: i }, {append: false})
    $('script.append-dom').template(
    { n: i },
    { append: false } // append=false is over-ridden by data-append
    )
    }
    t.equal($('.appended-dom').length, count)
    t.equal($('.append-dom-target .appended-dom-target').length, count)
    t.equal($('.new-dom').length, count * 2)
    t.equal($('.append-dom-target .new-dom-target').length, count * 2)
    t.end()
    })
    </script>
    <script class="append-js" type="text/html"><span class="appended-js"><%= n %></span></script>
    <script class="append-js" data-target=".append-js-target" type="text/html"><span class="appended-js-target"><%= n %></span></script>
    <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>
    <script>
    tape('$().template() with {append:true} option appends data to target', function (t) {
    var count = 5
    for (var i = 0; i < count; i++) {
    $('script.append-js').template({ n: i }, {append: true})
    $('script.append-js').template(
    { n: i },
    { append: true }
    )
    }
    t.equal($('.appended-js').length, count)
    t.equal($('.append-js-target .appended-js-target').length, count)
    t.equal($('.new-js').length, count * 2)
    t.equal($('.append-js-target .new-js-target').length, count * 2)
    t.end()
    })
    </script>
    <h1>Morphdom templates</h1>
    <div class="morphdom-t1">
    <script class="morphdom-attr" type="text/html" data-engine="vdom">
    <svg width="100" height="10">
    <circle cx="<%= x %>" cy="5" r="5" fill="<%= color %>"/>
    <rect x="<%= 100 - x %>" y="0" width="10" height="10" fill="green"/>
    </svg>
    <span><%= x %></span>
    <svg width="100" height="10">
    <circle cx="<%= x %>" cy="5" r="5" fill="<%= color %>"/>
    <rect x="<%= 100 - x %>" y="0" width="10" height="10" fill="green"/>
    </svg>
    </script>
    <script class="morphdom-js" type="text/html">
    <b><%= x %></b>
    </script>
    <script class="morphdom-none" type="text/html">
    <i><%= x %></i>
    </script>
    </div>
    <script>
    tape('$().template() with type=text/vdom morphs the same node', function(t) {
    $('.morphdom-t1 .morphdom-attr').template({ x: 0, color: 'white' })
    $('.morphdom-t1 .morphdom-js').template({ x: 0 }, {engine: 'vdom'})
    var $circle = $('.morphdom-t1 circle')
    var $rect = $('.morphdom-t1 rect')
    var $span = $('.morphdom-t1 span')
    var $b = $('.morphdom-t1 b')
    // Use Array() instead of []. Lack of semicolons associates it with previous line
    Array(5, 50, 95).forEach(function(pos) {
    $('.morphdom-t1 .morphdom-attr').template({ x: pos, color: 'red' })
    $('.morphdom-t1 .morphdom-js').template({ x: pos }, { engine: 'vdom' })
    $circle.each(function () {
    t.equal($(this).attr('cx'), String(pos))
    t.equal($(this).attr('fill'), 'red')
    })
    $rect.each(function () { t.equal($(this).attr('x'), String(100 - pos)) })
    $span.each(function () { t.equal($(this).text(), String(pos)) })
    $b.each(function () { t.equal($(this).text(), String(pos)) })
    })
    t.end()
    })
    </script>
    <script type="text/html" class="animated-template" data-engine="vdom">
    <svg class="vdom-result" width="100" height="10"><circle cx="<%= x %>" cy="5" r="5" fill="black"></circle></svg>
    </script>
    <div class="morphdom-target vdom" style="background-color:#afa"></div>
    <div class="morphdom-target vdom" style="background-color:#afa"></div>
    <script type="text/html" class="animated-template" data-target=".morphdom-target" data-engine="vdom">
    <svg class="vdom-result" width="100" height="10"><circle cx="<%= x %>" cy="5" r="5" fill="black"></circle></svg>
    </script>
    <script>
    var $tmpl = $('.animated-template').template({ x: 0 })
    var circles = $('.vdom-result circle').get()
    tape('$().template() with type=text/vdom animates nodes', function(t) {
    t.deepEqual(circles.map(function (c) { return c.getBBox().x }), [-5, -5, -5])
    // In the next cycle, start animation.
    setTimeout(function () {
    $tmpl.template({ x: 100 })
    // After a short interval, check if the SVG element has moved.
    // Default position is -5 (cx - r = 0 - 5 = -5)
    setTimeout(function () {
    var x = _.max(circles.map(function (c) { return c.getBBox().x }))
    t.ok(x > -5, 'x > -5')
    t.ok(x < 95, 'x < 95')
    t.end()
    }, 100)
    }, 0)
    })
    </script>
    </body>
    </html>
    yarn.lock
    View file @ 87cc1f6b
    ......@@ -2710,6 +2710,11 @@ moment@2:
    version "2.21.0"
    resolved "https://registry.yarnpkg.com/moment/-/moment-2.21.0.tgz#2a114b51d2a6ec9e6d83cf803f838a878d8a023a"
    morphdom@2:
    version "2.3.3"
    resolved "https://registry.yarnpkg.com/morphdom/-/morphdom-2.3.3.tgz#70b0aec3db0832688f7fcbde2a8921cf508c4f16"
    integrity sha512-z+/GEulEfhrSFPOJSum8o5lZNv63cAGBPeFHO2WgpGo636Ln67ZuVydp2q0iTaZIXdf5FDNP2ZY6uhtg+LjlsA==
    ms@2.0.0:
    version "2.0.0"
    resolved "https://registry.yarnpkg.com/ms/-/ms-2.0.0.tgz#5608aeadfc00be6c2901df5f9861788de0d597c8"
    ......
    Markdown is supported
    0% or
    You are about to add 0 people to the discussion. Proceed with caution.
    Finish editing this message first!
    Please register or to comment