Mustache

Mustache is the base class from which your Mustache subclasses should inherit (though it can be used on its own).

The typical Mustache workflow is as follows:

Create a Mustache subclass: class Stats < Mustache
Create a template: stats.mustache
Instantiate an instance: view = Stats.new
Render that instance: view.render

You can skip the instantiation by calling `Stats.render` directly.

While Mustache will do its best to load and render a template for you, this process is completely customizable using a few options.

All settings can be overriden at the class level.

For example, going with the above example, we can use `Stats.template_path = “/usr/local/templates”` to specify the path Mustache uses to find templates.

Here are the available options:

template_path

The `template_path` setting determines the path Mustache uses when looking for a template. By default it is “.” Setting it to /usr/local/templates, for example, means (given all other settings are default) a Mustache subclass `Stats` will try to load /usr/local/templates/stats.mustache

template_extension

The `template_extension` is the extension Mustache uses when looking for template files. By default it is “mustache”

template_file

You can tell Mustache exactly which template to us with this setting. It can be a relative or absolute path.

template

Sometimes you want Mustache to render a string, not a file. In those cases you may set the `template` setting. For example:

>> Mustache.render("Hello {{planet}}", :planet => "World!")
=> "Hello World!"

The `template` setting is also available on instances.

view = Mustache.new
view.template = "Hi, {{person}}!"
view[:person] = 'Mom'
view.render # => Hi, mom!

view_namespace

To make life easy on those developing Mustache plugins for web frameworks or other libraries, Mustache will attempt to load view classes (i.e. Mustache subclasses) using the `view_class` class method. The `view_namespace` tells Mustache under which constant view classes live. By default it is `Object`.

view_path

Similar to `template_path`, the `view_path` option tells Mustache where to look for files containing view classes when using the `view_class` method.

Constants

Version

Attributes

raise_on_context_miss[W]

Public Class Methods

classify(underscored) click to toggle source

template_partial => TemplatePartial

# File lib/mustache.rb, line 267
def self.classify(underscored)
  underscored.split(/[-_]/).map do |part|
    part[0] = part[0].chr.upcase; part
  end.join
end

compiled?() click to toggle source

Has this template already been compiled? Compilation is somewhat expensive so it may be useful to check this before attempting it.

# File lib/mustache.rb, line 257
def self.compiled?
  @template.is_a? Template
end

inheritable_config_for(attr_name, default) click to toggle source

Return the value of the configuration setting on the superclass, or return the default.

attr_name - Symbol name of the attribute. It should match the instance variable. default - Default value to use if the superclass does not respond.

Returns the inherited or default configuration setting.

# File lib/mustache.rb, line 301
def self.inheritable_config_for(attr_name, default)
  superclass.respond_to?(attr_name) ? superclass.send(attr_name) : default
end

partial(name) click to toggle source

Given a name, attempts to read a file and return the contents as a string. The file is not rendered, so it might contain {{mustaches}}.

Call `render` if you need to process it.

# File lib/mustache.rb, line 108
def self.partial(name)
  File.read("#{template_path}/#{name}.#{template_extension}")
end

path() click to toggle source

Alias for `template_path`

# File lib/mustache.rb, line 131
def self.path
  template_path
end

path=(path) click to toggle source

Alias for `template_path`

# File lib/mustache.rb, line 136
def self.path=(path)
  self.template_path = path
end

raise_on_context_miss=(boolean) click to toggle source

# File lib/mustache.rb, line 251
def self.raise_on_context_miss=(boolean)
  @raise_on_context_miss = boolean
end

raise_on_context_miss?() click to toggle source

Should an exception be raised when we cannot find a corresponding method or key in the current context? By default this is false to emulate ctemplate’s behavior, but it may be useful to enable when debugging or developing.

If set to true and there is a context miss, `Mustache::ContextMiss` will be raised.

# File lib/mustache.rb, line 247
def self.raise_on_context_miss?
  @raise_on_context_miss
end

render(*args) click to toggle source

Instantiates an instance of this class and calls `render` with the passed args.

Returns a rendered String version of a template

# File lib/mustache.rb, line 77
def self.render(*args)
  new.render(*args)
