HenrikJoreteg/templatizer HenrikJoreteg/templatizer


Simple solution for compiling jade templates into vanilla JS functions for blazin' fast client-side use.

Host: GitHub

Language: JavaScript

Keywords: browser, jade, templates, templatizer, compiled, options, user


templatizer.js

Build Status

NPM

Simple solution for compiling jade templates into vanilla JS functions for blazin' fast client-side use.

If you're looking for something that works with pug, check out puglatizer.

v2 has been released. See the changelog for breaking changes.

What is this?

Client-side templating is overly complicated, ultimately what you actually want is a function you can call from your JS that puts your data in a template. Why should I have to send a bunch of strings with Mustaches {{}} or other silly stuff for the client to parse? Ultimately, all I want is a function that I can call with some variable to render the string I want.

So, the question is, what's a sane way to get to that point? Enter jade. Simple, intuitive templating, and happens to be what I use on the server anyway. So... Jade has some awesome stuff for compiling templates into functions. I just built templatizer to make it easy to turn a folder full of jade templates into a CommonJS module that exports all the template functions by whatever their file name.

Is it faster?

From my tests it's 6 to 10 times faster than mustache.js with ICanHaz.

How do I use it?

  1. npm install templatizer
  2. Write all your templates as individual jade files in a folder in your project.
  3. Somewhere in your build process do this:
var templatizer = require('templatizer');

// pass in the template directory and what you want to save the output file as
templatizer(
  __dirname + '/templates',
  __dirname + '/output.js',
  options, // Optional
  function (err, templates) { console.log(err || 'Success!') }
);

So a folder like this

/clienttemplates
   user.jade
   app.jade
   /myfolder
     nestedTemplate.jade

Compiles down to a JS file that looks something like this:

var jade = require('jade-runtime') // This is a peerDependency

var templates = {};

// a function built from the `user.jade` file
// that takes your data and returns a string.
templates.user = function () {}

// built from the `app.jade` file
templates.app = function () {} // the function

// folders become nested objects so
// myfolder/nestedTemplate.jade becomes
templates.myFolder = {};
templates.myfolder.nestedTemplate = function () {} // the template function

module.exports = templates;

The awesome thing is... they're just functions at this point. Crazy fast, SO MUCH WIN!!!!

Dependencies

templatizer has jade-runtime as a peerDependency. In npm 3.x.x peerDependencies will no longer be installed by default.

When this happens, you'll want to run the following npm install jade-runtime to install it yourself.

Note: the currently published jade-runtime only works with the upcoming [email protected] release. For now templatizer uses an npm publically scoped module that is a copy of the current runtime @lukekarrys/jade-runtime. This will be changed once [email protected] is released.

API

templatizer(
  templatesDirectory,
  outputFile?,
  options?,
  function (err, templates) {}
)

templatesDirectory (string or array, required)

A string or an array of paths to look for templates.

The path can also be a glob instead that can be used to match *.jade files across multiple directories. For example:

templatizer(__dirname + '/app/**/*.jade', ...);

outputFile (string)

Optionally build the compiled templates to a file. The output will be a CommonJS module. If you don't build to a file, you'll want to supply a callback to do something else with the compiled templates.

Options (object)

jade (object, default {})

jade is an object which will be passed directly to jade.compile(). See the Jade API documentation for what options are available.

Here's an example where we set the Jade compileDebug option to true.

templatizer(templatesDir, outputFile, {
    // Options
    jade: {
        compileDebug: true
    }
});
globOptions (object, default {})

globOptions will be passed directly to node-glob. See the API docs for available options.

transformMixins (boolean, default false)

Set this to true to turn on mixin AST transformations.

Jade has a feature called mixins which when compiled get treated as function declarations within the compiled function. Templatizer can pull these out of the compiled function and place them on the namespace of the parent function. For example:

// users.jade
ul
  each user in users
    mixin user(user)

mixin user(user)
  // Jade mixin content

Templatizer will compile this as

// Compiled fn from file
exports.users = function () {}

// Compiled mixin fn
exports.users.user = function (user) {}

This is helpful as it allows you to call users() to create your list and then users.user() to render just a single item in the list.

Callback (function)

If the last parameter is a function, it will be treated as a callback. The callback will always have the signature function (err, templates) {}. Use this to respond to errors or to do something else with the source of the compiled templates file.

This can be helpful if you don't want to write the compiled templates directly to a file, and you want to make modifications first.

Argument order

Both the outputFile string and options object are optional.

// Use just the callback to do something else with your templates
// besides write them to a file
templatizer(templatesDir, function (err, templates) { });

// Build to a file and do something in the callback
templatizer(templatesDir, outputFile, function (err, templates) { });

// Use only with options
templatizer(templatesDir, { /* options */ }, function (err, templates) { });

// Use with options and outputFile
templatizer(templatesDir, outputFile, { /* options */ }, function (err, templates) { });

Passing client side data to templates

Simply pass in data objects to make those variables available within the template:

templatizer.Template({ title: ..., description: ...});

Using jade's &attributes(attributes) syntax:

templatizer.Template.call({ attributes:{ class: ..., value: ...}} , data);
templatizer.Template.apply({ attributes:{ class: ..., value: ...}} , [data]);

CLI

Templatizer comes with a bin script to use from makefiles/package.json scripts/etc, it works like this:

$ templatizer -d path/to/templates -o /path/to/output/templates.js

Tests

