Inherits from NSObject
Declared in GRMustacheTemplateRepository.h

Overview

Given a data source that provides Mustache template strings, a GRMustacheTemplateRepository’s responsability is to provide GRMustacheTemplate instances.

You may provide your own template string data source. However common cases such as loading templates from URLs, files, bundle resources, and dictionaries, are already implemented.

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

Tasks

Creating Template Repositories

Configuring Template Repositories

  •   dataSource

    The repository’s data source.

    property
  •   configuration

    The configuration for all templates and partials built by the repository.

    property

Getting Templates out of a Repository

Properties

configuration

The configuration for all templates and partials built by the repository.

@property (nonatomic, copy) GRMustacheConfiguration *configuration

Availability

Discussion

It is initialized to a copy of [GRMustacheConfiguration defaultConfiguration].

You can alter the repository’s configuration:

// All templates loaded from _repo_ will render text,
// and will not HTML-escape their input.
GRMustacheTemplateRepository *repo = [GRMustacheTemplateRepository templateRepositoryWithBundle:nil];
repo.configuration.contentType = GRMustacheContentTypeText;

You can also create a new configuration, and assign it to the repository:

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

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

Declared In

GRMustacheTemplateRepository.h

dataSource

The repository’s data source.

@property (nonatomic, assign) id<GRMustacheTemplateRepositoryDataSource> dataSource

Availability

Declared In

GRMustacheTemplateRepository.h

Class Methods

templateRepository

Returns a GRMustacheTemplateRepository.

+ (instancetype)templateRepository

Return Value

a GRMustacheTemplateRepository

Availability

Discussion

Until it is provided with a data source, it is unable to load template by names, and unable to process partial tags such as {{>partial}}:

GRMustacheTemplateRepository *repository = [GRMustacheTemplateRepository templateRepository];
NSError *error;

// Returns nil, and sets error to an NSError of domain
// GRMustacheErrorDomain, code GRMustacheErrorCodeTemplateNotFound.
[repository templateNamed:@"foo" error:&error];

// Returns nil, and sets error to an NSError of domain GRMustacheErrorDomain,
// code GRMustacheErrorCodeTemplateNotFound.
[repository templateFromString:@"{{>partial}}" error:&error];

It is, however, able to process Mustache template strings without any partial:

GRMustacheTemplate *template = [repository templateFromString:@"Hello {{name}}!" error:NULL];

You will give it a data source conforming to the GRMustacheTemplateRepositoryDataSource protocol in order to load template and partials by name:

repository.dataSource = ...;

// Returns a template built from the string provided by the dataSource.
[repository templateNamed:@"foo" error:NULL];

Declared In

GRMustacheTemplateRepository.h

templateRepositoryWithBaseURL:

Returns a GRMustacheTemplateRepository that loads Mustache template strings from files of extension .mustache, encoded in UTF8, stored in the provided base URL.

+ (instancetype)templateRepositoryWithBaseURL:(NSURL *)URL

Parameters

URL

the base URL where to look templates from.

Return Value

a GRMustacheTemplateRepository

Availability

Discussion

For example:

// Creates a repository for templates stored in /path/to/templates
NSURL *baseURL = [NSURL fileURLWithPath:@"/path/to/templates"];
GRMustacheTemplateRepository *repository = [GRMustacheTemplateRepository templateRepositoryWithBaseURL:baseURL];

// Returns a template for the file stored in
// /path/to/templates/profile.mustache
GRMustacheTemplate *template = [repository templateNamed:@"profile" error:NULL];

A partial tag {{>partial}} loads a partial template stored in a file named partial.mustache, located in the enclosing template’s directory.

You may use the slash /, and .., in order to navigate the URL hierarchical system: {{>partials/achievements}} would load /path/to/templates/partials/achievements.mustache, if invoked from /path/to/templates/profile.mustache.

When you ask the repository to parse a raw template string, partials are loaded from the base URL:

// The partial would be loaded from
// /path/to/templates/partials/achievements.mustache
GRMustacheTemplate *template = [repository templateFromString:@"{{>partials/achievements}}" error:NULL];

Declared In

GRMustacheTemplateRepository.h

templateRepositoryWithBaseURL:templateExtension:encoding:

Returns a GRMustacheTemplateRepository that loads Mustache template strings from files of provided extension, encoded in the provided encoding, stored in the provided base URL.

+ (instancetype)templateRepositoryWithBaseURL:(NSURL *)URL templateExtension:(NSString *)ext encoding:(NSStringEncoding)encoding