end

render_file(name, context = {}) click to toggle source

Given a file name and an optional context, attempts to load and render the file as a template.

# File lib/mustache.rb, line 93
def self.render_file(name, context = {})
  render(partial(name), context)
end

template() click to toggle source

The template is the actual string Mustache uses as its template. There is a bit of magic here: what we get back is actually a Mustache::Template object here, but you can still safely use `template=` with a string.

# File lib/mustache.rb, line 176
def self.template
  @template ||= templateify(File.read(template_file))
end

template=(template) click to toggle source

# File lib/mustache.rb, line 180
def self.template=(template)
  @template = templateify(template)
end

template_extension() click to toggle source

A Mustache template’s default extension is ‘mustache’

# File lib/mustache.rb, line 141
def self.template_extension
  @template_extension ||= inheritable_config_for :template_extension, 'mustache'
end

template_extension=(template_extension) click to toggle source

# File lib/mustache.rb, line 145
def self.template_extension=(template_extension)
  @template_extension = template_extension
  @template = nil
end

template_file() click to toggle source

The template file is the absolute path of the file Mustache will use as its template. By default it’s ./class_name.mustache

# File lib/mustache.rb, line 163
def self.template_file
  @template_file || "#{path}/#{template_name}.#{template_extension}"
end

template_file=(template_file) click to toggle source

# File lib/mustache.rb, line 167
def self.template_file=(template_file)
  @template_file = template_file
  @template = nil
end

template_name() click to toggle source

The template name is the Mustache template file without any extension or other information. Defaults to `class_name`.

# File lib/mustache.rb, line 152
def self.template_name
  @template_name || underscore
end

template_name=(template_name) click to toggle source

# File lib/mustache.rb, line 156
def self.template_name=(template_name)
  @template_name = template_name
  @template = nil
end

template_path() click to toggle source

The template path informs your Mustache subclass where to look for its corresponding template. By default it’s the current directory (“.”)

# File lib/mustache.rb, line 121
def self.template_path
  @template_path ||= inheritable_config_for :template_path, '.'
end

template_path=(path) click to toggle source

# File lib/mustache.rb, line 125
def self.template_path=(path)
  @template_path = File.expand_path(path)
  @template = nil
end

templateify(obj) click to toggle source

Turns a string into a Mustache::Template. If passed a Template, returns it.

# File lib/mustache.rb, line 286
def self.templateify(obj)
  if obj.is_a?(Template)
    obj
  else
    Template.new(obj.to_s)
  end
end

to_html(*args) click to toggle source

Alias for `render`

# File lib/mustache.rb, line 82
def self.to_html(*args)
  render(*args)
end

to_text(*args) click to toggle source

Alias for `render`

# File lib/mustache.rb, line 87
def self.to_text(*args)
  render(*args)
end

underscore(classified = name) click to toggle source

TemplatePartial => template_partial Takes a string but defaults to using the current class’ name.

# File lib/mustache.rb, line 275
def self.underscore(classified = name)
  classified = name if classified.to_s.empty?
  classified = superclass.name if classified.to_s.empty?

  string = classified.dup.split('::').last
  string[0] = string[0].chr.downcase
  string.gsub(/[A-Z]/) { |s| "_#{s.downcase}"}
end

view_class(name) click to toggle source

When given a symbol or string representing a class, will try to produce an appropriate view class. e.g.

Mustache.view_namespace = Hurl::Views
Mustache.view_class(:Partial) # => Hurl::Views::Partial

# File lib/mustache.rb, line 210
def self.view_class(name)
  if name != classify(name.to_s)
    name = classify(name.to_s)
  end

  # Emptiness begets emptiness.
  if name.to_s == ''
    return Mustache
  end

  file_name = underscore(name)
  namespace = view_namespace

  if namespace.const_defined?(:Views) && namespace::Views.const_defined?(name)
    namespace::Views.const_get(name)
  elsif namespace.const_defined?(name)
    namespace.const_get(name)
  elsif File.exists?(file = "#{view_path}/#{file_name}.rb")
    require "#{file}".chomp('.rb')
    if namespace.const_defined?(:Views)
      namespace::Views.const_get(name)
    else
      namespace.const_get(name)
    end
  else
    Mustache
  end
