Browse files

Add documentation for fallback mode

  • Loading branch information...
1 parent 882b466 commit b52ddae7029c8c8ae77a51e851b7d9c6b65ab1c0 @judofyr judofyr committed Mar 25, 2011
Showing with 42 additions and 14 deletions.
  1. +30 −7
  2. +12 −7
@@ -116,7 +116,7 @@ classes based on those associations.
The `Tilt::register` method associates a filename pattern with a specific
template implementation. To use ERB for files ending in a `.bar` extension:
- >> Tilt.register 'bar', Tilt::ERBTemplate
+ >> Tilt.register Tilt::ERBTemplate, 'bar'
=> #<Tilt::ERBTemplate @file="views/" ...>
@@ -131,7 +131,7 @@ It's also possible to register template file mappings that are more specific
than a file extension. To use Erubis for `bar.erb` but ERB for all other `.erb`
- >> Tilt.register 'bar.erb', Tilt::ErubisTemplate
+ >> Tilt.register Tilt::ErubisTemplate, 'bar.erb'
=> Tilt::ERBTemplate
@@ -147,14 +147,37 @@ mappings:
3. `html.erb`
4. `erb`
-`Tilt::register` can also be used to select between alternative template
-engines. To use Erubis instead of ERB for `.erb` files:
+### Fallback mode
- Tilt.register 'erb', Tilt::ErubisTemplate
+If there are more than one template class registered for a file extension, Tilt
+will automatically try to load the version that works on your machine:
-Or, use BlueCloth for markdown instead of RDiscount:
+ 1. If any of the template engines has been loaded alreaedy: Use that one.
+ 2. If not, it will try to initialize each of the classes with an empty template.
+ 3. Tilt will use the first that doesn't raise an exception.
+ 4. If however *all* of them failed, Tilt will raise the exception of the first
+ template engine, since that was the most preferred one.
- Tilt.register 'markdown', Tilt::BlueClothTemplate
+Template classes that were registered *last* would be tried first. Because the
+Markdown extensions are registered like this:
+ Tilt.register Tilt::BlueClothTemplate, 'md'
+ Tilt.register Tilt::RDiscountTemplate, 'md'
+Tilt will first try RDiscount and then BlueCloth. You could say that RDiscount
+has a *higher priority* than BlueCloth.
+The fallback mode works nicely when you just need to render an ERB or Markdown
+template, but if you depend on a specific implementation, you should use #prefer:
+ # Prefer BlueCloth for all its registered extensions (markdown, mkd, md)
+ Tilt.prefer Tilt::BlueClothTemplate
+ # Prefer Erubis for .erb only:
+ Tilt.prefer Tilt::ErubisTemplate, 'erb'
+When a file extension has a preferred template class, Tilt will *always* use
+that class, even if it raises an exception.
Template Compilation
@@ -16,7 +16,7 @@ text formats.
* Less - `Tilt::LessTemplate`
* Sass - `Tilt::SassTemplate`
- * [Markdown](#markdown) - `Tilt::RDiscountTemplate`
+ * [Markdown](#markdown) - `Tilt::RDiscountTemplate` and `Tilt::BlueClothTemplate`
* [RDoc](#rdoc) - `Tilt::RDocTemplate`
<a name='erb'></a>
@@ -32,7 +32,12 @@ An easy to use but powerful templating system for Ruby.
### Usage
The `Tilt::ERBTemplate` class is registered for all files ending in `.erb` or
-`.rhtml` by default. ERB templates support custom evaluation scopes and locals:
+`.rhtml` by default, but with a *lower* priority than ErubisTemplate. If you
+specifically want to use ERB, it's recommended to use `#prefer`:
+ Tilt.prefer Tilt::ERBTemplate
+ERB templates support custom evaluation scopes and locals:
>> require 'erb'
>> template ='hello.html.erb', :trim => '<>')
@@ -85,11 +90,11 @@ 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:
+The `Tilt::ErubisTemplate` class is registered for all files ending in `.erb` or
+`.rhtml` by default, but with a *higher* priority than `ERBTemplate`. If you
+specifically want to use Erubis, it's recommended to use `#prefer`:
- Tilt.register 'erb', Tilt::ErubisTemplate
- Tilt.register 'rhtml', Tilt::ErubisTemplate
+ Tilt.prefer Tilt::ErubisTemplate
### Options
@@ -289,7 +294,7 @@ default. Liquid templates support locals and objects that respond to
Or, use `Tilt::LiquidTemplate` directly to process strings:
>> require 'haml'
- >> template = { "<h1>Hello Liquid!</h1>" }
+ >> template = { "<h1>Hello Liquid!</h1>" }
=> #<Tilt::LiquidTemplate @file=nil ...>
>> template.render
=> "<h1>Hello Liquid!</h1>"

0 comments on commit b52ddae

Please sign in to comment.