sinatra 1.1.2 → 1.1.3

data/README.rdoc

@@ -119,7 +119,7 @@ You can easily define your own conditions:
     "Sorry, you lost."
   end
 
-=== Return values
+=== Return Values
 
 The return value of a route block determines at least the response body passed
 on to the HTTP client, or at least the next middleware in the Rack stack.
@@ -170,7 +170,7 @@ directly.
 
 === Haml Templates
 
-The haml gem/library is required to render HAML templates:
+The <tt>haml</tt> gem/library is required to render HAML templates:
 
   ## You'll need to require haml in your app
   require 'haml'
@@ -202,11 +202,11 @@ and overridden on an individual basis.
     erb :index
   end
 
-Renders <tt>./views/index.erb</tt>
+Renders <tt>./views/index.erb</tt>.
 
-=== Erubis
+=== Erubis Templates
 
-The erubis gem/library is required to render erubis templates:
+The <tt>erubis</tt> gem/library is required to render Erubis templates:
 
   ## You'll need to require erubis in your app
   require 'erubis'
@@ -215,11 +215,22 @@ The erubis gem/library is required to render erubis templates:
     erubis :index
   end
 
-Renders <tt>./views/index.erubis</tt>
+Renders <tt>./views/index.erubis</tt>.
+
+It is also possible to replace Erb with Erubis:
+
+  require 'erubis'
+  Tilt.register :erb, Tilt[:erubis]
+  
+  get '/' do
+    erb :index
+  end
+
+Renders <tt>./views/index.erb</tt> with Erubis.
 
 === Builder Templates
 
-The builder gem/library is required to render builder templates:
+The <tt>builder</tt> gem/library is required to render builder templates:
 
   ## You'll need to require builder in your app
   require 'builder'
@@ -232,7 +243,7 @@ Renders <tt>./views/index.builder</tt>.
 
 === Nokogiri Templates
 
-The nokogiri gem/library is required to render nokogiri templates:
+The <tt>nokogiri</tt> gem/library is required to render nokogiri templates:
 
   ## You'll need to require nokogiri in your app
   require 'nokogiri'
@@ -245,7 +256,7 @@ Renders <tt>./views/index.nokogiri</tt>.
 
 === Sass Templates
 
-The haml gem/library is required to render Sass templates:
+The <tt>haml</tt> or <tt>sass</tt> gem/library is required to render Sass templates:
 
   ## You'll need to require haml or sass in your app
   require 'sass'
@@ -269,7 +280,7 @@ and overridden on an individual basis.
 
 === Scss Templates
 
-The haml gem/library is required to render Scss templates:
+The <tt>haml</tt> or <tt>sass</tt> gem/library is required to render Scss templates:
 
   ## You'll need to require haml or sass in your app
   require 'sass'
@@ -293,7 +304,7 @@ and overridden on an individual basis.
 
 === Less Templates
 
-The less gem/library is required to render Less templates:
+The <tt>less</tt> gem/library is required to render Less templates:
 
   ## You'll need to require less in your app
   require 'less'
@@ -306,7 +317,7 @@ Renders <tt>./views/stylesheet.less</tt>.
 
 === Liquid Templates
 
-The liquid gem/library is required to render Liquid templates:
+The <tt>liquid</tt> gem/library is required to render Liquid templates:
 
   ## You'll need to require liquid in your app
   require 'liquid'
@@ -324,7 +335,7 @@ template, you almost always want to pass locals to it:
 
 === Markdown Templates
 
-The rdiscount gem/library is required to render Markdown templates:
+The <tt>rdiscount</tt> gem/library is required to render Markdown templates:
 
   ## You'll need to require rdiscount in your app
   require "rdiscount"
@@ -336,18 +347,34 @@ The rdiscount gem/library is required to render Markdown templates:
 Renders <tt>./views/index.markdown</tt> (+md+ and +mkd+ are also valid file
 extensions).
 
-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 engine:
+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
+engine:
 
   erb :overview, :locals => { :text => markdown(:introduction) }
 
