Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

add erubis, haml, and mustache docs to TEMPLATES.md

  • Loading branch information...
commit 2a4b2c0f5d120287aeb465ef41d33601b6b61443 1 parent 531c141
@rtomayko authored
Showing with 231 additions and 51 deletions.
  1. +217 −8 TEMPLATES.md
  2. +14 −43 lib/tilt.rb
View
225 TEMPLATES.md
@@ -1,11 +1,22 @@
-Templates
-=========
+Tilt Templates
+==============
+While all Tilt templates use the same basic interface for template loading and
+evaluation, each varies in its capabilities and available options. Detailed
+documentation on each supported template engine is provided below.
+
+ * [ERB](#erb)
+ * [Erubis](#erubis)
+ * [Haml](#haml)
+ * [Mustache](#mustache)
+
+----
+
+<a name='erb'></a>
ERB (`erb`, `rhtml`)
--------------------
-[Docs](http://www.ruby-doc.org/stdlib/libdoc/erb/rdoc/classes/ERB.html) |
-[Syntax](http://vision-media.ca/resources/ruby/ruby-rdoc-documentation-syntax)
+An easy to use but powerful templating system for Ruby.
### Example
@@ -28,9 +39,12 @@ Or, use the `Tilt::ERBTemplate` class directly to process strings:
template = Tilt::ERBTemplate.new(nil, :trim => '<>') { "Hello <%= world %>!" }
template.render(self, :world => 'World!')
+__NOTE:__ It's suggested that your program `require 'erb'` at load time when
+using this template engine within a threaded environment.
+
### Options
-`:trim => '-'`
+#### `:trim => '-'`
The ERB trim mode flags. This is a string consisting
of any combination of the following characters:
@@ -40,10 +54,205 @@ of any combination of the following characters:
* `'-'` omits newlines for lines ending in `-%>`.
* `'%'` enables processing of lines beginning with `%`
-`:safe => nil`
+#### `:safe => nil`
The `$SAFE` level; when set, ERB code will be run in a
separate thread with `$SAFE` set to the provided level.
-It's suggested that your program require 'erb' at load time when using this
-template engine.
+### See also
+
+ * [ERB documentation](http://www.ruby-doc.org/stdlib/libdoc/erb/rdoc/classes/ERB.html)
+
+----
+
+<a name='erubis'></a>
+Erubis (`erubis`)
+-----------------
+
+Erubis is a fast, secure, and very extensible implementation of eRuby.
+
+### Usage
+
+To use Erubis instead of ERB for all `.erb` and `.rhtml` files, register
+the extensions as follows:
+
+ Tilt.register 'erb', Tilt::ErubisTemplate
+ Tilt.register 'rhtml', Tilt::ErubisTemplate
+
+See the [ERB](#erb) template documentation for examples, usage, and options.
+
+__NOTE:__ It's suggested that your program `require 'erubis'` at load time when
+using this template engine within a threaded environment.
+
+### See also
+
+ * [Erubis Home](http://www.kuwata-lab.com/erubis/)
+ * [Erubis User's Guide](http://www.kuwata-lab.com/erubis/users-guide.html)
+
+----
+
+<a name='haml'></a>
+Haml (`haml`)
+-------------
+
+Haml is a markup language that’s used to cleanly and simply describe the HTML of
+any web document without the use of inline code. Haml functions as a replacement
+for inline page templating systems such as PHP, ASP, and ERB, the templating
+language used in most Ruby on Rails applications. However, Haml avoids the
+need for explicitly coding HTML into the template, because it itself is a
+description of the HTML, with some code to generate dynamic content.
+([more](http://haml-lang.com/about.html))
+
+
+### Example
+
+ %html
+ %head
+ %title= @title
+ %body
+ %h1
+ Hello
+ = world + '!'
+
+### Usage
+
+The `Tilt::HamlTemplate` class is registered for all files ending in `.haml`
+by default. Haml templates support custom evaluation scopes and locals:
+
+ >> require 'haml'
+ >> template = Tilt.new('hello.haml')
+ => #<Tilt::HamlTemplate @file='hello.haml'>
+ >> @title = "Hello Haml!"
+ >> template.render(self, :world => 'Haml!')
+ => "
+ <html>
+ <head>
+ <title>Hello Haml!</title>
+ </head>
+ <body>
+ <h1>Hello Haml!</h1>
+ </body>
+ </html>"
+
+Or, use the `Tilt::HamlTemplate` class directly to process strings:
+
+ >> require 'haml'
+ >> template = Tilt::HamlTemplate.new { "%h1= 'Hello Haml!'" }
+ => #<Tilt::HamlTemplate @file=nil ...>
+ >> template.render
+ => "<h1>Hello Haml!</h1>"
+
+__NOTE:__ It's suggested that your program `require 'haml'` at load time when
+using this template engine within a threaded environment.
+
+### Options
+
+#### `:format => :xhtml`
+
+Determines the output format. The default is `:xhtml`. Other options are
+`:html4` and `:html5`, which are identical to `:xhtml` except there are no
+self-closing tags, the XML prolog is ignored and correct DOCTYPEs are generated.
+
+#### `:escape_html => false`
+
+Sets whether or not to escape HTML-sensitive characters in script. If this is
+true, `=` behaves like `&=;` otherwise, it behaves like `!=`. Note that if this
+is set, `!=` should be used for yielding to subtemplates and rendering partials.
+Defaults to false.
+
+#### `:ugly => false`
+
+If set to true, Haml makes no attempt to properly indent or format the HTML
+output. This causes the rendering to be done much quicker than it would
+otherwise, but makes viewing the source unpleasant. Defaults to false.
+
+#### `:suppress_eval => false`
+
+Whether or not attribute hashes and Ruby scripts designated by `=` or `~` should
+be evaluated. If this is true, said scripts are rendered as empty strings.
+Defaults to false.
+
+#### `:attr_wrapper => "'"`
+
+The character that should wrap element attributes. This defaults to `'` (an
+apostrophe). Characters of this type within the attributes will be escaped (e.g.
+by replacing them with `&apos;`) if the character is an apostrophe or a
+quotation mark.
+
+#### `:autoclose => %w[meta img link br hr input area param col base]`
+
+A list of tag names that should be automatically self-closed if they have no
+content. Defaults to `['meta', 'img', 'link', 'br', 'hr', 'input', 'area',
+'param', 'col', 'base']`.
+
+#### `:preserve => %w[textarea pre]`
+
+A list of tag names that should automatically have their newlines preserved
+using the `Haml::Helpers#preserve` helper. This means that any content given on
+the same line as the tag will be preserved. For example, `%textarea= "Foo\nBar"`
+compiles to `<textarea>Foo&#x000A;Bar</textarea>`. Defaults to `['textarea',
+'pre']`.
+
+#### `:encoding => 'utf-8'`
+
+The encoding to use for the HTML output. Only available in Ruby 1.9 or higher.
+This can be a string or an Encoding Object. Note that Haml does not
+automatically re-encode Ruby values; any strings coming from outside the
+application should be converted before being passed into the Haml template.
+Defaults to `Encoding.default_internal` or, if that's not set, `"utf-8"`.
+
+### See also
+
+ * [#haml.docs](http://haml-lang.com/docs.html)
+ * [Haml Tutorial](http://haml-lang.com/tutorial.html)
+ * [Haml Reference](http://haml-lang.com/docs/yardoc/HAML_REFERENCE.md.html)
+ * [Whitespace Preservation](http://haml-lang.com/docs/yardoc/HAML_REFERENCE.md.html#whitespace_preservation)
+
+
+----
+
+<a name='mustache'></a>
+Mustache (`mustache`)
+---------------------
+
+Mustache is a framework-agnostic way to render logic-free views.
+
+### Options
+
+__NOTE:__ It's suggested that your program `require 'mustache'` at load time
+when using this template engine in a threaded environment.
+
+#### `:path => Dir.pwd`
+
+The base path where mustache templates (`.html` files) are located. Defaults to
+the current working directory.
+
+#### `:template_extension => 'html'`
+
+The file extension used on mustache templates. Default is `'html'`.
+
+#### `:namespace => Object`
+
+The class or module where View classes are located. If you have
+`Hurl::App::Views`, namespace should be `Hurl:App`. This defaults to `Object`,
+causing `::Views` to be searched for classes.
+
+#### `:mustaches => nil`
+
+Where mustache views (.rb files) are located, or nil to disable auto-requiring
+of views based on template names. By default, the view file is assumed to be in
+the same directory as the template file.
+
+All other options are assumed to be attribute writer's on the Mustache
+class and are set when a template is compiled. They are:
+
+#### `:view => nil`
+
+The Mustache subclass that should be used a the view. When this option is
+specified, the template file will be determined from the view class, and the
+`:namespace` and `:mustaches` options are irrelevant.
+
+### See also
+
+ * [Mustache Docs](http://defunkt.github.com/mustache/)
+ * [defunkt/mustache](http://github.com/defunkt/mustache) on GitHub
View
57 lib/tilt.rb
@@ -44,6 +44,7 @@ def self.[](file)
end
end
+
# Base class for template implementations. Subclasses must implement
# the #compile! method and one of the #evaluate or #template_source
# methods.
@@ -165,8 +166,10 @@ def clear
end
end
+
# Template Implementations ================================================
+
# The template source is evaluated as a Ruby string. The #{} interpolation
# syntax can be used to generated dynamic output.
class StringTemplate < Template
@@ -180,11 +183,9 @@ def template_source
end
register 'str', StringTemplate
+
# ERB template implementation. See:
# http://www.ruby-doc.org/stdlib/libdoc/erb/rdoc/classes/ERB.html
- #
- # It's suggested that your program require 'erb' at load
- # time when using this template engine.
class ERBTemplate < Template
def compile!
require_template_library 'erb' unless defined?(::ERB)
@@ -224,11 +225,9 @@ def local_assignment_code(locals)
end
%w[erb rhtml].each { |ext| register ext, ERBTemplate }
+
# Erubis template implementation. See:
# http://www.kuwata-lab.com/erubis/
- #
- # It's suggested that your program require 'erubis' at load
- # time when using this template engine.
class ErubisTemplate < ERBTemplate
def compile!
require_template_library 'erubis' unless defined?(::Erubis)
@@ -238,11 +237,9 @@ def compile!
end
register 'erubis', ErubisTemplate
+
# Haml template implementation. See:
# http://haml.hamptoncatlin.com/
- #
- # It's suggested that your program require 'haml' at load
- # time when using this template engine.
class HamlTemplate < Template
def compile!
require_template_library 'haml' unless defined?(::Haml::Engine)
@@ -260,13 +257,11 @@ def haml_options
end
register 'haml', HamlTemplate
+
# Sass template implementation. See:
# http://haml.hamptoncatlin.com/
#
# Sass templates do not support object scopes, locals, or yield.
- #
- # It's suggested that your program require 'sass' at load
- # time when using this template engine.
class SassTemplate < Template
def compile!
require_template_library 'sass' unless defined?(::Sass::Engine)
@@ -284,11 +279,9 @@ def sass_options
end
register 'sass', SassTemplate
+
# Builder template implementation. See:
# http://builder.rubyforge.org/
- #
- # It's suggested that your program require 'builder' at load
- # time when using this template engine.
class BuilderTemplate < Template
def compile!
require_template_library 'builder' unless defined?(::Builder)
@@ -311,6 +304,7 @@ def template_source
end
register 'builder', BuilderTemplate
+
# Liquid template implementation. See:
# http://liquid.rubyforge.org/
#
@@ -331,6 +325,7 @@ def evaluate(scope, locals, &block)
end
register 'liquid', LiquidTemplate
+
# Discount Markdown implementation.
class RDiscountTemplate < Template
def compile!
@@ -345,37 +340,13 @@ def evaluate(scope, locals, &block)
register 'markdown', RDiscountTemplate
register 'md', RDiscountTemplate
+
# Mustache is written and maintained by Chris Wanstrath. See:
# http://github.com/defunkt/mustache
#
- # It's suggested that your program require 'mustache' at load
- # time when using this template engine.
- #
- # Mustache templates support the following options:
- #
- # * :view - The Mustache subclass that should be used a the view. When
- # this option is specified, the template file will be determined from
- # the view class, and the :namespace and :mustaches options are
- # irrelevant.
- #
- # * :namespace - The class or module where View classes are located.
- # If you have Hurl::App::Views, namespace should be Hurl:App. This
- # defaults to Object, causing ::Views to be searched for classes.
- #
- # * :mustaches - Where mustache views (.rb files) are located, or nil
- # disable auto-requiring of views based on template names. By default,
- # the view file is assumed to be in the same directory as the template
- # file.
- #
- # All other options are assumed to be attribute writer's on the Mustache
- # class and are set when a template is compiled. They are:
- #
- # * :path - The base path where mustache templates (.html files) are
- # located. This defaults to the current working directory.
- #
- # * :template_extension - The file extension used on mustache templates.
- # The default is 'html'.
- #
+ # When a scope argument is provided to MustacheTemplate#render, the
+ # instance variables are copied from the scope object to the Mustache
+ # view.
class MustacheTemplate < Template
attr_reader :engine
Please sign in to comment.
Something went wrong with that request. Please try again.