@zokugun/template

0.3.0 • Public • Published

@zokugun/template

kaoscript License NPM Version Dependency Status Build Status CircleCI Coverage Status

It is a fast template engine forked from doT with extended and extendable tags.

Getting Started

In Node.js

With node previously installed:

npm install @zokugun/template

Use it with JavaScript:

require('kaoscript/register');

const { Template } = require('@zokugun/template')();

const myTemplate = template.compile(`It's nice to meet you, {{:it}}.`);

console.log(myTemplate('miss White'));

Use it with kaoscript:

import '@zokugun/template'

const myTemplate = template.compile(`It's nice to meet you, {{:it}}.`)

console.log(myTemplate('miss White'))

Differences from doT

doT @zokugun/template Description
{{ }} {{| |}} for evaluation
{{= }} {{: }} for interpolation
{{! }} {{! }} for interpolation with encoding
{{# }} use {{: }} for using partials
{{## #}} {{#name(args)}} {{#}} for defining partials
{{? }} {{? }} for conditionals
{{~ }} {{~ }} for array iteration
{{. }} for object iteration
{{% }} for iterator
{{[ ]}} for range iteration
{{/ }}` `{{\ }} for block
{{` }} for escaping template
{{-- --}} for comments

{{ }} has been changed to {{| |}} to be able to do:

{{|
	function hello(name) {
		if(arguments.length) {
			return 'hello ' + name;
		}
		else {
			return 'hello world!';
		}
	};
|}}
{{:hello('foo')}}

API

import '@zokugun/template'

The variable template is the default template compiler. It contains the tags described above.

The class Template allows to create new templates. It has the following API:

new Template(tags, options)

The default compiler contains the extra method new which allows you to create new template compiler.

The arguments tags and options can be optionals. By default, options will be:

{
	varnames: 'it',
	strip: true,      // remove spaces in javascript code. Be careful of missing ;
	append: true      // use string concatenation or addition assignment operator
}

Example:

const custom = new Template({
	interpolate: {
		regex: /\$\{([\s\S]+?)\}/g
		replace(m, code) => this.cse.start + 'it.' + code + this.cse.end
	}
})

const hello = custom.compile('Hello ${firstname}')

console.log(hello({
	firstname: 'John'
	lastname: 'Doe'
}))

template.addTag(name, regex, replace)

The method addTag allow you to add new tag so he can extends the compiler. The tags are executed in alphabetic order. So its name will determine when the tag will be executed.

The function replace will be called as in str.replace(regex, replace) excepted that the variable this will an object like:

{
	cse: {
		start: string,         // start of the code
		end: string,           // end of the code
		startencode: string,   // start of the code that will be HTML escaped
		endencode: string      // end of the code that will be HTML escaped
	},
	unescape(str),   // unescape the code to pass from the template to the function's code
	sid: integer               // the sid for the variables' names
}

template.clearTags()

The method clearTags removes all the tags defined in the compiler.

template.compile(template, options)

The function compile returns a function based of the string template. The argument options will overwrite the default options of the compiler.

The first line of the template can also contains options for the compiler. It must start with '{{}} ' and the options separated with spaces.

{{}} strip:true
hello {{:it.firstname}}
{{}} strip:false varnames:firstname,lastname
hello {{:firstname}}

template.removeTag(name)

The method clearTags removes the tag named name.

template.run(template, variables, options)

The method run will firstly compiles the template with the options and the variables' names. Then it will execute the resulting function with the variables.

console.log(template.run('It\'s nice to meet you, {{:name}}.', {
	name: 'miss White'
}))

This is the least efficient to use a template. Because the template will be compiled every time.

Tags

Interpolation

Template Data Result
```
It\'s nice to meet you, {{:it.name}}!
Today, you have {{:it.age}}.
```
{
	name: 'Jake',
	age: 32
}
				
```
It\'s nice to meet you, Jake!
Today, you have 31.
```

Interpolation with encoding

Template Data Result
```
{{:it.title}}
```
				
{
	title: 'github',
	url: 'https://github.com'
}
				
```
github
```
				

Evaluation

Template Data Result
```
{{|
	function hello(name) {
		if(arguments.length) {
			return 'hello ' + name;
		}
		else {
			return 'hello world!';
		}
	};
|}}
{{:hello(it.name)}}
```
{
	name: 'Jake'
}
				
```
hello Jake
```

Conditionals

Template Data Result
```
{{?it.morning}}
good morning
{{??it.evening}}
good evening
{{??}}
hello
{{?}}
```
				
```
{
	morning: true
}
```
				
```
good morning
```
				
```
{
	evening: true
}
```
				
```
good evening
```
				
```
{
}
```
				
```
hello
```
				

Array Iteration

Template Data Result
```
{{~it :value}}
{{:value}}
{{~}} ```
```
['banana','apple','orange']
```
				
```
banana
apple
orange
```
```
{{~it :value:index}}
{{:value}}
{{~}} ```
```
banana
apple
orange
```
```
{{~~it :value}}
{{:value}}
{{~}} ```
```
orange
apple
banana
```
```
{{~~it :value:index}}
{{:value}}
{{~}} ```
```
orange
apple
banana
```

Object Iteration

Template Data Result
```
{{.it :value}}
{{:value}}
{{.}} ```
```
{
	firstname: 'John',
	lastname: 'Doe',
	age: 25
}
```
				
```
John
Doe
25
```
```
{{.it :value:key}}
{{:value}}
{{.}} ```
```
John
Doe
25
```

Iterator

Template Data Result
```
{{%iterator.first() :item}}
{{:item.name()}}
{{%iterator.next()}}
```
				

Range Iteration

Template Data Result
```
{{[i 0..3]}}
{{:i}}
{{[]}}
```
				
```
{
}
```
				
```
0
1
2
3
```
				
```
{{[i 3..0]}}
{{:i}}
{{[]}}
```
				
```
3
2
1
0
```
				
```
{{[i 0..3 :2]}}
{{:i}}
{{[]}}
```
				
```
0
1
```
				
```
{{[i 0..it]}}
{{:i}}
{{[]}}
```
				
```
3
```
				
```
0
1
2
3
```
				

Partials

Template Data Result
```
{{#hello}}
	Hello world!
{{#}}
{{:hello()}}
```
				
```
{
}
```
				
```
Hello world!
```
				
```
{{#hello(name)}}
	Hello {{:name}}!
{{#}}
{{:hello(it.name)}}
```
				
```
{
	name: 'Jake'
}
```
				
```
Hello Jake!
```
				

Blocks

Template Data Result
```
{{|var i = 0;|}}
{{/do}}
{{:i}}
{{\while(++i <= 3)}}
```
				
```
{
}
```
				
```
0
1
2
3
```
				
```
{{/for(var i = 0; i <= 3; i++)}}
{{:i}}
{{\}}
```
				
```
{
}
```
				
```
0
1
2
3
```
				

Comments

Template Data Result
```
Hello {{--{{:it.name}}--}}
```
				
```
{
	name: 'Jake'
}
```
				
```
Hello
```
				

Escape

Template Data Result
```
Hello {{`it.name}}
```
				
```
{
	name: 'Jake'
}
```
				
```
Hello {{it.name}}
```
				

Forked from

License

MIT © Baptiste Augrain

Package Sidebar

Install

npm i @zokugun/template

Weekly Downloads

1

Version

0.3.0

License

none

Unpacked Size

27 kB

Total Files

4

Last publish

Collaborators

  • daiyam