diff --git a/README.rdoc b/README.rdoc
index f3e12aab..11154a97 100644
--- a/README.rdoc
+++ b/README.rdoc
@@ -209,10 +209,82 @@ Note that the public directory name is not included in the URL. A file
== Views / Templates
+Each template language is exposed as via its own rendering method. These
+methods simply return a string:
+
+ get '/' do
+ erb :index
+ end
+
+This renders views/index.erb.
+
+Instead of a template name, you can also just pass in the template content
+directly:
+
+ get '/' do
+ code = "<%= Time.now >"
+ erb code
+ end
+
+Templates take a second argument, the options hash:
+
+ get '/' do
+ erb :index, :layout => :post
+ end
+
+This will render views/index.erb embedded in the
+views/post.erb (default is views/layout.erb, if it exists).
+
+Any options not understood by Sinatra will be passed on to the template
+engine:
+
+ get '/' do
+ haml :index, :format => :html5
+ end
+
+You can also set options per template language in general:
+
+ set :haml, :format => :html5
+
+ get '/' do
+ haml :index
+ end
+
+Options passed to the render method override options set via +set+.
+
+Available Options:
+
+[locals]
+ List of locals passed to the document. Handy with partials.
+ Example: erb "<%= foo %>", :locals => {:foo => "bar"}
+
+[default_encoding]
+ String encoding to use if uncertain. Defaults to
+ settings.default_encoding.
+
+[views]
+ Views folder to load templates from. Defaults to settings.views.
+
+[layout]
+ Whether to use a layout (+true+ or +false+), if it's a Symbol, specifies
+ what template to use. Example: erb :index, :layout => request.xhr?
+
+[content_type]
+ Content-Type the template produces, default depends on template language.
+
+[scope]
+ Scope to render template under. Defaults to the application instance. If you
+ change this, instance variables and helper methods will not be available.
+
+[layout_engine]
+ Template engine to use for rendering the layout. Useful for languages that
+ do not support layouts otherwise. Defaults to the engine used for the
+ temple. Example: set :rdoc, :layout_engine => :erb
+
Templates are assumed to be located directly under the ./views
directory. To use a different views directory:
- set :views, File.dirname(__FILE__) + '/templates'
+ set :views, settings.root + '/templates'
One important thing to remember is that you always have to reference
templates with symbols, even if they're in a subdirectory (in this
@@ -220,160 +292,84 @@ case, use :'subdir/template'). You must use a symbol because
otherwise rendering methods will render any strings passed to them
directly.
+=== Available Template Languages
+
+Some languages have multiple implementations. To specify what implementation
+to use (and to be thread-safe), you should simply require it first:
+
+ require 'rdiscount' # or require 'bluecloth'
+ get('/') { markdown :index }
+
=== Haml Templates
-The haml gem/library is required to render HAML templates:
-
- # You'll need to require haml in your app
- require 'haml'
-
- get '/' do
- haml :index
- end
-
-Renders ./views/index.haml.
-
-{Haml's options}[http://haml-lang.com/docs/yardoc/file.HAML_REFERENCE.html#options]
-can be set globally through Sinatra's configurations,
-see {Options and Configurations}[http://www.sinatrarb.com/configuration.html],
-and overridden on an individual basis.
-
- set :haml, :format => :html5 # default Haml format is :xhtml
-
- get '/' do
- haml :index, :format => :html4 # overridden
- end
-
+Dependency:: {haml}[http://haml-lang.com/]
+File Extensions:: .haml
+Example:: haml :index, :format => :html5
=== Erb Templates
- # You'll need to require erb in your app
- require 'erb'
-
- get '/' do
- erb :index
- end
-
-Renders ./views/index.erb.
+Dependency:: {erubis}[http://www.kuwata-lab.com/erubis/] or
+ erb (included in Ruby)
+File Extensions:: .erb, .rhtml or .erubis (Erubis
+ only)
+Example:: erb :index
=== Builder Templates
-The builder gem/library is required to render builder templates:
+Dependency:: {builder}[http://builder.rubyforge.org/]
+File Extensions:: .builder
+Example:: builder { |xml| xml.em "hi" }
- # You'll need to require builder in your app
- require 'builder'
-
- get '/' do
- builder :index
- end
-
-Renders ./views/index.builder.
+It also takes a block for inline templates (see example).
=== Nokogiri Templates
-The nokogiri gem/library is required to render nokogiri templates:
+Dependency:: {nokogiri}[http://nokogiri.org/]
+File Extensions:: .nokogiri
+Example:: builder { |xml| xml.em "hi" }
- # You'll need to require nokogiri in your app
- require 'nokogiri'
-
- get '/' do
- nokogiri :index
- end
-
-Renders ./views/index.nokogiri.
+It also takes a block for inline templates (see example).
=== Sass Templates
-The haml or sass gem/library is required to render Sass templates:
+Dependency:: {sass}[http://sass-lang.com/]
+File Extensions:: .sass
+Example:: sass :stylesheet, :style => :expanded
- # You'll need to require haml or sass in your app
- require 'sass'
+Up until version 3.0, Sass is included in the +haml+ gem.
- get '/stylesheet.css' do
- sass :stylesheet
- end
+=== SCSS Templates
-Renders ./views/stylesheet.sass.
+Dependency:: {sass}[http://sass-lang.com/]
+File Extensions:: .scss
+Example:: scss :stylesheet, :style => :expanded
-{Sass's options}[http://sass-lang.com/docs/yardoc/file.SASS_REFERENCE.html#options]
-can be set globally through Sinatra's configurations,
-see {Options and Configurations}[http://www.sinatrarb.com/configuration.html],
-and overridden on an individual basis.
-
- set :sass, :style => :compact # default Sass style is :nested
-
- get '/stylesheet.css' do
- sass :stylesheet, :style => :expanded # overridden
- end
-
-=== Scss Templates
-
-The haml or sass gem/library is required to render Scss templates:
-
- # You'll need to require haml or sass in your app
- require 'sass'
-
- get '/stylesheet.css' do
- scss :stylesheet
- end
-
-Renders ./views/stylesheet.scss.
-
-{Scss's options}[http://sass-lang.com/docs/yardoc/file.SASS_REFERENCE.html#options]
-can be set globally through Sinatra's configurations,
-see {Options and Configurations}[http://www.sinatrarb.com/configuration.html],
-and overridden on an individual basis.
-
- set :scss, :style => :compact # default Scss style is :nested
-
- get '/stylesheet.css' do
- scss :stylesheet, :style => :expanded # overridden
- end
+Up until version 3.0, SCSS is included in the +haml+ gem.
=== Less Templates
-The less gem/library is required to render Less templates:
-
- # You'll need to require less in your app
- require 'less'
-
- get '/stylesheet.css' do
- less :stylesheet
- end
-
-Renders ./views/stylesheet.less.
+Dependency:: {less}[http://www.lesscss.org/]
+File Extensions:: .less
+Example:: less :stylesheet
=== Liquid Templates
-The liquid gem/library is required to render Liquid templates:
-
- # You'll need to require liquid in your app
- require 'liquid'
-
- get '/' do
- liquid :index
- end
-
-Renders ./views/index.liquid.
+Dependency:: {liquid}[http://www.liquidmarkup.org/]
+File Extensions:: .liquid
+Example:: liquid :index, :locals => { :key => 'value' }
Since you cannot call Ruby methods (except for +yield+) from a Liquid
-template, you almost always want to pass locals to it:
-
- liquid :index, :locals => { :key => 'value' }
+template, you almost always want to pass locals to it.
=== Markdown Templates
-The rdiscount gem/library is required to render Markdown templates:
-
- # You'll need to require rdiscount in your app
- require "rdiscount"
-
- get '/' do
- markdown :index
- end
-
-Renders ./views/index.markdown (+md+ and +mkd+ are also valid file
-extensions).
+Dependency:: {rdiscount}[https://github.com/rtomayko/rdiscount],
+ {redcarpet}[https://github.com/tanoku/redcarpet],
+ {bluecloth}[http://deveiate.org/projects/BlueCloth],
+ {kramdown}[http://kramdown.rubyforge.org/] *or*
+ {maruku}[http://maruku.rubyforge.org/]
+File Extensions:: .markdown, .mkd and .md
+Example:: markdown :index, :layout_engine => :erb
It is not possible to call methods from markdown, nor to pass locals to it.
You therefore will usually use it in combination with another rendering
@@ -388,52 +384,13 @@ Note that you may also call the +markdown+ method from within other templates:
Since you cannot call Ruby from Markdown, you cannot use layouts written in
Markdown. However, it is possible to use another rendering engine for the
-template than for the layout by passing the :layout_engine option:
-
- get '/' do
- markdown :index, :layout_engine => :erb
- end
-
-This will render ./views/index.md with ./views/layout.erb as
-layout.
-
-Remember that you can set such rendering options globally:
-
- set :markdown, :layout_engine => :haml, :layout => :post
-
- get '/' do
- markdown :index
- end
-
-This will render ./views/index.md (and any other Markdown template)
-with ./views/post.haml as layout.
-
-It is also possible to parse Markdown with BlueCloth rather than RDiscount:
-
- require 'bluecloth'
-
- Tilt.register 'markdown', BlueClothTemplate
- Tilt.register 'mkd', BlueClothTemplate
- Tilt.register 'md', BlueClothTemplate
-
- get '/' do
- markdown :index
- end
-
-Renders ./views/index.md with BlueCloth.
+template than for the layout by passing the :layout_engine option.
=== Textile Templates
-The RedCloth gem/library is required to render Textile templates:
-
- # You'll need to require redcloth in your app
- require "redcloth"
-
- get '/' do
- textile :index
- end
-
-Renders ./views/index.textile.
+Dependency:: {RedCloth}[http://redcloth.org/]
+File Extensions:: .textile
+Example:: textile :index, :layout_engine => :erb
It is not possible to call methods from textile, nor to pass locals to it. You
therefore will usually use it in combination with another rendering engine:
@@ -447,38 +404,13 @@ Note that you may also call the +textile+ method from within other templates:
Since you cannot call Ruby from Textile, you cannot use layouts written in
Textile. However, it is possible to use another rendering engine for the
-template than for the layout by passing the :layout_engine option:
-
- get '/' do
- textile :index, :layout_engine => :erb
- end
-
-This will render ./views/index.textile with
-./views/layout.erb as layout.
-
-Remember that you can set such rendering options globally:
-
- set :textile, :layout_engine => :haml, :layout => :post
-
- get '/' do
- textile :index
- end
-
-This will render ./views/index.textile (and any other Textile
-template) with ./views/post.haml as layout.
+template than for the layout by passing the :layout_engine option.
=== RDoc Templates
-The rdoc gem/library is required to render RDoc templates:
-
- # You'll need to require rdoc/markup/to_html in your app
- require "rdoc/markup/to_html"
-
- get '/' do
- rdoc :index
- end
-
-Renders ./views/index.rdoc.
+Dependency:: {rdoc}[http://rdoc.rubyforge.org/]
+File Extensions:: .rdoc
+Example:: textile :README, :layout_engine => :erb
It is not possible to call methods from rdoc, nor to pass locals to it. You
therefore will usually use it in combination with another rendering engine:
@@ -492,110 +424,57 @@ Note that you may also call the +rdoc+ method from within other templates:
Since you cannot call Ruby from RDoc, you cannot use layouts written in
RDoc. However, it is possible to use another rendering engine for the
-template than for the layout by passing the :layout_engine option:
-
- get '/' do
- rdoc :index, :layout_engine => :erb
- end
-
-This will render ./views/index.rdoc with ./views/layout.erb as
-layout.
-
-Remember that you can set such rendering options globally:
-
- set :rdoc, :layout_engine => :haml, :layout => :post
-
- get '/' do
- rdoc :index
- end
-
-This will render ./views/index.rdoc (and any other RDoc template)
-with ./views/post.haml as layout.
+template than for the layout by passing the :layout_engine option.
=== Radius Templates
-The radius gem/library is required to render Radius templates:
+Dependency:: {radius}[http://radius.rubyforge.org/]
+File Extensions:: .radius
+Example:: radius :index, :locals => { :key => 'value' }
- # You'll need to require radius in your app
- require 'radius'
-
- get '/' do
- radius :index
- end
-
-Renders ./views/index.radius.
-
-Since you cannot call Ruby methods (except for +yield+) from a Radius
-template, you almost always want to pass locals to it:
-
- radius :index, :locals => { :key => 'value' }
+Since you cannot call Ruby methods directly from a Radius template, you almost
+always want to pass locals to it.
=== Markaby Templates
-The markaby gem/library is required to render Markaby templates:
+Dependency:: {markaby}[http://markaby.github.com/]
+File Extensions:: .mab
+Example:: markaby { h1 "Welcome!" }
- # You'll need to require markaby in your app
- require 'markaby'
-
- get '/' do
- markaby :index
- end
-
-Renders ./views/index.mab.
-
-You may also use inline Markaby:
-
- get '/' do
- markaby { h1 "Welcome!" }
- end
+It also takes a block for inline templates (see example).
=== Slim Templates
-The slim gem/library is required to render Slim templates:
-
- # You'll need to require slim in your app
- require 'slim'
-
- get '/' do
- slim :index
- end
-
-Renders ./views/index.slim.
+Dependency:: {slim}[http://slim-lang.com/]
+File Extensions:: .slim
+Example:: slim :index
=== Creole Templates
-The creole gem/library is required to render Creole templates:
+Dependency:: {creole}[https://github.com/minad/creole]
+File Extensions:: .creole
+Example:: creole :wiki, :layout_engine => :erb
- # You'll need to require creole in your app
- require 'creole'
+It is not possible to call methods from creole, nor to pass locals to it. You
+therefore will usually use it in combination with another rendering engine:
- get '/' do
- creole :index
- end
+ erb :overview, :locals => { :text => creole(:introduction) }
-Renders ./views/index.creole.
+Note that you may also call the +creole+ method from within other templates:
+
+ %h1 Hello From Haml!
+ %p= creole(:greetings)
+
+Since you cannot call Ruby from Creole, you cannot use layouts written in
+Creole. However, it is possible to use another rendering engine for the
+template than for the layout by passing the :layout_engine option.
=== CoffeeScript Templates
-The coffee-script gem/library and at least one of the
-following options to execute JavaScript:
-
-* +node+ (from Node.js) in your path
-* you must be running on OSX
-* +therubyracer+ gem/library
-
-See http://github.com/josh/ruby-coffee-script for an updated list of options.
-
-Now you can render CoffeeScript templates:
-
- # You'll need to require coffee-script in your app
- require 'coffee-script'
-
- get '/application.js' do
- coffee :application
- end
-
-Renders ./views/application.coffee.
+Dependency:: {coffee-script}[https://github.com/josh/ruby-coffee-script]
+ and a {way to execute javascript}[https://github.com/sstephenson/execjs/blob/master/README.md#readme]
+File Extensions:: .coffee
+Example:: coffee :index
=== Embedded Templates