Skip to content

Latest commit

 

History

History
155 lines (100 loc) · 6.01 KB

configuration.md

File metadata and controls

155 lines (100 loc) · 6.01 KB
Raw

up, next

Configuration

GRMustache has options: they are properties of a GRMustacheConfiguration instance. You basically have three levels of tuning:

  • global configuration for all templates,
  • configuration for all templates of a template repository,
  • configuration for a single template.

The global default configuration is [GRMustacheConfiguration defaultConfiguration]:

// Have GRMustache templates render text by default,
// and do not HTML-escape their input.
[GRMustacheConfiguration defaultConfiguration].contentType = GRMustacheContentTypeText;

// Load the text template `profile.mustache` from the main bundle:
GRMustacheTemplate *template = [GRMustacheTemplate templateFromResource:@"profile" bundle:nil error:NULL];

Each template repository has its custom configuration, initialized with the default one:

GRMustacheTemplateRepository *repo = [GRMustacheTemplateRepository templateRepositoryWithDirectory:@"/path/to/templates"];

// Have all templates in /path/to/templates render HTML
repo.configuration.contentType = GRMustacheContentTypeHTML;

// Load the HTML template `profile.mustache`:
GRMustacheTemplate *template = [repo templateNamed:@"profile" error:NULL];

Options can be configured at the template level also: this is described below.

Factory configuration

The global default configuration is there to suit your needs: tweak it.

Whenever you need a raw pristine configuration, use the [GRMustacheConfiguration configuration] class method. It returns a configuration initialized with factory defaults.

GRMustacheTemplateRepository *repo = [GRMustacheTemplateRepository templateRepositoryWithDirectory:@"/path/to/templates"];

// Have all templates in /path/to/templates render with factory configuration:
repo.configuration = [GRMustacheConfiguration configuration];

GRMustacheConfiguration properties

baseContext

Mustache rendering is all about looking for values in a context stack. That context stack is initialized with the base context, gets extended with the objects you provide to templates, and grows as Mustache sections get rendered each on its turn. See the Runtime Guide for more information.

The default configuration contains the default base context, pre-filled with the GRMustache standard library.

The standard library pre-defines a few keys, such as localize and uppercase. For instance, the following template:

{{# localize }}Hello {{ uppercase(name) }}!{{/ localize }}

Would render:

Bonjour ARTHUR !

Provided with a name and a localization for "Hello %@!" string in the Localizable.strings file of the main bundle.

You can extend the base context:

// Globally for all templates:
GRMustacheContext *baseContext = [GRMustache defaultConfiguration].baseContext;
GRMustacheContext *extendedContext = [baseContext contextByAddingObject:myCustomLibrary];
[GRMustache defaultConfiguration].baseContext = extendedContext;

// For templates of a template repository:
GRMustacheTemplateRepository *repo = [GRMustacheTemplateRepository templateRepositoryWith...];
repo.configuration.baseContext = [repo.configuration.baseContext contextByAddingObject:myCustomLibrary];

You can also reset it to a blank slate, getting rid of the whole standard library:

[GRMustache defaultConfiguration].baseContext = [GRMustacheContext context];
repo.configuration.baseContext = [GRMustacheContext context];

You may also be interested in protected contexts. They guarantee that a particular identifier will always evaluate to the same value.

// Guarantee that {{my_important_value}} will always render the same and cannot
// be overriden by custom data:
id library = @{ @"my_important_value": ... };
repo.configuration.baseContext = [GRMustacheContext contextWithProtectedObject:library];

At the template level

The base context can also be defined right at the template level:

// This template has its own base context that overrides the default
// configuration and its template repository:
GRMustacheTemplate *template = ...;
template.baseContext = ...;

contentType

The default configuration has the GRMustacheContentTypeHTML contentType, meaning that all templates render HTML by default, and escape their input.

GRMustache also supports text templates, that render text and do not escape anything.

This subject is fully covered in the HTML vs. Text Templates Guide.

tagStartDelimiter and tagEndDelimiter

Mustache takes its name from its tag delimiters: {{ and }}.

You can configure them through GRMustacheConfiguration:

// Have all templates use <% and %> as tag delimiters:
[GRMustacheConfiguration defaultConfiguration].tagStartDelimiter = @"<%";
[GRMustacheConfiguration defaultConfiguration].tagEndDelimiter = @"%>";

// Only for templates of a template repository:
GRMustacheTemplateRepository *repo = [GRMustacheTemplateRepository templateRepositoryWith...];
repo.configuration.tagStartDelimiter = @"[[";
repo.configuration.tagEndDelimiter = @"]]";

At the template level

The tag delimiters can be overriden at the template level using a "Set Delimiters Tag" such as {{=<% %>=}}: now tag would look like <% name %>.

Compatibility with other Mustache implementations

The Mustache specification does not talk about any of the options above.

If your goal is to design templates that remain compatible with other Mustache implementations, check their documentation.

up, next