monkberry

Monkberry - JavaScript template engine

Monkberry compile template to JavaScript code for creating nodes with DOM API and helper methods for updating content of these nodes.

npm install monkberry --save

Features

• Small, dependency free
• Simple and minimalistic
• Fully tested
• One-way data flow
• Precompiled templates
• SourceMaps
• Custom tags
• Extremely fast!

Table of Contents

• Example
• Documentation
  • Getting Started
  • Expressions
  • If, Else
  • For
  • Filters
  • Custom tags
  • Prerender
  • Wrappers
  • Transforms
  • Parsers
• Tests
• Benchmarks

Example

Monkberry will compile this template:

<div>
  <h1>{{ title }}</h1>
  <p>
    {{ text }}
  </p>
</div>

To JavaScript code like this:

var div = document.createElement('div');
var h1 = document.createElement('h1');
var p = document.createElement('p');

div.appendChild(h1);
div.appendChild(p);

   ...

view.update = function (data) {
  h1.textContent = data.title;
  p.textContent = data.text;
};

Which can be used like that:

var view = monkberry.render('template');
document.body.appendChild(view.dom()); 

view.update({
  title: 'Monkberry',
  text: 'JavaScript DOM template engine'
});

Documentation

Getting Started

Monkberry has support for both browserify via monkberrify and for webpack via monkberry-loader.

Monkberry can be used like CLI tool. Install Monkberry globally:

npm install monkberry -g

To compile all templates into single JavaScript file with source map run next command:

monkberry --source-map --output template.js templates/*.html

Require generated template.js and monkberry.js files and mount template:

var monkberry = require('monkberry');
var template = require('./template.js');

monkberry.mount(template);

Render that view.

var view = monkberry.render('template'); 
// or
var view = monkberry.render('template', {...}); 

Attach generated DOM nodes to the page.

document.getElementById('root').appendChild(view.dom());

Now, to update data of view on page:

view.update({...});
// or update only what's needed
view.update({key: value});

Expressions

Monkberry perceives everything inside {{ and }} mustache as JavaScript expression.

<div class="greetings {{ visible ? '' : 'hidden' }}">
  Hello, {{ user.name + "!" }}
</div>

If, Else

Can be any valid JavaScrpt expressions.

{% if count < 0 || count > 10 %}
  ...
{% else %}
  ...
{% endif %}

Any number on variables in if:

{% if array.indexOf(search) != -1 %}
  ...
{% endif %}

Note what Monkberry update only one of if/else block.

{% if check %}
  Then {{ value }}!
{% else %}
  Else {{ value }}!
{% endif %}

Render that template:

var view = monkberry.render('example', {
  check: true,
  value: 'one'
});

View will be Then one!. When if update view:

view.update({
  check: false,
  value: 'two'
});

View will be Else two!. But if update only check, variable of then part will be same as before.

view.update({check: true});

View will be Then one!.

This is happens becouse Monkberry does not stores variables passed to update function, it stores only DOM nodes. Monkberry will update only one part of if/else.

For

Monkberry can loop other arrays and objects as well.

{% for array %}
  {{ name }}
{% endfor %}

In this form, body of for has access only for variables iterating on.

view.update({
  array: [
    {name: 'Anton'},
    ...
  ]
});

To access outer scope specify iterator name.

{% for user of array %}
  {{ user.name }}
{% endfor %}

Also key can be specified.

{% for key, user of array %}
  {{ key }}: {{ user.name }}
{% endfor %}

Filters

Any expression support filter statement.

Hello, {{ user.name | upper }}

To define that filter:

monkberry.filters.upper = function (text) {
  return text.toUpperCase();
};

Also Monkberry understand parameters for filters:

monkberry.filters.replace = function (text, from, to) {
  return text.replace(from, to);
};

{{ text | replace(/.../, '$1') }}

And allow to combine filters:

{{ text | lower | replace(/.../, '$1') | upper }}

That expression will be compiled to next JavaScript:

upper(replace(lower(text), /.../, '$1'));

Filters can be used in expressions, if and for statements.

Custom tags

Any template mounted to Monkberry can be called as custom tag.

monkberry.mount(require('./views/block.html'));

Inside another template possible to insert that block templace as custom tag:

<div>
  <block/>
</div>

One file can contains several definitions of custom tags:

<my-tag>
  ...
</my-tag>
<my-second-tag>
  ...
</my-second-tag>

Custom tags may contains variables:

<greet>
  {{ value }}, {{ name }}!
</greet>

To render that custom tag, specify variables as attributes:

<greet value="Hello" name="world">
<greet value="Hello" name="{{ user.name }}">

Prerender

To speedup render Monkberry can prerender DOM nodes to use them in future.

monkberry.prerender('template', 10); // Preprender template 10 times.

Then next render call will use one of these prerendered views:

monkberry.render('template', {...}); // Will use already created DOM nodes.

This is very usefull to do then browser waiting some xhr request.

To get info about prerendered template in runtime, use monkberry.pool.store.

Wrappers

Every template in Monkbeery when rendered can be "wrapped" by function.

For example we have a template logo.html:

<div>
  <i class="svg-icon"></i>
</div>

And we want to insert SVG nodes inside i tag on render. This is can be done via wrappers:

monkberry.wrappers.logo = function (view) {
  view.dom().querySelector('.svg-icon').appendChild(svgIconNodes);
  return view;
};

Wrappers usefull to manipulate view's nodes, adding event listeners and a lot of other staff.

Transforms

Transformers allow to modify AST before compilation of templates. List of AST nodes can be founded here: ast.js Example of transform which trim whitespaces: whitespace.js

Add transforms to Monkbeery before compilation:

import { Compiler } from 'monkberry';
import { myTransform } from './myTransform';

var compiler = new Compiler();
compiler.transforms.custom = myTransform;

Parsers

Now Monkberry support only one type of parser, mustage like (monk named). But it can be extender with custom parsers. Every parser must return valid AST tree.

import { Compiler } from 'monkberry';
import { myParser } from './parser';

var compiler = new Compiler();
compiler.parsers.myParser = myTransform;

compiler.addSource('template', code, 'myParser');
compiler.addSource('another', code, 'monk');

var output = compiler.compile();

Tests

Monkberry uses Jasmine and testem. To run test locally run:

testem ci

Benchmarks

Benchmarks covers a few use cases, and compare Monkberry with React and temple-wat. Also it's contains real site code for soft/hard update tests.

• monkberry.github.io/benchmark
• github.com/monkberry/benchmark