Run npm test to run the tests (you'll need phantomjs installed). You can also run the tests in your browser with npm start and going to http://localhost:3003.

Changelog

  • 2.0.3

  • 2.0.2

  • 2.0.0 Breaking Changes:

    • Async API Pass a callback as the last parameter with the signature function (err, templates) {} to know when compilation is complete.
    • Compiled templates are no longer UMD. The compiled templates are now only a CommonJS module. Global and AMD support have been removed. If you want to consume this file as an AMD module or global, you'll need to do that as part of a build step in your project. Try the require.js conversion tool or amd-wrap for AMD compatibility or creating a standalone build with browserify for global builds.
    • jade-runtime is no longer inlined. jade-runtime is now installed as a peerDependency and required from the compiled templates file.
    • namespace options have been removed. Since the compiled templates no longer have the option to attach to a global variable, the namespace options are no longer relevant.
    • Mixin transformation is now off by default. Mixin transformation can be turned back on by using the option transformMixins: true. Also, the dynamic mixin compiler is no automatically turned on if opting-in to mixin transformation.

License

MIT

Contributors

If you think this is cool, you should follow me on twitter: @HenrikJoreteg


Dependencies

package.json
Kind Requirements Latest Stable Latest Release Licenses
@lukekarrys/jade-runtime peer ^1.11.1 1.11.1 1.11.1 MIT
@lukekarrys/jade-runtime development ^1.11.1 1.11.1 1.11.1 MIT
async runtime ^2.0.1 2.1.5 2.1.5 MIT
browserify development ^13.1.0 14.1.0 14.1.0 MIT
colors development ^1.1.2 1.1.2 1.1.2 MIT
escodegen runtime ^1.8.1 1.8.1 1.8.1 BSD-2-Clause
esprima runtime ^3.0.0 3.1.3 3.1.3 BSD-2-Clause
falafel runtime ^2.0.0 2.0.0 2.0.0 MIT
glob runtime ^7.1.0 7.1.1 7.1.1 ISC
http-server development ^0.9.0 0.9.0 0.9.0 MIT
jade runtime ^1.11.0 1.11.0 1.11.0 MIT
jshint development ^2.9.3 2.9.4 2.9.4 JSON
lodash runtime ^4.16.2 4.17.4 4.17.4 MIT
minimatch runtime ^3.0.3 3.0.3 3.0.3 ISC
minimist runtime ^1.1.3 1.2.0 1.2.0 MIT
mkdirp development ^0.5.1 0.5.1 0.5.1 MIT
phantomjs-prebuilt development ^2.1.12 2.1.14 2.1.14 Apache-2.0
precommit-hook development ^3.0.0 3.0.0 3.0.0 MIT
rimraf development ^2.5.4 2.6.0 2.6.0 ISC
run-browser development ^2.0.2 2.0.2 2.0.2 MIT
tap-spec development ^4.1.1 4.1.1 4.1.1 MIT
tape development ^4.6.0 4.6.3 4.6.3 MIT
tape-run development ^2.1.4 2.2.1 2.2.1 MIT
uglify-js runtime ^2.4.24 2.7.5 2.7.5 BSD-2-Clause
underscore development ^1.8.3 1.8.3 1.8.3 MIT
walkdir runtime 0.0.11 0.0.11 0.0.11 MIT
yetify development 0.1.0 0.1.0 0.1.0 Unknown

Project Statistics

Sourcerank 10
Size 333 KB
Stars 310
Forks 41
Watchers 16
Open issues 3
Dependencies 27
Contributors 26
Tags 21
Created
Last updated
Last pushed

Top Contributors See all

Luke Karrys Henrik Joreteg Darren McElligott Beau Sorensen Aaron McCall Clemens Stolle Gar Philip Roberts johnnyleung Sanjay Pandit Simon Bailey Klaus Bayrhammer Shakhal Levinson Alexandros Tzortzidis Jonathan Blanchet Michael Cox Bryce Kahle Remko Tronçon Chris Novak Hugo Josefson

Projects Referencing this Repo

templatizer 2.0.5
Simple solution for compiling jade templates into vanilla JS functions for blazin' fast client-si...
npm - JavaScript - MIT - Updated - 310 stars

Tags See all

  • v2.0.5 - August 30, 2016 23:48
  • v2.0.4 - August 23, 2016 16:53
  • v2.0.3 - November 05, 2015 15:54
  • v2.0.2 - August 19, 2015 18:29
  • v2.0.1 - August 19, 2015 18:05
  • v2.0.0 - August 19, 2015 17:41
  • v1.5.4 - August 19, 2015 02:17
  • v1.5.3 - August 13, 2015 18:33
  • v1.5.2 - June 20, 2015 01:39
  • v1.5.1 - June 15, 2015 20:34
  • v1.5.0 - June 03, 2015 01:39
  • v1.4.0 - June 03, 2015 01:06
  • v1.3.0 - April 03, 2015 01:53
  • v1.2.1 - February 18, 2015 06:46
  • v1.2.0 - February 15, 2015 01:30
  • v1.1.1 - December 14, 2014 23:15
  • v1.1.0 - November 13, 2014 19:28
  • v1.0.1 - September 14, 2014 01:18
  • v1.0.0 - August 12, 2014 17:56
  • v0.2.9 - January 20, 2014 17:44
  • v0.2.8 - December 19, 2013 01:52

Something wrong with this page? Make a suggestion

Last synced: 2016-11-24 14:13:19 UTC