Mustache Templates for Smalltalk

Mustache is a popular templating engine that is supported in many programming languages. I first encountered them in javascript while researching web toolkits. The syntax is small and covers a wide range of use cases. Maybe I should say that I didn’t find something I can’t do with it so far. Although it was designed to be a templating engine for HTML pages it is useful in different areas.

I have done an implementation for Mustache in smalltalk. It is available at smalltalkhub (update: The source has moved to github: https://github.com/noha/mustache). There is documentation available on how the syntax is to be used. Here are a few examples to show the smalltalk methods you have to call in order to make it work.

How to use?

Disclaimer: I’m talking about an implementation for smalltalk but to be honest I developed and tested it only on pharo smalltalk 2.0. If you need it for another dialect drop me note and we see what we can do.

A simple Mustache template looks like this (taken from the documentation):

    templateString := ‘Hello {{ name }} 
    You have just won ${{value}}! 
    {{#in_ca}} 
    Well, ${{taxed_value}}, after taxes. 
    {{/in_ca}}’.

Given a context object with content

    context := {
       'name' -> 'Chris'.
       'value' -> 10000.
       'taxed_value' -> (10000 - (10000 * 0.4)).
       'in_ca' -> true } asDictionary

we execute the template

    (MustacheTemplate on: templateString) value: context

or

    templateString asMustacheTemplate value: context

we get the following output

    Hello Chris
    You have just won $10000!
    Well, $6000.0, after taxes.

Note: You’ll get a lot more newlines and whitespaces than the string shown here. It is not clear to me what the rules are for condensing whitespace. The will be changed in an upcoming version of mustache As context object we can use Dictionaries and Objects. Dictionaries need to have a key that is used in the template and Objects need a selector with the same name. In this post I use Dictionaries because they are easier to illustrate with.

Working with lists

We can use collections to make loop constructs in templates

    templateString := 'A list of numbers 
    {{# list }} 
    Number: {{ number }} 
    {{/ list }}'.

A context object with content

    {
        'label' -> 'fine'.
        'list' -> {
            { 'number' -> 1 } asDictionary.
            { 'number' -> 2 } asDictionary.
        } 
    } asDictionary

gives us the output

    'A list of numbers
    Number: 1
    Number: 2
    '

And Blocks as well

We can use blocks in context objects. They will be evaluated at the time the template is filled out.

    'The alphabet: {{ alphabet }}' asMustacheTemplate
         value: { 'alphabet' -> [ Character alphabet ] } asDictionary

prints

    The alphabet: abcdefghijklmnopqrstuvwxyz

Partial templates

Mustache templates have a notion of sub templates that are called partials. With partials we can nested templates this way

    templateString := '<h2>Names</h2>
    {{# names }}
        {{> user }}
    {{/ names }}'.
    userTemplateString := '<strong>{{name}}</strong>'.
    templateString asMustacheTemplate
        value: {
           'names' {
               { 'name' -> 'Username' } asDictionary } } asDictionary
        partials: {'user' ->  userTemplateString} asDictionary

prints the output

    <h2>Names</h2>
    <strong>Username</strong>

The dictionary given as partials: argument is supposed to be a dictionary that contains MustacheTemplates itself. A dictionary of strings will do as well because the strings are converted internally.

How about json?

Json is really easy to apply to the templates. If you have a pharo2.0 image just click outside a window. From the upcoming menu select tools and then “Configuration Browser”. Scroll down to NeoJSON and click the install button. After that it is just

    'I can use {{name}} easily with {{format}}' asMustacheTemplate
        value: (NeoJSONReader 
             fromString: '{ "name" : "mustache", "format" : "json" }')

Copy that to pharo workspace and execute to see the result.

Templates made easy

Mustache can make template dependent tasks very easy from a simple token replacement up to nested structures to create HTML pages. I use them e.g. for generating SOAP templates. The purpose of this post is to show the basic usage of it. The strength of Mustache lays in the syntax and the combination of context objects. So, there is more for you to find what can be done with it. If what you find is a bug I like to know. Happy templating !

How to load

    Metacello new
        baseline: 'Mustache';
        repository: 'github://noha/mustache:v1.0/repository';
        load

How to depend on it

    spec 
        baseline: 'Mustache' 
        with: [ spec repository: 'github://noha/mustache:v1.0/repository' ].