From 0f0fa46e392fc74bcebcf998558c1e9c30d301b7 Mon Sep 17 00:00:00 2001 From: Konstantin Haase Date: Sun, 17 Apr 2011 16:23:41 +0200 Subject: [PATCH] DRY-up the README --- README.rdoc | 439 +++++++++++++++++++--------------------------------- 1 file changed, 159 insertions(+), 280 deletions(-) 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