17c98a0 Mar 16, 2014
113 lines (59 sloc) 4.47 KB

up, next

GRMustache introduction

The Mustache language

Make sure you get familiar with the Mustache syntax and features first: http://mustache.github.io/mustache.5.html.

  • Variable tags, as {{name}}, {{{name}}} and {{&name}} (HTML-escaped or not)
  • Section tags (boolean, loop, lambda, inverted), as {{#name}}...{{/name}} and {{^name}}...{{/name}}
  • Partial tags, as {{> partial}}
  • Comment tag, as {{! comment }}
  • "Set delimiter tags", as {{=<% %>=}}

Features below are not documented in mustache.5.html, despite their inclusion in the Mustache specification:

  • Key paths, as {{ person.name }}, for direct access to an object's property.
  • "Implicit iterator", aka {{.}}, directly renders the current object (useful when looping over strings, for instance).
  • "Mustache lambdas", allow both {{name}} and {{#name}}...{{/name}} tags to perform custom rendering.

Beyond Mustache

GRMustache adds many services on top of the minimalistic template engine.

Check the Compatibility Guide whenever you want to keep your templates compatible with other Mustache implementations.

Syntax extensions

  • Empty closing tags, as in {{#name}}...{{/}}

    You don't have to repeat the opening expression in the closing tag.

  • "Else", as in {{#name}}...{{^name}}...{{/name}}

    You don't have to close a regular section if it is immediately followed by its inverted form.

    The short form {{#name}}...{{^}}...{{/}} is accepted, as well as the "unless" form {{^name}}...{{#}}...{{/}}.

  • "Anchored key paths", as {{ .name }} which enforces lookup of the name key in the immediate context instead of going through the context stack built by Mustache sections.

    If you are not familiar with the "context stack" and the Mustache key lookup mechanism, check the Runtime Guide.

  • Loops in variable tags: a simple variable tag {{items}} renders a concatenation of the rendering of each individual item. You may think of Ruby on Rails' <%= render @items %>: check the Rendering Objects Guide.

More partials

  • Support for the file system hierarchy.

    Use relative {{> header }} or absolute paths {{> /shared/header }} to your partial templates: see the Partials Guide.

  • Template inheritance, inspired by hogan.js and spullara/mustache.java, allow you to define reusable template layouts:

    {{< page }}      {{! page.mustache defines the layout.  }}
      {{$ content }} {{! this template defines the content. }}
      {{/ content }}
    {{/ page }}

    Template inheritance is documented in the Template Inheritance Guide.

Text templates

Mustache focuses on rendering HTML, and safely HTML-escape your data.

GRMustache also supports text templates, that do not escape anything. Check the HTML vs. Text Templates Guide.


Filters, as {{ uppercase(name) }}, are documented in the Filters Guide.

Powerful Lambdas

Forget everything you know about the stifled genuine Mustache lambdas, and give GRMustache rendering objects a try.


The library ships with a standard library of various filters and tools for rendering your data.

Our old friend NSFormatter is also welcome to the party.


GRMustache's core engine is extensible. Feel free to hook in:

Those three hooks are lego bricks: from them you can build more complex tools, such as NSFormatter and the localize helper.


GRMustache has built-in features that prevents it from threatening your application whenever you render untrusted templates or data. See the Security Guide for more information.

up, next