rescue NameError
  Mustache
end

view_namespace() click to toggle source

The constant under which Mustache will look for views. By default it’s `Object`, but it might be nice to set it to something like `Hurl::Views` if your app’s main namespace is `Hurl`.

# File lib/mustache.rb, line 187
def self.view_namespace
  @view_namespace ||= inheritable_config_for(:view_namespace, Object)
end

view_namespace=(namespace) click to toggle source

# File lib/mustache.rb, line 191
def self.view_namespace=(namespace)
  @view_namespace = namespace
end

view_path() click to toggle source

Mustache searches the view path for .rb files to require when asked to find a view class. Defaults to "."

# File lib/mustache.rb, line 197
def self.view_path
  @view_path ||= inheritable_config_for(:view_path, '.')
end

view_path=(path) click to toggle source

# File lib/mustache.rb, line 201
def self.view_path=(path)
  @view_path = path
end

Public Instance Methods

[](key) click to toggle source

Context accessors.

view = Mustache.new view = “Jon” view.template = “Hi, {{name}}!” view.render # => “Hi, Jon!”

# File lib/mustache.rb, line 337
def [](key)
  context[key.to_sym]
end

[]=(key, value) click to toggle source

# File lib/mustache.rb, line 341
def []=(key, value)
  context[key.to_sym] = value
end

compiled?() click to toggle source

Has this instance or its class already compiled a template?

# File lib/mustache.rb, line 262
def compiled?
  (@template && @template.is_a?(Template)) || self.class.compiled?
end

context() click to toggle source

A helper method which gives access to the context at a given time. Kind of a hack for now, but useful when you’re in an iterating section and want access to the hash currently being iterated over.

# File lib/mustache.rb, line 327
def context
  @context ||= Context.new(self)
end

partial(name) click to toggle source

Override this in your subclass if you want to do fun things like reading templates from a database. It will be rendered by the context, so all you need to do is return a string.

# File lib/mustache.rb, line 115
def partial(name)
  self.class.partial(name)
end

raise_on_context_miss?() click to toggle source

Instance level version of `Mustache.raise_on_context_miss?`

# File lib/mustache.rb, line 319
def raise_on_context_miss?
  self.class.raise_on_context_miss? || @raise_on_context_miss
end

render(data = template, ctx = {}) click to toggle source

Parses our fancy pants template file and returns normal file with all special {{tags}} and {{sections}}replaced{{/sections}}.

data - A String template or a Hash context. If a Hash is given,

      we'll try to figure out the template from the class.
ctx - A Hash context if `data` is a String template.

Examples

@view.render("Hi {{thing}}!", :thing => :world)

View.template = "Hi {{thing}}!"
@view = View.new
@view.render(:thing => :world)

Returns a rendered String version of a template

# File lib/mustache.rb, line 361
def render(data = template, ctx = {})
  if data.is_a? Hash
    ctx = data
    tpl = templateify(template)
  else
    tpl = templateify(data)
  end

  return tpl.render(context) if ctx == {}

  begin
    context.push(ctx)
    tpl.render(context)
  ensure
    context.pop
  end
end

Also aliased as: to_html, to_text

render_file(name, context = {}) click to toggle source

Given a file name and an optional context, attempts to load and render the file as a template.

# File lib/mustache.rb, line 99
def render_file(name, context = {})
  self.class.render_file(name, context)
end

template() click to toggle source

The template can be set at the instance level.

# File lib/mustache.rb, line 310
def template
  @template ||= self.class.template
end

template=(template) click to toggle source

# File lib/mustache.rb, line 314
def template=(template)
  @template = templateify(template)
end

templateify(obj) click to toggle source

# File lib/mustache.rb, line 305
def templateify(obj)
  self.class.templateify(obj)
end

to_html(data = template, ctx = {}) click to toggle source

Alias for: render

to_text(data = template, ctx = {}) click to toggle source

Alias for: render

Home Classes Methods

In Files

Parent

Namespace

Methods

Class/Module Index

Mustache

Constants

Attributes

Public Class Methods

Public Instance Methods