dynamictemplate

Δt - async & dynamic templating engine

npm install dynamictemplate
84 downloads in the last month

Δtdynamictemplate

dynamictemplate is yet another template engine, but this time loaded with full async support and capable of being changed even after the template was rendered.

It works in browsers too.

Check out the demo!

Installation

$ npm install dynamictemplate

Solutions

If any of these problems are familiar to you, you should skip the tl;dr and read the documentation:

  • building a real-time user interface
  • updating large chunks of DOM
  • manipulating nested DOM structures
  • working with a designer
  • isomorph code
  • HTML streaming

TL;DR

Δt provides convenient DOM manipulation in template style for real-time user interfaces.

  • async & dynamic → changeable even after template was rendered
  • pure JavaScript with a hugh {{do you mean "huge"?}} event based api → modular & extendable
  • runs on server and browser side
  • different approach than DOM: don't get your elements out of the black box; keep only those which you need.
  • minimalistic (all the other stuff is hidden in modules :P)

Documentation

Writing and maintaining user interfaces can be hard.

Δt is a new event-based way of writing and maintaining user interfaces in JavaScript.

DOM has grown old. It's one of the legacies from the last millennium that each browser caries with it. Like nearly every browser API, the DOM has an opinionated {{do you mean "inconsistent"?}}, ugly interface to work with: the fastest way to fill a DOM is innerHTML; the way to get information back once it's parsed is by querying it, but the convenient way to manipulate it is by changing, creating and removing nodes. So, WTF? These are the reasons why jquery and mootools are still the most used js libraries. But seriously, have you ever tried to write a large {{better word choice: complex}} user interface with it?

So let's try something new:

var Template = require('dynamictemplate').Template;
var tpl = new Template({schema:'html5'}, function () {
    this.div(function () {
        this.text("hello world");
        this.end();
    });
});
{ Template } = require 'dynamictemplate'
tpl = new Template schema:'html5', ->
    @div ->
        @text "hello world"
        @end()

That was easy. We created a new template instance and with it a new <div> element with some text and closed it.

Let's try something more complex:

function template(view) {
    return new Template({schema:5}, function () {
        this.$div(function () {
            view.on('set title', this.text);
        });
        this.$a(function () {
            this.text("back");
            view.on('navigate', function (url) {
                this.attr('href', url);
            }.bind(this));
        });
    });
}
template = (view) ->
     new Template schema:'5', ->
        @$div ->
            view.on('set title', @text)
        @$a href:'/', ->
            @text "back"
            view.on('navigate', (url) => @attr(href:url))

Ok. Let me explain: we created a div whose text changes on every 'set title' event the view object will emit, and we created an anchor element whose href attribute will change on every 'navigate' event. That's it. Note that the div element will be empty at the beginning. If you play with it a while {{what is "it"?}}, you might hit some known problems from nodejs: flow control. How convenient that it seems that nearly everybody has written her own library. Use your own flow control library! {{I don't understand what you are trying to say here.}} If you don't know any, async might be a good fit.

If you already started playing around with this example, you might have found out that nothing is happing. That is because each this.div call doesn't produce a div tag; it only creates a new and add event with the object representation of the div tag that is its argument. Doesn't sound very useful to you? How about if you use one of the many adapters? An Adapter is a little module that listens for these events and acts accordingly on its domain. This means if you use dt-jquery or dt-dom {{it}} will create a DOM element. In the case of dt-stream, {{it}} will create a nodejs stream instance that emits HTML strings as data.

{{You have a problem with the pronoun "it" -- you know what you are referring to, but I don't. I've put double braces around the occurrences of "it" that are hard to understand.}}

var jqueryify = require('dt-jquery');
tpl = jqueryify(template(view));
// or
var domify = require('dt-dom');
tpl = domify(template(view));
// or
var streamify = require('dt-stream');
tpl = streamify(template(view));

{{Make it explicit that "view" refers the previous example. What do I do with variable tpl once I have it?}}

For more information on the events look at asyncxml which generates them.

Let's have another example:

function template(view) {
    return new Template({schema:5}, function () {
        this.$div({class:'user'}, function () {
            var name = this.a({class:'name'});
            var about = this.span({class:'about'});
            view.on('set user', function setUser(user) {
                name.text(user.name);
                name.attr('href', user.url);
                about.text(user.description);
            });
            setUser(view.currentUser);
            about.end();
            name.end();
        });
    });
}
template = (view) ->
    new Template schema:5, ->
        @$div class:'user', ->
            name = @a(class:'name')
            about = @span(class:'about')
            setUser = (user) ->
                name.text(user.name)
                name.attr(href:user.url)
                about.text(user.description)
            view.on('set user', setUser)
            setUser(view.currentUser)
            about.end()
            name.end()

All right. Here is the trick: unlike the DOM, where you normally have to query most elements, which feels mostly like grabbing into a black box with spiders and snakes, with Δt you already created the tags, so you can store them in variables, scopes and/or closures when you need them.

For more information, look at the various examples and plugins supporting Δt:

Plugins

  • Δt compiler - this compiles static HTML (like mockup files from a designer) to template masks.
  • Δt stream adapter - this lets you use node's beloved Stream to get static HTML from the templates.
  • Δt jquery adapter - this lets you insert the template into the DOM with the help of jQuery.
  • Δt list - this gives all you need to handle an ordered list of tags.
  • Δt selector - this gives you specific selected tags without modifing the template.

Build Status

{{You've told me what all these parts are, but I'm still not sure how they all fit together.}}

npm loves you