class 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 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:
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
The `template_extension` is the extension Mustache uses when looking for template files. By default it is “mustache”
You can tell Mustache exactly which template to use 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!
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`.
Similar to `template_path`, the `view_path` option tells Mustache where to look for files containing view classes when using the `view_class` method.
Settings which can be configured for all view classes, a single view class, or a single Mustache instance.
Constants
- Enumerable
- VERSION
Public Class Methods
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 168 def self.partial(name) self.new.partial(name) end
Alias for `template_path`
# File lib/mustache/settings.rb, line 35 def self.path template_path end
Alias for `template_path`
# File lib/mustache/settings.rb, line 40 def self.path=(path) self.template_path = path end
# File lib/mustache/settings.rb, line 180 def self.raise_on_context_miss=(boolean) @raise_on_context_miss = boolean end
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/settings.rb, line 176 def self.raise_on_context_miss? @raise_on_context_miss end
Instantiates an instance of this class and calls `render` with the passed args.
@return A rendered String version of a template.
# File lib/mustache.rb, line 81 def self.render(*args) new.render(*args) end
Given a file name and an optional context, attempts to load and render the file as a template.
# File lib/mustache.rb, line 153 def self.render_file(name, context = {}) render(partial(name), context) end
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, but you can still safely use `template=`
with a string.
# File lib/mustache/settings.rb, line 140 def self.template @template ||= templateify(File.read(template_file)) end
# File lib/mustache/settings.rb, line 144 def self.template=(template) @template = templateify(template) end
A Mustache template's default extension is 'mustache', but this can be changed.
# File lib/mustache/settings.rb, line 51 def self.template_extension @template_extension ||= inheritable_config_for :template_extension, 'mustache' end
# File lib/mustache/settings.rb, line 55 def self.template_extension=(template_extension) @template_extension = template_extension @template = nil end
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/settings.rb, line 110 def self.template_file @template_file || "#{path}/#{template_name}.#{template_extension}" end
# File lib/mustache/settings.rb, line 114 def self.template_file=(template_file) @template_file = template_file @template = nil end
The template name is the Mustache template file without any extension or other information. Defaults to `class_name`.
You may want to change this if your class is named Stat but you want to re-use another template.
class Stat self.template_name = "graphs" # use graphs.mustache end
# File lib/mustache/settings.rb, line 84 def self.template_name @template_name || underscore end
# File lib/mustache/settings.rb, line 88 def self.template_name=(template_name) @template_name = template_name @template = nil end
The template path informs your Mustache view where to look for its corresponding template. By default it's the current directory (“.”)
A class named Stat with a ::template_path of “app/templates” will look for “app/templates/stat.mustache”
# File lib/mustache/settings.rb, line 15 def self.template_path @template_path ||= inheritable_config_for :template_path, '.' end
# File lib/mustache/settings.rb, line 19 def self.template_path=(path) @template_path = File.expand_path(path) @template = nil end
The constant under which Mustache will look for views when autoloading. By default the view namespace is `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/settings.rb, line 202 def self.view_namespace @view_namespace ||= inheritable_config_for(:view_namespace, Object) end
# File lib/mustache/settings.rb, line 206 def self.view_namespace=(namespace) @view_namespace = namespace end
Mustache searches the view path for .rb files to require when asked to find a view class. Defaults to “.”
# File lib/mustache/settings.rb, line 218 def self.view_path @view_path ||= inheritable_config_for(:view_path, '.') end
# File lib/mustache/settings.rb, line 222 def self.view_path=(path) @view_path = path end
Private Class Methods
template_partial => TemplatePartial template/partial => Template::Partial
# File lib/mustache.rb, line 256 def self.classify(underscored) Mustache::Utils::String.new(underscored).classify end
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 249 def self.compiled? @template.is_a? Template end
# File lib/mustache.rb, line 237 def self.const_from_file name file_name = underscore(name) file_path = "#{view_path}/#{file_name}.rb" return Mustache unless File.exists?(file_path) require file_path.chomp('.rb') rescued_const_get(name) end
Return the value of the configuration setting on the superclass, or return the default.
@param [Symbol] attr_name Name of the attribute. It should match
the instance variable.
@param [Object] default Default value to use if the superclass does
not respond.
@return Inherited or default configuration setting.
# File lib/mustache.rb, line 287 def self.inheritable_config_for(attr_name, default) superclass.respond_to?(attr_name) ? superclass.send(attr_name) : default end
# File lib/mustache.rb, line 231 def self.rescued_const_get name const_get(name, true) || Mustache rescue NameError nil end
@param [Template,String] obj Turns `obj` into a template
# File lib/mustache.rb, line 270 def self.templateify(obj) obj.is_a?(Template) ? obj : Template.new(obj) end
TemplatePartial => template_partial
Template::Partial => template/partial Takes a string but defaults to using the current class' name.
# File lib/mustache.rb, line 263 def self.underscore(classified = name) classified = superclass.name if classified.to_s.empty? Mustache::Utils::String.new(classified).underscore(view_namespace) end
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 217 def self.view_class(name) name = classify(name.to_s) # Emptiness begets emptiness. return Mustache if name.to_s.empty? name = "#{view_namespace}::#{name}" const = rescued_const_get(name) return const if const const_from_file(name) end
Public Instance Methods
Context accessors.
Example:
view = Mustache.new view[:name] = "Jon" view.template = "Hi, {{name}}!" view.render # => "Hi, Jon!"
# File lib/mustache.rb, line 136 def [](key) context[key.to_sym] end
# File lib/mustache.rb, line 140 def []=(key, value) context[key.to_sym] = value end
Has this instance or its class already compiled a template?
# File lib/mustache.rb, line 204 def compiled? (@template && @template.is_a?(Template)) || self.class.compiled? end
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 147 def context @context ||= Context.new(self) end
Override this to provide custom escaping.
Example:
class PersonView < Mustache def escapeHTML(str) my_html_escape_method(str) end end
@param [String] str String to escape.
@return [String] Escaped HTML.
# File lib/mustache.rb, line 199 def escapeHTML(str) CGI.escapeHTML(str) end
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 175 def partial(name) path = "#{template_path}/#{name}.#{template_extension}" begin File.read(path) rescue raise if raise_on_context_miss? "" end end
# File lib/mustache/settings.rb, line 189 def raise_on_context_miss=(boolean) @raise_on_context_miss = boolean end
Instance level version of `Mustache.raise_on_context_miss?`
# File lib/mustache/settings.rb, line 185 def raise_on_context_miss? self.class.raise_on_context_miss? || @raise_on_context_miss end
Parses our fancy pants template file and returns normal file with all special {{tags}} and {{#sections}}replaced{{/sections}}.
Examples
@view.render("Hi {{thing}}!", :thing => :world) View.template = "Hi {{thing}}!" @view = View.new @view.render(:thing => :world)
@param [String,Hash] data A String template or a Hash context.
If a Hash is given, we'll try to figure out the template from the class.
@param [Hash] ctx A Hash context if `data` is a String template.
@return [String] Returns a rendered version of a template.
# File lib/mustache.rb, line 102 def render(data = template, ctx = {}) case data when Hash ctx = data when Symbol self.template_name = data end tpl = case data when Hash templateify(template) when Symbol templateify(template) else templateify(data) end return tpl.render(context) if ctx == {} begin context.push(ctx) tpl.render(context) ensure context.pop end end
Given a file name and an optional context, attempts to load and render the file as a template.
# File lib/mustache.rb, line 159 def render_file(name, context = {}) self.class.render_file(name, context) end
The template can be set at the instance level.
# File lib/mustache/settings.rb, line 149 def template return @template if @template # If they sent any instance-level options use that instead of the class's. if @template_path || @template_extension || @template_name || @template_file @template = templateify(File.read(template_file)) else @template = self.class.template end end
# File lib/mustache/settings.rb, line 160 def template=(template) @template = templateify(template) end
# File lib/mustache/settings.rb, line 60 def template_extension @template_extension ||= self.class.template_extension end
# File lib/mustache/settings.rb, line 64 def template_extension=(template_extension) @template_extension = template_extension @template = nil end
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/settings.rb, line 121 def template_file @template_file || "#{path}/#{template_name}.#{template_extension}" end
# File lib/mustache/settings.rb, line 125 def template_file=(template_file) @template_file = template_file @template = nil end
# File lib/mustache/settings.rb, line 93 def template_name @template_name ||= self.class.template_name end
# File lib/mustache/settings.rb, line 97 def template_name=(template_name) @template_name = template_name @template = nil end
# File lib/mustache/settings.rb, line 24 def template_path @template_path ||= self.class.template_path end
# File lib/mustache/settings.rb, line 29 def template_path=(path) @template_path = File.expand_path(path) @template = nil end
Private Instance Methods
# File lib/mustache.rb, line 274 def templateify(obj) self.class.templateify(obj) end