Inherits from NSObject
Conforms to NSCopying
Declared in GRMustacheConfiguration.h

Overview

A GRMustacheConfiguration instance configures GRMustache rendering.

Companion guide: https://github.com/groue/GRMustache/blob/master/Guides/configuration.md

The default configuration [GRMustacheConfiguration defaultConfiguration] applies to all GRMustache rendering by default:

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

You can also alter the configuration of a specific template repository: its configuration only applies to the templates built by this very template repository:

// All templates loaded from _repo_ will use [[ and ]] as tag delimiters.
GRMustacheTemplateRepository *repo = [GRMustacheTemplateRepository templateRepositoryWithBundle:nil];
repo.configuration.tagStartDelimiter = @"[[";
repo.configuration.tagEndDelimiter = @"]]";

A third option is to create a new configuration, and assign it to the template:

// Create a configuration
GRMustacheConfiguration *configuration = [GRMustacheConfiguration configuration];
configuration.... // setup

GRMustacheTemplateRepository *repo = [GRMustacheTemplateRepository templateRepositoryWithBundle:nil];
repo.configuration = configuration;

The contentType option can be specified at the template level, so that your repositories can mix HTML and text templates: see the documentation of this property.

The tagStartDelimiter and tagEndDelimiter options can also be specified at the template level, using a “Set Delimiters tag”: see the documentation of these properties.

Tasks

Default Configuration

Creating Configuration

Set Up Configuration

Properties

baseContext

The base context for templates rendering. The default base context contains the GRMustache standard Library.

@property (nonatomic, retain) GRMustacheContext *baseContext

Availability

v6.4

See Also

Declared In

GRMustacheConfiguration.h

contentType

The content type of strings rendered by templates.

@property (nonatomic) GRMustacheContentType contentType

Availability

v6.2

Discussion

This property affects the HTML-escaping of your data, and the inclusion of templates in other templates.

The GRMustacheContentTypeHTML content type has templates render HTML. This is the default behavior. HTML template escape the input of variable tags such as {{name}}. Use triple mustache tags {{{content}}} in order to avoid the HTML-escaping.

The GRMustacheContentTypeText content type has templates render text. They do not HTML-escape their input: {{name}} and {{{name}}} have identical renderings.

GRMustache safely keeps track of the content type of templates: should a HTML template embed a text template, the content of the text template would be HTML-escaped.

There is no API to specify the content type of individual templates. However, you can use pragma tags right in the content of your templates:

  • {{% CONTENT_TYPE:TEXT }} turns a template into a text template.
  • {{% CONTENT_TYPE:HTML }} turns a template into a HTML template.

Insert those pragma tags early in your templates. For example:

{{! This template renders a bash script. }}
{{% CONTENT_TYPE:TEXT }}
export LANG={{ENV.LANG}}
...

Should two such pragmas be found in a template content, the last one wins.

Declared In

GRMustacheConfiguration.h

tagEndDelimiter

The closing delimiter for Mustache tags. Its default value is }}.

@property (nonatomic, copy) NSString *tagEndDelimiter

Availability

v6.4

Discussion

You can also change the delimiters right in your templates using a “Set Delimiter tag”: {{=[[ ]]=}} changes start and end delimiters to [[ and ]].

Declared In

GRMustacheConfiguration.h

tagStartDelimiter

The opening delimiter for Mustache tags. Its default value is {{.

@property (nonatomic, copy) NSString *tagStartDelimiter

Availability

v6.4

Discussion

You can also change the delimiters right in your templates using a “Set Delimiter tag”: {{=[[ ]]=}} changes start and end delimiters to [[ and ]].

Declared In

GRMustacheConfiguration.h

Class Methods

configuration

A new factory configuration.

+ (GRMustacheConfiguration *)configuration

Return Value

A new factory configuration.

Its contentType is GRMustacheContentTypeHTML. Its tag delimiters are {{ and }}.

Availability

v6.2

Declared In

GRMustacheConfiguration.h

defaultConfiguration

The default configuration.

+ (GRMustacheConfiguration *)defaultConfiguration

Return Value

The default configuration.

Availability

v6.2

Discussion

All templates and template repositories use the default configuration unless you specify otherwise by setting the configuration of a template repository.

The “default” defaultConfiguration has GRMustacheContentTypeHTML contentType, and {{ and }} as tag delimiters.

Declared In

GRMustacheConfiguration.h

Instance Methods

extendBaseContextWithObject:

Extends the base context of the receiver with the provided object, making its keys available for all renderings.

- (void)extendBaseContextWithObject:(id)object

Parameters

object

An object

Availability

v6.8

Discussion

For example:

GRMustacheConfiguration *configuration = [GRMustacheConfiguration defaultConfiguration];

// Have the `name` key defined for all template renderings:
id object = @{ @"name": @"Arthur" };
[configuration extendBaseContextWithObject:object];

// Renders "Arthur"
[GRMustacheTemplate renderObject:nil fromString:@"{{name}}" error:NULL];

Keys defined by object can be overriden by other objects that will eventually enter the context stack:

// Renders "Billy", not "Arthur"
[GRMustacheTemplate renderObject:nil:@{ @"name": @"Billy" } fromString:@"{{name}}" error:NULL];

This method is a shortcut. It is equivalent to the following line of code:

configuration.baseContext = [configuration.baseContext contextByAddingObject:object];

See Also

Declared In

GRMustacheConfiguration.h

extendBaseContextWithProtectedObject:

Extends the base context of the receiver with the provided object, making its keys available for all renderings.

- (void)extendBaseContextWithProtectedObject:(id)object

Parameters

object

An object

Availability

v6.8

Discussion

Keys defined by object are given priority, which means that they can not be overriden by other objects that will eventually enter the context stack.

For example:

GRMustacheConfiguration *configuration = [GRMustacheConfiguration defaultConfiguration];

// The `precious` key is given priority:
[configuration extendBaseContextWithProtectedObject:@{ @"precious": @"gold" }];

// Renders "gold", not "lead".
[GRMustacheTemplate renderObject:nil:@{ @"precious": @"lead" } fromString:@"{{precious}}" error:NULL];

This method is a shortcut. It is equivalent to the following line of code:

configuration.baseContext = [configuration.baseContext contextByAddingProtectedObject:object];

See Also

Declared In

GRMustacheConfiguration.h

extendBaseContextWithTagDelegate:

Extends the base context of the receiver with a tag delegate, making it aware of the rendering of all template tags.

- (void)extendBaseContextWithTagDelegate:(id<GRMustacheTagDelegate>)tagDelegate

Parameters

tagDelegate

A tag delegate

Availability

v6.8

Discussion

This method is a shortcut. It is equivalent to the following line of code:

configuration.baseContext = [configuration.baseContext contextByAddingTagDelegate:tagDelegate];

See Also

Declared In

GRMustacheConfiguration.h