shinesolutions / jazz

Template engine for nodejs

Jazz is a simple template engine built specifically for nodejs.

Usage

var jazz = require("jazz");
var sys = require("sys");

var template = jazz.compile("my template source code {someVariable}");
template.eval({"someVariable": "lolmuffin"}, function(data) { sys.puts(data); });

This example would output the following:

my template source code lolmuffin

Syntax

Printing variables

{someVariable}

This works for any type of expression, so the following should also work:

{users.fred}
{"hello"}
{45}
{a eq b}

Filter functions

You can call filter functions like so:

{someFilter(arg1, arg2)}

Filter functions are statements, NOT expressions so they cannot be chained nor used in if/forelse/etc. tests. However, calls can be made on any type of expression -- e.g.

{math.sin(45)}

Implementing filter functions

Filter functions may block so rather than returning the value you want rendered as you might in other frameworks, jazz passes in a callback to your filter function that you then call to indicate that you have a result. e.g. here we simulate a blocking operation using setTimeout().

// sum.jazz

{sum(5, 10)}

// sum.js

var jazz = require("jazz");

var params = {
    sum: function(arg1, arg2, cb) {
        setTimeout(function() {
            cb((arg1 + arg2).toString());
        }, 2000);
    }
}
jazz.compile("sum.jazz").eval(params, function(output) { console.log(output); });

Note that even though the execution of the callback is delayed, this example still works.

Conditional Statements

You can check if a variable evaluates to a true value like so:

{if name}
    Hello, {name}
{end}

Else clauses are also supported:

{if name}
    Hello, {name}
{else}
    Hello, Captain Anonymous
{end}

As are else..if clauses:

{if firstName}
    Hello, {firstName}
{elif lastName}
    Hello, Mr. {lastName}
{else}
    Hello, Captain Anonymous
{end}

Limited logical expressions are also possible:

{if user.lastName and user.isVip}
    Hello, Mr. {user.lastName}, my good man!
{end}

{if fred.tired or fred.bored}
    Fred: "Yawn!"
{end}

{if not awake}
    Zzz
{end}

eq & neq comparison operators are available for comparing two values:

{if config.feature eq "enabled"}
    Feature is enabled!
{end}

{if status neq "inactive"}
    Huzzah!
{end}

You can also group expressions using parentheses:

{if (a and b) or c}
    ...
{end}

Looping over an array

{foreach item in someArray}
    <p>{item}</p>
{end}

The value being iterated over can be any expression supporting an Array-like interface.

Looping over an object

{foreach pair in someObject}
    <p>{pair.key} = {pair.value}</p>
{end}

Synchronous functions

{if @blah('a')}
    <p>There were so many blahs in a</p>
{end}

The function is provided to the template the same way asynchronous functions are, just with a return instead of a cb.

Loop counters / index

{foreach pair in someObject}
    <p>Loop number (1 based): {__count}</p>
    <p>Index (0 based): {__index}</p>
    <p>{pair.key} = {pair.value}</p>
{end}

Looking into arrays/objects

    <p>{object['array'][0].cheese}</p>

jazz's Issues

Inefficient complete checking

Instead of checking if all chunks is ready, check it only when one of them is ready - add
if (__jazz_expected == __jazz_seen) __jazz_cb(__jazz_output.join(''));
to
__jazz_emitter.addListener('data', function(pos, chunk) { ... })

For ... Until Loop

A loop which goes trough a defined amount of numbers, would be very helpful.

A simple example

 {for number from 0 until 10}
      <p>{number}</p>
 {end}

More complex example with stepwidth

 {for number from 0 until 10 step 2}
      <p>{number}</p>
 {end}

Access of Variables/Parameters Within Function Calls

Is there the possibly to set variables as a parameter within function calls? This functionality would be very helpful - especially within foreach loops.

{foreach item in someArray}
    <p>{doSomething({item})}</p>
{end}

Explain "@" in readme

I love the simplicity of jazz, but I'm sure you know, the readme could use a bit of help.

The thing that I was totally confused about was it was mentioned nowhere that in order to call a function other than a filter function, that you needed to include an "@". This is also skipped over in your tutorial but I just happened to catch it.

Plus, you should at least include a link to your tutorial (http://tomlee.co/2011/04/intro-to-jazz-templates-for-nodejs/)

ALSO:
I've been considering putting together a helper module that works as a manager for these templates as I have done in my own projects. But before I do it, is there another templating module that has replaced this one in your new projects?

More of a question...

I have this line

function jazzIt(fileName, data) {
data = data||{};
var filedata = fs.readFileSync( parts_dir +'/'+ fileName +'.jazz', 'utf8' );
var template = jazz.compile( filedata );
return template.eval( data, function(data) { sys.puts(template); } );
}

...what happens in eval() ? -Nothing get printed in console, nothing is returned.

I need the parsed template back from the function for further handling, how do I go about achieving that?

Thanks!
//gnimm

Escaping curved brackets

Do you know if it's possible - in any way - to escape curved brackets within jazz files? I have some templates which contains JavaScript functions and therefore I need curved brackets for the function definition.

At the moment i have to include the JavaScript over a external function, which works but not very uncomfortable.

Incorporate some of the improvements by Softmotions

This fork of jazz has some interesting/nice little additions that might be worth cherry-picking:

https://github.com/Softmotions/jazz/commits/master

Not sure I like the "define" keyword, but things like the gc-friendly stuff & handling array accesses in function arguments is kinda nice.

help in loop

hi，how to get index in a "foreach"？