knockout-template-helper

KOTH (knockout-template-helper)

A small node.js library that combines a master template and some knockout templates into one html file. This is very useful useful if you're writing applications with node and knockout.js.

The concept is fairly basic, a master template is an html document which must include a body tag, this is the page which hosts and makes use of your knockout templates.

A template file is an html document with one or more script tags representing a knockout template.

A template has an id attribute unique to its template file. Koth rewrites these ids to provide a dot-path namespace for templates, using the template filename, and directory names in the case of nested directories.

For instance, a directory of templates:

    templates/common.html
    templates/admin/users.html

with contents:

<!-- common.html -->
<script type="text/html" id="messages">
    <div class="message">
        <h3 data-bind="text: title">Message Title </h3> 
        <p data-bind="text: body">Message Body</p>
    </div>
</script>

<script type="text/html" id="actions">
    <ul class="actions" data-bind="foreach: actions" >
        <a data-bind="attr: {href : url}, text: label">Action Label</li>
    </ul>
</script>

<!-- users.html -->
<script type="text/html" id="groups">
    <div class="group">
        <h3 data-bind="text: name">Group name</h3> 
        <ul data-bind="foreach: members">
            <li>...</li> 
        </ul>
    </div>
</script>

Would remap these templates to make them available in master template like so:

<div data-bind="template: { name: 'common.messages', data: myMessages }"></div>
...
<div data-bind="template: { name: 'common.actions', data: actions }"></div>
...
<div data-bind="template: { name: 'admin.users.groups', data: groups }"></div>

This is a particularly simple way to manage templates with the added benefit of namespaces.

API

KOTH provides three ways to make use of its functionality:

• as a basic flattener for one-shot compiling of a static recource (great for pushing to your CDN!), see flatten and flattenDir.
• as a watcher which will call your callback with the compiled result whenever a file changes, (useful for integrating with your own framework).
• and as a connect or express URL handler, provides a function which can be mapped directly to a url (with optional watch-mode for development).

For each of these there is a function which takes a directory of templates and sub-directories to compile, and a function which takes a mapping of {'dot.path.prefix' : '/absolute/file/path.html'}.

Flatteners

flatten(master, templates, callback)

combines a mapping of template files with a master template and calls the callback with the result as a string.

koth.flatten('index.html', {'admin.user' : '/path/to/file.html'}, function(out) {
    console.log(out);
});

flattenDir(master, dir, callback)

combines a directory of template files with a master template and calls the callback with the result as a string.

koth.flattenDir('index.html', '/path/to/templates', function(out) {
    console.log(out);
});

Watchers

watch(master, templates, callback)

combines a mapping of template files with a master template and calls the callback with the result as a string initially and every time a file changes.

koth.watch('index.html', {'admin.user' : '/path/to/file.html'}, function(out) {
    console.log(out);
});

watchDir(master, dir, callback)

combines a directory of template files with a master template and calls the callback with the result as a string initially and every time a file changes.

koth.watchDir('index.html', '/path/to/templates', function(out) {
    console.log(out);
});

Connect / Express integration

connectHandler(master, templates, watch, callback)

combines a mapping of template files with a master template and provides a connect resource handler which takes a request and response object and responds with the compiled result as a valid html response.

app = express.createServer();
koth.connectDirHandler('index.html', {'admin.user' : '/path/to/file.html'}, true, function(handler) {
    app.get('/', handler);
    app.listen(8000);
});

connectDirHandler(master, dir, watch, callback)

combines a directory of template files with a master template and provides a connect resource handler which takes a request and response object and responds with the compiled result as a valid html response.

app = express.createServer();
koth.connectDirHandler('index.html', '/path/to/templates', true, function(handler) {
    app.get('/', handler);
    app.listen(8000);
});