-Note that you may also call the markdown method from within other templates:
+Note that you may also call the +markdown+ method from within other templates:
 
   %h1 Hello From Haml!
   %p= markdown(:greetings)
 
+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 <tt>./views/index.md</tt> with BlueCloth.
+
 === Textile Templates
 
-The RedCloth gem/library is required to render Textile templates:
+The <tt>RedCloth</tt> gem/library is required to render Textile templates:
 
   ## You'll need to require redcloth in your app
   require "redcloth"
@@ -358,18 +385,19 @@ The RedCloth gem/library is required to render Textile templates:
 
 Renders <tt>./views/index.textile</tt>.
 
-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:
+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:
 
   erb :overview, :locals => { :text => textile(:introduction) }
 
-Note that you may also call the textile method from within other templates:
+Note that you may also call the +textile+ method from within other templates:
 
   %h1 Hello From Haml!
   %p= textile(:greetings)
 
 === RDoc Templates
 
-The RDoc gem/library is required to render RDoc templates:
+The <tt>rdoc</tt> gem/library is required to render RDoc templates:
 
   ## You'll need to require rdoc in your app
   require "rdoc"
@@ -380,18 +408,19 @@ The RDoc gem/library is required to render RDoc templates:
 
 Renders <tt>./views/index.rdoc</tt>.
 
-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:
+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:
 
   erb :overview, :locals => { :text => rdoc(:introduction) }
 
-Note that you may also call the rdoc method from within other templates:
+Note that you may also call the +rdoc+ method from within other templates:
 
   %h1 Hello From Haml!
   %p= rdoc(:greetings)
 
 === Radius Templates
 
-The radius gem/library is required to render Radius templates:
+The <tt>radius</tt> gem/library is required to render Radius templates:
 
   ## You'll need to require radius in your app
   require 'radius'
@@ -409,7 +438,7 @@ template, you almost always want to pass locals to it:
 
 === Markaby Templates
 
-The markaby gem/library is required to render Markaby templates:
+The <tt>markaby</tt> gem/library is required to render Markaby templates:
 
   ## You'll need to require markaby in your app
   require 'markaby'
@@ -422,8 +451,16 @@ Renders <tt>./views/index.mab</tt>.
 
 === CoffeeScript Templates
 
-The coffee-script gem/library and the `coffee` binary are required to render
-CoffeeScript templates:
+The <tt>coffee-script</tt> gem/library and at least <b>one</b> 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'
@@ -434,13 +471,13 @@ CoffeeScript templates:
 
 Renders <tt>./views/application.coffee</tt>.
 
-=== Inline Templates
+=== Embedded Templates
 
   get '/' do
     haml '%div.title Hello World'
   end
 
-Renders the inlined template string.
+Renders the embedded template string.
 
 === Accessing Variables in Templates
 
@@ -502,12 +539,38 @@ Templates may also be defined using the top-level <tt>template</tt> method:
   end
 
 If a template named "layout" exists, it will be used each time a template
-is rendered. You can disable layouts by passing <tt>:layout => false</tt>.
+is rendered. You can individually disable layouts by passing <tt>:layout => false</tt>
+or disable them by default via <tt>set :haml, :layout => false</tt>.
 
   get '/' do
     haml :index, :layout => !request.xhr?
   end
 
+=== Associating File Extensions
+
+To associate a file extension with a template engine, use
+<tt>Tilt.register</tt>. For instance, if you like to use the file extension
++tt+ for Textile templates, you can do the following:
+
+  Tilt.register :tt, Tilt[:textile]
+
+=== Adding You Own Template Engine
+
+First, register your engine with Tilt, then create a rendering method:
+
+  Tilt.register :myat, MyAwesomeTemplateEngine
+
+  helpers do
+    def myat(*args) render(:myat, *args) end
+  end
+
+  get '/' do
+    myat :index
+  end
+
+Renders <tt>./views/index.myat</tt>. See https://github.com/rtomayko/tilt to
+learn more about Tilt.
+
 == Helpers
 
 Use the top-level <tt>helpers</tt> method to define helper methods for use in
