Skip to content
Fetching contributors…
Cannot retrieve contributors at this time
166 lines (97 sloc) 6.07 KB

up, next

GRMustache introduction

Make sure you get familiar with the Mustache syntax and features first:


Core Mustache

  • variables, as {{name}} and {{{name}}} (HTML-escaped or not)
  • sections (boolean, loop, lambda, inverted), as {{#name}}...{{/name}} and {{^name}}...{{/name}}
  • partial templates inclusion, including recursive partials, as {{> partial}}
  • comments, as {{! comment }}
  • "set delimiter" tags, as {{=<% %>=}}

Overlooked Mustache

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

  • key paths, as {{ }}
  • "implicit iterator", as {{.}}, that you may use when rendering each string in an array, for instance.

GRMustache extensions

Genuine Mustache falls short on a few topics. GRMustache implements features that are not yet in the specification:

  • "anchored key paths", as {{ .name }}, which prevents the lookup of the name key in the context stack built by Mustache sections, and guarantees that the name key will be fetched from the very current context.

    If you are not familiar with the "context stack" and the key lookup mechanism, check Guides/runtime/

    This extension is backed on the discussions at mustache/spec#10 and mustache/spec#52.

  • "filters", as {{ uppercase(name) }}.

    This extension is backed on the discussion at mustache/spec#41

GRMustache tools

  • hooks and template debugging: the library helps you observe a template rendering, in order to catch rendering bugs or to extend the raw Mustache features.

Getting started

You'll generally gather a template string and a data object that will fill the "holes" in the template.

The shortest way to render a template is to mix a literal template string and a dictionary:

#import "GRMustache.h"

// Render "Hello Arthur!"

NSDictionary *person = @{ @"name": @"Arthur" };
NSString *templateString = @"Hello {{name}}!";
NSString *rendering = [GRMustacheTemplate renderObject:person fromString:templateString error:NULL];

However, generally speaking, your templates will be stored as resources in your application bundle, and your data will come from your model objects. It turns out the following code should be more common:

#import "GRMustache.h"

// Render a profile document from the `Profile.mustache` resource

Person *person = [Person personWithName:@"Arthur"];
NSString *profile = [GRMustacheTemplate renderObject:person fromResource:@"Profile" bundle:nil error:NULL];

Finally, should you render a single template several times, you will spare CPU cycles by using a single GRMustacheTemplate instance:

#import "GRMustache.h"

// Initialize a template from the `Profile.mustache` resource:
GRMustacheTemplate *profileTemplate = [GRMustacheTemplate templateFromResource:@"Profile" bundle:nil error:NULL];

// Render two profile documents
NSString *arthurProfile = [profileTemplate renderObject:arthur];
NSString *barbieProfile = [profileTemplate renderObject:barbie];

If the library makes it handy to render templates stored as resources, you may have other needs. Check Guides/ for a thorough documentation.

Advanced features

Lambda sections

Lambda sections let your own application code process a portion of a template, and render it in a custom fashion.

A very simple example is a lambda section that wraps its content:


  {{name}} is awesome.


<b>Arthur is awesome.</b>

Lambda sections are fully documented in Guides/ They are the core feature behind the sample code.


Filters allow you to inject your code (again), but this time in order to process values.

There are a few built-in filters as well. For instance:

{{ uppercase(name) }} is awesome.


ARTHUR is awesome.

Filters are fully documented in Guides/ They are demoed in the numbers formatting and array indexes sample codes.

Template delegates

All the nice Objective-C classes you know allow for observation and customization through delegates. GRMustache templates will not let you down.

Check Guides/ for documentation and sample code.

Full documentation map

Mustache syntax


Basic Mustache:

Advanced Mustache:

  • how to process the template canvas before it is rendered with Mustache "lambda sections".
  • how to process data before it is rendered with "filters".
  • how to hook into template rendering.

Sample code:


  • Reference: the GRMustache reference, automatically generated from inline documentation, for fun and profit, by appledoc.


  • the forking guide tells you everything about GRMustache organization.

up, next

Jump to Line
Something went wrong with that request. Please try again.