@cvpcasada/micromustache
v5.2.1
Published
A faster and smaller subimplementation of the {{mustache}} template engine for JavaScript
Downloads
22
Maintainers
Readme
This is a fork of micromustach by userpixel the difference is only the way it is bundled (uses rollup) to allow drop-in imports to environments like create-react-app and Next.js
micromustache
This small library covers the most important use case for Mustache templates:
interpolation: replacing variable names with their values from an object.
Think of it as a sweet spot between plain text replacement and mustache (certainly not as logicful as Handlebars).
If that's all you need, micromustache is a drop-in replacement for MustacheJS.
- No dependencies
- Fully compatible with MustacheJS for interpolation
- Works in node (CommonJS) and Browser (using CommonJS build tools like Browserify/WebPack)
- Well tested (full test coverage over 80+ tests)
- Dead simple to learn yet a pleasure to use
- The code is small and easy to read and has full JSDoc documentation
Tradeoffs
Micromustache achieves faster speed and smaller size by dropping the following features from MustacheJS:
- Array iterations: {{# ...}}
- Partials: {{> ...}}
- Arrays as values: {{ arrName[1] }} (you can access arrays like
arrName.1
though) - Inverted selection: {{^ ...}}
- Comments: {{! ...}}
- HTML sanitization: {{{ propertyName }}}
- Custom delimiters: No support for <% ... %>. We just have {{ ... }}
- It does not support IE 6-8
If you can live with this, read on...
API
render(template, view = {}, customResolver)
Parameters
template: string
: The template containing one or more{{variableNames}}
.view: Object
: An optional object containing values for every variable names that is used in the template. If it's omitted, it'll be assumed an empty object.customResolver: function (varName, view)
An optional function that will be called for every{{varName}}
to generate a value. If the resolver throws we'll proceed with the default value resolution algorithm (find the value from the view object).
Return
The return is always the same type as the template itself (if template is not a string, it'll be
returned untouched and no processing is done). All {{varName}}
strings inside the template will
be resolved with their corresponding value from the view
object.
If a particular path doesn't exist in the view
object, it'll be replaced with empty string (''
).
Objects will be JSON.stringified()
but if there was an error doing so (for example when there's
a loop in the object, they'll be simply replaced with {...}
.
Example:
var person = {
first: 'Michael',
last: 'Jackson'
};
micromustache.render('Search for {{first}} {{ last }} songs!', person);
// output = "Search for Michael Jackson songs!"
// If a custom resolver was provided it would be called two times with these params:
// ('first', person)
// ('last', person) <-- notice the varName is trimmed
You can even access array elements and length
because they are all valid keys in the array object
in javascript:
var fruits = [ 'orange', 'apple', 'lemon' ];
micromustache.render('I like {{length}} fruits: {{0}}, {{1}} and {{2}}.', fruits);
// output = "I like 3 fruits: orange, apple and lemon."
// If a custom resolver was provided it would be called three times with these params:
// ('0', person) <-- notice that the array indices are sent as strings.
// ('1', person)
// ('2', person)
Note: if a key is missing or null
, it'll be treated as if it contained a value
of empty string (i.e. the {{variableName}} will be removed from the template).
var person = {
first: 'Michael',
last: 'Jackson'
};
micromustache.render('He was {{age}} years old!', person);
// output = "He was years old!"
You can easily reference deep object hierarchies:
var singer = {
first: 'Michael',
last: 'Jackson',
children: [
{
first: 'Paris-Michael',
middle: 'Katherine',
},
{
first: 'Prince',
middle: 'Michael',
prefix: 'II'
},
{
first: 'Michael',
middle: 'Joseph',
prefix: 'Jr.'
}
]
}
micromustache.render("{{first}} {{last}} had {{children.length}} children: {{children.0.first}}, {{children.1.first}} and {{children.2.first}}", singer);
//output = "Michael Jackson had 3 children: Paris-Michael, Prince and Michael"
As you can see unlike MustacheJS, micromustache doesn't have loops.
Differences with MustacheJS render() method
- micromustache is a bit more forgiving than MustacheJS. For example, if the
view
isnull
orundefined
, MustacheJS throws an exception but micromustache doesn't. It just assumes an empty object for the view. - also the
customResolver
doesn't exist in MustacheJS but is a powerful little utility that halps some use cases.
compile(template, customResolver)
This is a utility function that accepts a template
and customResolver
and returns a renderer
function that only accepts view and spits out filled template. This is useful when you find yourself
using the render function over and over again with the same template. Under the hood it's just a thin
layer on top of render
so it uses the same parameters 👆.
Return
A function that accepts a view
object and returns a rendered template string.
Example
const templateEngine = micromustache.compile('Search {{first}} {{ last }} popcorn!');
var output = templateEngine(person);
// output = "Search Michael Jackson popcorn!"
output = templateEngine({first:'Albert',last:'Einstein'});
// output = "Search Albert Einstein popcorn!"
compile()
doesn't do any memoization so it doesn't introduce any performance improvmenet to your
code.
Command Line Interface
Micromustache comes with a simple CLI that brings the render()
functionality to shell programming.
npm i -g micromustache
This will make the micromustache
command available on your shell.
It works like this:
micromustache templatePath viewPath
Both parameters are required.
templatePath
: path to a template text file that contains {{varName}} in itviewPath
: path to a valid json file
Files are read/write with utf8 encoding.
By default CLI prints the output to console (and erros to stderr).
You can redirect it to output file using > outputPath
.
Example:
micromustache template.txt view.json > output.txt
This command reads the contents of template.txt
and render()
it using data from view.json
and puts the result text in output.txt
.
Tests
We use Mocha/Chai for tests. If you want to run the tests, install dependencies and run them using npm:
npm it
FAQ
Q. What about ES6 template literals (AKA "template strings")? Aren't they gonna deprecate this library?
A. The expressions in a string literal can't reference values from outside its scope. Therefore it is not possible to simply pass an object and resolve variables from its keys. The tagged template literals cover part of the functionality but they:
- are not Mustache-compatible
- require compilation for Android and IE
- need the variables to be accessible in the scope of the template literal
However, since when they are natively supported by the runtime, they have a great performance and if you learn to use the native way of doing things, you don't have to learn yet another library, though their functionality is more limited than MustacheJS.
Q. I want "INSERT SOME MUSTACHE FEATUE HERE" but it's not available in MicroMustache. Can I add it?
A. Make an issue first. The goal of MicroMustache is to be super tiny and while adressing the most important use-case of Mustache. If there's something that is terribly missing, we may add it, otherwise, you may fork it and call it something else OR use MustacheJS.