@@ -547,6 +610,10 @@ and routes are accessible by after filters:
     puts response.status
   end
 
+Note: Unless you use the `body` method rather than just returning a String from
+the routes, the body will not yet be available in the after filter, since it is
+generated later on.
+
 Filters optionally taking a pattern, causing them to be evaluated only if the
 request path matches that pattern:
 
@@ -648,7 +715,20 @@ The <tt>request.body</tt> is an IO or StringIO object:
 Run once, at startup, in any environment:
 
   configure do
-    ...
+    # setting one option
+    set :option, 'value'
+    
+    # setting multiple options
+    set :a => 1, :b => 2
+    
+    # same as `set :option, true`
+    enable :option
+    
+    # same as `set :option, false`
+    disable :option
+    
+    # you can also have dynamic settings with blocks
+    set(:css_dir) { File.join(views, 'css') }
   end
 
 Run only when the environment (RACK_ENV environment variable) is set to
@@ -665,7 +745,19 @@ Run when the environment is set to either <tt>:production</tt> or
     ...
   end
 
-== Error handling
+You can access those options via <tt>settings</tt>:
+
+  configure do
+    set :foo, 'bar'
+  end
+
+  get '/' do
+    settings.foo? # => true
+    settings.foo  # => 'bar'
+    ...
+  end
+
+== Error Handling
 
 Error handlers run within the same context as routes and before filters, which
 means you get all the goodies it has to offer, like <tt>haml</tt>,
@@ -725,7 +817,7 @@ Or a range:
 Sinatra installs special <tt>not_found</tt> and <tt>error</tt> handlers when
 running under the development environment.
 
-== Mime types
+== Mime Types
 
 When using <tt>send_file</tt> or static files you may have mime types Sinatra
 doesn't understand. Use +mime_type+ to register them by file extension:
@@ -828,13 +920,6 @@ etc.). That's where Sinatra::Base comes into play:
     end
   end
 
-The MyApp class is an independent Rack component that can act as
-Rack middleware, a Rack application, or Rails metal. You can +use+ or
-+run+ this class from a rackup +config.ru+ file; or, control a server
-component shipped as a library:
-
-   MyApp.run! :host => 'localhost', :port => 9090
-
 The methods available to Sinatra::Base subclasses are exactly as those
 available via the top-level DSL. Most top-level apps can be converted to
 Sinatra::Base components with two modifications:
