combyne: A JavaScript repository from chesles

Stable: 0.3.5

No dependencies. Can be loaded as a browser global, AMD module, and Node module. Works with Browserify. Can be installed via NPM or Bower.

Install.

Node:

npm install combyne

Bower:

bower install combyne

Getting started.

Node.

Require in your source:

var combyne = require("combyne");

AMD.

// Configure the path if necessary.
require({
  paths: {
    combyne: "path/to/combyne"
  }
});

// Use in a module.
define(["combyne"], function(combyne) {});

There is also an AMD plugin for easier consumption and building:

https://github.com/tbranyen/combyne-amd-loader

Browserify.

combynify is a browserify transform plugin to pre-compile combyne templates.

In your code:

var template = require("./template.combyne");
var data = { ... }

template.render(data)

Install combynify and browserify it:

npm install --save-dev combynify
browserify -t combynify main.js > bundle.js

Once the template is precompiled, there is no dependency on the combyne engine.

Browser global.

Include the latest stable in your markup:

<script src="path/to/dist/combyne.js"></script>

Compatibility.

Combyne is written in ES5 and contains polyfills to provide support back to IE 7. These polyfills are omitted in the dist/combyne.js file, but exist in the dist/combyne.legacy.js file. Use this if you are developing/testing with older IE.

Basic usage.

var tmpl = combyne("hello {{msg}}!");
tmpl.render({ msg: "world" });

// => hello world!

Features.

Combyne works by parsing your template into an AST. This provides mechanisms for intelligent compilation and optimization. The template is converted to JavaScript and invoked upon calling render with data.

Security.

By default all templates are encoded to avoid possible issues arising from XSS attacks. This is specifically applied to properties and you can avoid this by using the raw property style: {{{ value }}}. This is very similar to Mustache.

While using this template engine in the browser, it is important to note that you should not trust unknown values to render unencoded. The recommendation is to forget it exists while writing templates in the browser, unless you know what you're doing and have a valid use case.

View this XSS (Cross Site Scripting) Prevention Cheat Sheet for more information.

Comments.

Comments are useful for ignoring anything between the open and close. They can be nested.

var tmpl = combyne("test {%-- not parsed --%}");
tmpl.render();

// => test

Custom delimiters.

If you are not happy with the default Mustache-like syntax, you can trivially change the delimiters to suit your needs. You may only change the delimiters at a global level, because templates are compiled immediately after invoking the combyne function.

// This sets the delimiters, and applies to all templates.
combyne.options.delimiters = {
  START_PROP: "[[",
  END_PROP: "]]"
};

var tmpl = combyne("[[msg]]", { msg: "hello world" });

tmpl.render();
// => hello world

Defaults:

START_RAW:  "{{{"
END_RAW:    "}}}"
START_PROP: "{{"
END_PROP:   "}}"
START_EXPR: "{%"
END_EXPR:   "%}"
COMMENT:    "--"
FILTER:     "|"

Replacing template variables.

var template = "{{foo}}";
var context = { foo: "hello" };

var tmpl = combyne(template);

var output = tmpl.render(context);
/// output == "hello"

Using filters on variables.

var template = "{{foo|reverse}}";
var context = { foo: "hello" };

var tmpl = combyne(template);

tmpl.registerFilter("reverse", function(val) {
  return val.split("").reverse().join("");
});

var output = tmpl.render(context);
/// output == "olleh"

Passing arguments to filters.

You may find that the property value is not enough information for the filter function, in which case you can send additional arguments.

var tmpl = combyne("{{ code|highlight 'javascript' }}");

tmpl.registerFilter("highlight", function(code, language) {
  // Magic highlight function that takes code and language.
  return highlight(code, language);
});

Chaining filters on variables.

var template = "{{foo|reverse|toUpper}}";
var context = { foo: "hello" };

var tmpl = combyne(template);

tmpl.registerFilter("reverse", function(val) {
  return val.split("").reverse().join("");
});

tmpl.registerFilter("toUpper", function(val) {
  return val.toUpperCase();
});

var output = tmpl.render(context);
/// output == "OLLEH"

Conditionals.

Instead of being logic-less, combyne doesn't make any assumptions and allows you to do things like if/elsif/else with simple conditionals, such as if something == somethingElse or if not something. All data types will be coerced to Strings except for Numbers.

var template = "{%if not foo%}why not?{%endif%}";
var context = { foo: false };

var tmpl = combyne(template);

var output = tmpl.render(context);
/// output == "why not?"

or a more complicated example...

var template = "{%if foo == 'hello'%}Hi!{%else%}bye...{%endif%}";
var context = { foo: "hello" };

var tmpl = combyne(template);

var output = tmpl.render(context);
/// output == "Hi!"

elsif is also supported:

var template = "{%if foo == ''%}goodbye!{%elsif foo == 'hello'%}hello!{%endif%}";
var context = { foo: "hello" };

var tmpl = combyne(template);

var output = tmpl.render(context);
/// output == "hello!"

Iterating arrays.

Also works on array-like objects: arguments and NodeList.

var template = "{%each foo%}{{.}} {%endeach%}";
var context = { foo: [1,2,3,4] };

var tmpl = combyne(template);

var output = tmpl.render(context);
/// output == "1 2 3 4 "

Iterating an array of objects shorthand.

If you pass an array of objects to Combyne, you may iterate it via a shorthand:

var template = "{%each%}{{foo}} {%endeach%}";
var context = [{ foo: 1 }, { foo: 2 }, { foo: 3 }, { foo: 4 }];

var tmpl = combyne(template);

var output = tmpl.render(context);
/// output == "1 2 3 4 "

Change the iterated identifer within loops.

var template = "{%each arr as val%}{{val}}{%endeach%}";
var context = { arr: [1,2,3] };

var tmpl = combyne(template);

var output = tmpl.render(context);
/// output = "123"

Iterating objects.

var template = "{%each fruits as val key%}the {{key}} is {{val}}{%endeach%}";
var context = {
  fruits: {
    apple: "green"
  }
};

var tmpl = combyne(template);

var output = tmpl.render(context);
/// output == "the apple is green"

Partials.

var template = "{{foo}} {%partial bar%}";
var context = { foo: "hello" };

var tmpl = combyne(template);

tmpl.registerPartial("bar", combyne("{{name}}", {
  name: "john"
}));

var output = tmpl.render(context);
/// output == "hello john"

Unit tests.

There are many ways to run the unit tests as this library can operate in various environments.

Browser

Open test/index.html in your web browser.

Node

Run the tests inside the Node runtime and within PhantomJS:

grunt test

This will run the tests against the AMD source, the built modern dist/combyne.js, and the built legacy dist/combyne.legacy.js files.

Continuous testing

To keep the PhantomJS tests running continuously, run:

grunt karma:watch

The tests will automatically run whenever files change.

Code coverage

If you run the tests through Karma, a test/coverage directory will be created containing folders that correspond with the environment where the tests were run.

If you are running the defaults you should see something that looks like:

.
└── coverage
    ├── Chrome 33.0.1750 (Linux)
    └── PhantomJS 1.9.7 (Linux)

Inside PhantomJS contains the HTML output that can be opened in a browser to inspect the source coverage from running the tests.

chesles/combyne