Template

final public class Template

Template instances render Mustache templates.

  • Creates a template from a template string.

    Throws

    MustacheError

    Declaration

    Swift

    public convenience init(string: String) throws

    Parameters

    string

    The template string.

  • Creates a template from the contents of a file.

    Eventual partial tags in the template refer to sibling template files using the same extension.

    // `{{>partial}}` in `/path/to/template.txt` loads `/path/to/partial.txt`:
    let template = try! Template(path: "/path/to/template.txt")
    

    Throws

    MustacheError

    Declaration

    Swift

    public convenience init(path: String, encoding: String.Encoding = String.Encoding.utf8) throws

    Parameters

    path

    The path to the template file.

    encoding

    The encoding of the template file.

  • Creates a template from the contents of a URL.

    Eventual partial tags in the template refer to sibling templates using the same extension.

    // `{{>partial}}` in `file://path/to/template.txt` loads `file://path/to/partial.txt`:
    let template = try! Template(URL: "file://path/to/template.txt")
    

    Throws

    MustacheError

    Declaration

    Swift

    public convenience init(URL: Foundation.URL, encoding: String.Encoding = String.Encoding.utf8) throws

    Parameters

    URL

    The URL of the template.

    encoding

    The encoding of the template resource.

  • Throws

    MustacheError

    Declaration

    Swift

    public convenience init(named name: String, bundle: Bundle? = nil, templateExtension: String? = "mustache", encoding: String.Encoding = String.Encoding.utf8) throws

    Parameters

    templateExtension

    If extension is an empty string or nil, the extension is assumed not to exist and the template file should exactly match name.

    encoding

    The encoding of template resource.

  • Renders a template with a context stack initialized with the provided value on top of the templates’s base context.

    Throws

    MustacheError

    Declaration

    Swift

    public func render(_ value: Any? = nil) throws -> String

    Parameters

    value

    A value.

    Return Value

    The rendered string.

  • Returns the rendering of the receiver, evaluating mustache tags from values stored in the given context stack.

    This method does not return a String, but a Rendering value that wraps both the rendered string and its content type (HTML or Text). It is intended to be used when you perform custom rendering in a RenderFunction.

    Throws

    MustacheError

    Seealso

    RenderFunction

    Seealso

    Template.contentType

    Declaration

    Swift

    public func render(_ context: Context) throws -> Rendering

    Parameters

    context

    A context stack

    Return Value

    The template rendering.

  • The content type of the template and of its renderings.

    See Configuration.contentType for a full discussion of the content type of templates.

    Declaration

    Swift

    public var contentType: ContentType
  • The template’s base context: all renderings start from this context.

    Its default value comes from the configuration of the template repository this template comes from.

    You can set the base context to some custom context, or extend it with the extendBaseContext(_) and register(_:forKey:) methods.

    // Renders "Arthur"
    let template = try! Template(string: "{{name}}")
    template.baseContext = Context(["name": "Arthur"])
    try! template.render()
    

    Seealso

    extendBaseContext(_)

    Seealso

    register(_:forKey:)

    Declaration

    Swift

    public var baseContext: Context
  • Extends the base context with the provided boxed value. All renderings will start from this extended context.

    // Renders "Arthur"
    let template = try! Template(string: "{{name}}")
    template.extendBaseContext(["name": "Arthur"])
    try! template.render()
    

    Seealso

    baseContext

    Seealso

    register(_:forKey:)

    Seealso

    Context.extendedContext

    Declaration

    Swift

    public func extendBaseContext(_ value: Any?)
  • Registers the value for the given key in the base context. Registered keys are looked up first when evaluating Mustache tags.

    // Renders "Arthur"
    let template = try! Template(string: "{{name}}")
    template.register("Arthur", forKey: "name")
    try! template.render()
    
    // Renders "Arthur" again, because the registered key "name" has priority.
    try! template.render(["name": "Barbara"])
    

    Seealso

    baseContext

    Seealso

    extendBaseContext(_)

    Seealso

    Context.extendedContext(withRegisteredValue:forKey:)

    Declaration

    Swift

    public func register(_ value: Any?, forKey key: String)
  • The template repository that issued the template.

    All templates belong a template repository:

  • Templates returned by init(string:) have a template repository that can not load any template or partial by name.

  • Templates returned by init(path:encoding:) have a template repository that loads templates and partials stored in the directory of the receiver, with the same file extension.

  • Templates returned by init(URL:encoding:) have a template repository that loads templates and partials stored in the directory of the receiver, with the same file extension.

  • Templates returned by init(named:bundle:templateExtension:encoding:) have a template repository that loads templates and partials stored as resources in the specified bundle.

  • Templates returned by TemplateRepository.template(named:) and TemplateRepository.template(string:) belong to the invoked repository.

  • Seealso

    TemplateRepository

    Seealso

    init(string:)

    Seealso

    init(path:)

    Seealso

    init(URL:)

    Seealso

    init(named:bundle:templateExtension:encoding:)

    Declaration

    Swift

    public let repository: TemplateRepository
  • Template adopts the MustacheBoxable protocol so that it can feed Mustache templates.

    You should not directly call the mustacheBox property.

    A template renders just like a partial tag:

    • {{template}} renders like an embedded partial tag {{>partial}} that would refer to the same template.

    • {{#template}}...{{/template}} renders like a partial override tag {{<partial}}...{{/partial}} that would refer to the same template.

    The difference is that {{>partial}} is a hard-coded template name, when {{template}} is a template that you can choose at runtime.

    For example:

    let template = try! Template(string: "<a href='{{url}}'>{{firstName}} {{lastName}}</a>")
    let data: [String: Any] = [
        "firstName": "Salvador",
        "lastName": "Dali",
        "url": "/people/123",
        "template": template
    ]
    
    // <a href='/people/123'>Salvador Dali</a>
    try! Template(string: "{{template}}").render(data)
    

    Note that templates whose contentType is Text are HTML-escaped when they are included in an HTML template.

    Declaration

    Swift

    public var mustacheBox: MustacheBox
  • A textual representation of self, suitable for debugging.

    Declaration

    Swift

    public var debugDescription: String