@@ -849,6 +934,91 @@ Sinatra::Base components with two modifications:
 including the built-in server. See {Options and Configuration}[http://sinatra.github.com/configuration.html]
 for details on available options and their behavior.
 
+=== Modular vs. Classic Style
+
+Contrary to common believes, there is nothing wrong with classic style. If it
+suits your application, you do not have to switch to a modular application.
+
+There are only two downsides compared to modulare style:
+
+* You may only have one Sinatra application per Ruby process - if you plan to
+  use more, switch to modular style.
+
+* Classic style pollutes Object with delegator methods - if you plan to ship
+  your application in a library/gem, switch to modular style.
+
+There is no reason you cannot mix modular and classic style.
+
+If switching from one style to the other, you should be aware of slight
+differences in the setting:
+
+  Setting             Classic                 Modular
+
+  app_file            file loading sinatra    nil
+  run                 $0 == app_file          false
+  logging             true                    false
+  method_override     true                    false
+  inline_templates    true                    false
+
+
+=== Serving a Modular Application
+
+There are two common options for starting a modular app, activly starting with
+<tt>run!</tt>:
+
+  # my_app.rb
+  require 'sinatra/base'
+  
+  class MyApp < Sinatra::Base
+    # ... app code here ...
+    
+    # start the server if ruby file executed directly
+    run! if app_file == $0
+  end
+
+Start with:
+
+  ruby my_app.rb
+
+Or with a <tt>config.ru</tt>, which allows using any Rack handler:
+
+  # config.ru
+  require 'my_app'
+  run MyApp
+
+Run:
+
+  rackup -p 4567
+
+=== Using a Classic Style Application with a config.ru
+
+Write your app file:
+
+  # app.rb
+  require 'sinatra'
+  
+  get '/' do
+    'Hello world!'
+  end
+
+And a corresponding <tt>config.ru</tt>:
+
+  require 'app'
+  run Sinatra::Application
+
+=== When to use a config.ru?
+
+Good signs you probably want to use a <tt>config.ru</tt>:
+
+* You want to deploy with a different Rack handler (Passenger, Unicorn,
+  Heroku, ...).
+* You want to use more than one subclass of <tt>Sinatra::Base</tt>.
+* You want to use Sinatra only for middleware, but not as endpoint.
+
+<b>There is no need to switch to a <tt>config.ru</tt> only because you
+switched to modular style, and you don't have to use modular style for running
+with a <tt>config.ru</tt>.</b>
+
 === Using Sinatra as Middleware
 
 Not only is Sinatra able to use other Rack middleware, any Sinatra application
@@ -971,7 +1141,7 @@ Have a look at the code for yourself: here's the
 {Sinatra::Delegator mixin}[http://github.com/sinatra/sinatra/blob/ceac46f0bc129a6e994a06100aa854f606fe5992/lib/sinatra/base.rb#L1128]
 being {included into the main namespace}[http://github.com/sinatra/sinatra/blob/ceac46f0bc129a6e994a06100aa854f606fe5992/lib/sinatra/main.rb#L28].
 
-== Command line
+== Command Line
 
 Sinatra applications can be run directly:
 
@@ -987,32 +1157,67 @@ Options are:
   -x # turn on the mutex lock (default is off)
 
 == The Bleeding Edge
+If you would like to use Sinatra's latest bleeding code, feel free to run your
+application against the master branch, it should be rather stable.
+
+We also push out prerelease gems from time to time, so you can do a
 
-If you would like to use Sinatra's latest bleeding code, create a local
-clone and run your app with the <tt>sinatra/lib</tt> directory on the
-<tt>LOAD_PATH</tt>:
+  gem install sinatra --pre
+
+To get some of the latest features.
+
+=== With Bundler
+If you want to run your application with the latest Sinatra, using
+{Bundler}[http://gembundler.com/] is the recommend way.
+
+First, install bundler, if you haven't:
+
+  gem install bundler
+
+Then, in you project directory, create a +Gemfile+:
+
+  source :rubygems
+  gem 'sinatra', :git => "git://github.com/sinatra/sinatra.git"
+  
+  # other dependencies
+  gem 'haml'                    # for instance, if you use haml
+  gem 'activerecord', '~> 3.0'  # maybe you also need ActiveRecord 3.x
+
+Note that you will have to list all your applications dependencies in there.
+Sinatra's direct dependencies (Rack and Tilt) will however be automatically
+fetched and added by Bundler.
+
+Now you can run your app like this:
+
+  bundle exec ruby myapp.rb
+
+=== Roll Your Own
+Create a local clone and run your app with the <tt>sinatra/lib</tt> directory
+on the <tt>LOAD_PATH</tt>:
 
   cd myapp
   git clone git://github.com/sinatra/sinatra.git
   ruby -Isinatra/lib myapp.rb
 
-Alternatively, you can add the <tt>sinatra/lib</tt> directory to the
-<tt>LOAD_PATH</tt> in your application:
+To update the Sinatra sources in the future:
 
-  $LOAD_PATH.unshift File.dirname(__FILE__) + '/sinatra/lib'
-  require 'rubygems'
-  require 'sinatra'
+  cd myapp/sinatra
+  git pull
 
-  get '/about' do
-    "I'm running version " + Sinatra::VERSION
-  end
+=== Install Globally
 
-To update the Sinatra sources in the future:
+You can build the gem on your own:
 
-  cd myproject/sinatra
-  git pull
+  git clone git://github.com/sinatra/sinatra.git
+  cd sinatra
+  rake sinatra.gemspec
+  rake install
+
+If you install gems as root, the last step should be
+
+  sudo rake install
 
-== More
+== Further Reading
 
 * {Project Website}[http://www.sinatrarb.com/] - Additional documentation,
   news, and links to other resources.