object-template

Bidirectional JSON-based templating engine

Installation

Install object-template by running:

npm install --save object-template

Documentation

object-template is a templating engine that operates on JSON objects, providing the unique benefit of allowing bidirectional transformations, that is, from template and data to a result, and from a template and result to the original data.

For example, consider the following template:

{
  "foo": "My name is {{name}}"
}

Notice the use of double curly braces to denote string interpolation.

In order to compile this template, we need a name value. This is an example data object that can be used to compile the above template:

{
  "name": "John Doe"
}

The compilation result looks like this:

{
  "foo": "My name is John Doe"
}

Now consider that we have the compilation result and the template, and we want to be able to determine what was the original data used to compile it.

object-template will realise "My name is John Doe" was compiled from "My name is {{name}}", and therefore that name equals John Doe. Using this information, object-template will "decompile" the template and return back the following object to the user, which unsurprisingly equals the "data" object:

{
  "name": "John Doe"
}

The example objects contain one key and a single interpolation, but on real templates, there can be complex nesting levels and multiple interpolations (even many per property).

Default values

Default values can be provided using the || operator. The default value should be JSON encoded. In the example below, if the name value is not provided, the default value John Doe will be used instead.

{
  "foo": "My name is {{name || \"John Doe\"}}"
}

When decompiling a result that used a default value, the default value will be returned.

API

• object-template
  • .compile(template, data, [options]) ⇒ Object
  • .decompile(template, result, [options]) ⇒ Object
  • .matches(template, object, [options]) ⇒ Boolean

object-template.compile(template, data, [options]) ⇒ Object

Kind: static method of object-template
Summary: Compile a JSON template
Returns: Object - compilation result
Access: public

| Param | Type | Description | | --- | --- | --- | | template | Object | json template | | data | Object | template data | | [options] | Object | options | | [options.delimiters] | Array.<String> | delimiters | | [options.allowMissing] | Boolean | allow missing variables |

Example

const result = objectTemplate.compile({
  greeting: 'Hello, {{name}}!'
}, {
  name: 'John Doe'
})

console.log(result)
> {
>   greeting: 'Hello, John Doe!'
> }

object-template.decompile(template, result, [options]) ⇒ Object

Kind: static method of object-template
Summary: Decompile a JSON template
Returns: Object - template data
Access: public

| Param | Type | Description | | --- | --- | --- | | template | Object | json template | | result | Object | compilation result | | [options] | Object | options | | [options.delimiters] | Array.<String> | delimiters |

Example

const data = objectTemplate.decompile({
  greeting: 'Hello, {{name}}!'
}, {
  greeting: 'Hello, John Doe!'
})

console.log(data)
> {
>   name: 'John Doe'
> }

object-template.matches(template, object, [options]) ⇒ Boolean

Kind: static method of object-template
Summary: Check if a compiled object matches a template
Returns: Boolean - whether object matches template
Access: public

| Param | Type | Description | | --- | --- | --- | | template | Object | template object | | object | Object | compiled object | | [options] | Object | options | | [options.delimiters] | Array.<String> | delimiters |

Example

if (objectTemplate.matches({
  foo: '{{bar}}'
}, }
  foo: 'bar'
)) {
  console.log('This is a match!')
}

Tests

Run the test npm script:

npm test

Contribute

• Issue Tracker: github.com/resin-io-modules/object-template/issues
• Source Code: github.com/resin-io-modules/object-template

Before submitting a PR, please make sure that you include tests, and that the linter runs without any warning:

npm run lint

Support

If you're having any problem, please raise an issue on GitHub.

License

This project is free software, and may be redistributed under the terms specified in the license.