Parameters

URL

The base URL where to look templates from.

ext

The extension of template files.

encoding

The encoding of template files.

Return Value

a GRMustacheTemplateRepository

Availability

Discussion

For example:

// Creates a repository for templates of extension `.txt` stored in
// /path/to/templates, encoded with NSMacOSRomanStringEncoding:
NSURL *baseURL = [NSURL fileURLWithPath:@"/path/to/templates"];
GRMustacheTemplateRepository *repository = [GRMustacheTemplateRepository templateRepositoryWithBaseURL:baseURL
                                                                                     templateExtension:@"txt"
                                                                                              encoding:NSMacOSRomanStringEncoding];

// Returns a template for the file stored in
// /path/to/templates/profile.txt
GRMustacheTemplate *template = [repository templateNamed:@"profile" error:NULL];

A partial tag {{>partial}} loads a partial template stored in a file named partial.txt, located in the enclosing template’s directory.

You may use the slash /, and .., in order to navigate the URL hierarchical system: {{>partials/achievements}} would load /path/to/templates/partials/achievements.txt, if invoked from /path/to/templates/profile.txt.

When you ask the repository to parse a raw template string, partials are loaded from the base URL:

// The partial would be loaded from
// /path/to/templates/partials/achievements.txt
GRMustacheTemplate *template = [repository templateFromString:@"{{>partials/achievements}}" error:NULL];

Declared In

GRMustacheTemplateRepository.h

templateRepositoryWithBundle:

Returns a GRMustacheTemplateRepository that loads Mustache template strings from resources of extension .mustache, encoded in UTF8, stored in the provided bundle.

+ (instancetype)templateRepositoryWithBundle:(NSBundle *)bundle

Parameters

bundle

The bundle that stores templates as resources. If nil, the

           main bundle is used.

Return Value

a GRMustacheTemplateRepository

Availability

Discussion

For example:

// Creates a repository for templates stored in the main bundle:
GRMustacheTemplateRepository *repository = [GRMustacheTemplateRepository templateRepositoryWithBundle:[NSBundle mainBundle]];

// Returns a template for the resource profile.mustache
GRMustacheTemplate *template = [repository templateNamed:@"profile" error:NULL];

You may provide nil for the bundle parameter: the repository will use the main bundle.

A partial tag {{>partial}} loads a partial template from the partial.mustache resource in the bundle.

Declared In

GRMustacheTemplateRepository.h

templateRepositoryWithBundle:templateExtension:encoding:

Returns a GRMustacheTemplateRepository that loads Mustache template strings from resources of provided extension, encoded in the provided encoding, stored in the provided bundle.

+ (instancetype)templateRepositoryWithBundle:(NSBundle *)bundle templateExtension:(NSString *)ext encoding:(NSStringEncoding)encoding

Parameters

bundle

The bundle that stores templates as resources.

ext

The extension of template files.

encoding

The encoding of template files.

Return Value

a GRMustacheTemplateRepository

Availability

Discussion

For example:

// Creates a repository for templates of extension `.txt` stored in the
// main bundle, encoded with NSMacOSRomanStringEncoding:
GRMustacheTemplateRepository *repository = [GRMustacheTemplateRepository templateRepositoryWithBundle:[NSBundle mainBundle]
                                                                                    templateExtension:@"txt"
                                                                                             encoding:NSMacOSRomanStringEncoding];

// Returns a template for the resource profile.txt
GRMustacheTemplate *template = [repository templateNamed:@"profile" error:NULL];

You may provide nil for the bundle parameter: the repository will use the main bundle.

A partial tag {{>partial}} loads a partial template from the partial.txt resource in the bundle.

Declared In

GRMustacheTemplateRepository.h

templateRepositoryWithDictionary:

Returns a GRMustacheTemplateRepository that loads Mustache template strings from a dictionary whose keys are template names, and values template strings.

+ (instancetype)templateRepositoryWithDictionary:(NSDictionary *)templates

Parameters

templates

A dictionary whose keys are template names, and values

              Mustache template strings.

Return Value

a GRMustacheTemplateRepository

Availability

Discussion

For example:

NSDictionary *templates = [NSDictionary dictionaryWithObject:@"It works." forKey:@"partial"];
GRMustacheTemplateRepository *repository = [GRMustacheTemplateRepository templateRepositoryWithDictionary:templates];

