README.md in tilt-1.2.2 vs README.md in tilt-1.3

- old
+ new

@@ -19,26 +19,33 @@ The primary goal is to get all of the things listed above right for all template engines included in the distribution. Support for these template engines is included with the package: - ENGINE FILE EXTENSIONS REQUIRED LIBRARIES - -------------------------- ----------------- ---------------------------- - ERB .erb none (included ruby stdlib) - Interpolated String .str none (included ruby core) - Haml .haml haml - Sass .sass haml - Less CSS .less less - Builder .builder builder - Liquid .liquid liquid - RDiscount .markdown rdiscount - RedCloth .textile redcloth - RDoc .rdoc rdoc - Radius .radius radius - Markaby .mab markaby - Nokogiri .nokogiri nokogiri - CoffeeScript .coffee coffee-script (+node coffee) + ENGINE FILE EXTENSIONS REQUIRED LIBRARIES + -------------------------- ---------------------- ---------------------------- + ERB .erb, .rhtml none (included ruby stdlib) + Interpolated String .str none (included ruby core) + Erubis .erb, .rhtml, .erubis erubis + Haml .haml haml + Sass .sass haml (< 3.1) or sass (>= 3.1) + Scss .scss haml (< 3.1) or sass (>= 3.1) + Less CSS .less less + Builder .builder builder + Liquid .liquid liquid + RDiscount .markdown, .mkd, .md rdiscount + Redcarpet .markdown, .mkd, .md redcarpet + BlueCloth .markdown, .mkd, .md bluecloth + Kramdown .markdown, .mkd, .md kramdown + Maruku .markdown, .mkd, .md maruku + RedCloth .textile redcloth + RDoc .rdoc rdoc + Radius .radius radius + Markaby .mab markaby + Nokogiri .nokogiri nokogiri + CoffeeScript .coffee coffee-script (+ javascript) + Creole (Wiki markup) .creole creole These template engines ship with their own Tilt integration: ENGINE FILE EXTENSIONS REQUIRED LIBRARIES -------------------------- ----------------- ---------------------------- @@ -114,11 +121,11 @@ 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.new('views/foo.bar') => #<Tilt::ERBTemplate @file="views/foo.bar" ...> Retrieving the template class for a file or file extension: @@ -129,11 +136,11 @@ 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` files: - >> Tilt.register 'bar.erb', Tilt::ErubisTemplate + >> Tilt.register Tilt::ErubisTemplate, 'bar.erb' >> Tilt.new('views/foo.erb') => Tilt::ERBTemplate >> Tilt.new('views/bar.erb') => Tilt::ErubisTemplate @@ -145,27 +152,50 @@ 1. `views/foo.html.erb` 2. `foo.html.erb` 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 already: 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 -------------------- Tilt compiles generated Ruby source code produced by template engines and reuses it on subsequent template invocations. Benchmarks show this yields a 5x-10x performance increase over evaluating the Ruby source on each invocation. Template compilation is currently supported for these template engines: -StringTemplate, ERB, Erubis, Haml, and Builder. +StringTemplate, ERB, Erubis, Haml, Nokogiri and Builder. LICENSE ------- Tilt is Copyright (c) 2010 [Ryan Tomayko](http://tomayko.com/about) and