// Two templates that would render "It works."
GRMustacheTemplate *template1 = [repository templateNamed:@"partial" error:NULL];
GRMustacheTemplate *template2 = [repository templateFromString:@"{{>partial}}" error:NULL];

Declared In

GRMustacheTemplateRepository.h

templateRepositoryWithDirectory:

Returns a GRMustacheTemplateRepository that loads Mustache template strings from files of extension .mustache, encoded in UTF8, stored in the provided directory.

+ (instancetype)templateRepositoryWithDirectory:(NSString *)path

Parameters

path

The path of the directory that stores templates.

Return Value

a GRMustacheTemplateRepository

Availability

Discussion

For example:

// Creates a repository for templates stored in /path/to/templates
GRMustacheTemplateRepository *repository = [GRMustacheTemplateRepository templateRepositoryWithDirectory:@"/path/to/templates"];

// Returns a template for the file stored in
// /path/to/templates/profile.mustache
GRMustacheTemplate *template = [repository templateNamed:@"profile" error:NULL];

A partial tag {{>partial}} loads a partial template stored in a file named partial.mustache, located in the enclosing template’s directory.

You may use the slash /, and .., in order to navigate the hierarchical file system: {{>partials/achievements}} would load /path/to/templates/partials/achievements.mustache, if invoked from /path/to/templates/profile.mustache.

When you ask the repository to parse a raw template string, partials are loaded from the base directory:

// The partial would be loaded from
// /path/to/templates/partials/achievements.mustache
GRMustacheTemplate *template = [repository templateFromString:@"{{>partials/achievements}}" error:NULL];

Declared In

GRMustacheTemplateRepository.h

templateRepositoryWithDirectory:templateExtension:encoding:

Returns a GRMustacheTemplateRepository that loads Mustache template strings from files of provided extension, encoded in the provided encoding, stored in the provided directory.

+ (instancetype)templateRepositoryWithDirectory:(NSString *)path templateExtension:(NSString *)ext encoding:(NSStringEncoding)encoding

Parameters

path

The path of the directory that stores templates.

ext

The extension of template files.

encoding

The encoding of template files.

Return Value

a GRMustacheTemplateRepository

Availability

Discussion

For example:

// Creates a repository for templates of extension `.txt` stored in
// /path/to/templates, encoded with NSMacOSRomanStringEncoding:
GRMustacheTemplateRepository *repository = [GRMustacheTemplateRepository templateRepositoryWithDirectory:@"/path/to/templates"
                                                                                       templateExtension:@"txt"
                                                                                                encoding:NSMacOSRomanStringEncoding];

// Returns a template for the file stored in
// /path/to/templates/profile.txt
GRMustacheTemplate *template = [repository templateNamed:@"profile" error:NULL];

A partial tag {{>partial}} loads a partial template stored in a file named partial.txt, located in the enclosing template’s directory.

You may use the slash /, and .., in order to navigate the hierarchical file system: {{>partials/achievements}} would load /path/to/templates/partials/achievements.txt, if invoked from /path/to/templates/profile.txt.

When you ask the repository to parse a raw template string, partials are loaded from the base directory:

// The partial would be loaded from
// /path/to/templates/partials/achievements.txt
GRMustacheTemplate *template = [repository templateFromString:@"{{>partials/achievements}}" error:NULL];

Declared In

GRMustacheTemplateRepository.h

Instance Methods

templateFromString:error:

Returns a template built from the provided Mustache template string.

- (GRMustacheTemplate *)templateFromString:(NSString *)templateString error:(NSError **)error

Parameters

templateString

A Mustache template string

error

If there is an error loading or parsing template and

                   partials, upon return contains an NSError object that
                   describes the problem.

Return Value

a GRMustacheTemplate

Availability

Discussion

Depending on the way the repository has been created, partial tags such as {{>partial}} load partial templates from URLs, file paths, keys in a dictionary, or whatever is relevant to the repository’s data source.

Declared In

GRMustacheTemplateRepository.h

templateNamed:error:

Returns a template identified by its name.

- (GRMustacheTemplate *)templateNamed:(NSString *)name error:(NSError **)error

Parameters

name

The template name

error

If there is an error loading or parsing template and

             partials, upon return contains an NSError object that
             describes the problem.

Return Value

a GRMustacheTemplate

Availability

Discussion

Depending on the way the repository has been created, the name identifies a URL, a file path, a key in a dictionary, or whatever is relevant to the repository’s data source.

Declared In

GRMustacheTemplateRepository.h