mirror of
https://github.com/sinatra/sinatra
synced 2023-03-27 23:18:01 -04:00
1802 lines
47 KiB
Text
1802 lines
47 KiB
Text
= Sinatra
|
|
|
|
Sinatra is a DSL for quickly creating web applications in Ruby with minimal
|
|
effort:
|
|
|
|
# myapp.rb
|
|
require 'sinatra'
|
|
|
|
get '/' do
|
|
'Hello world!'
|
|
end
|
|
|
|
Install the gem and run with:
|
|
|
|
gem install sinatra
|
|
ruby -rubygems myapp.rb
|
|
|
|
View at: http://localhost:4567
|
|
|
|
It is recommended to also run <tt>gem install thin</tt>, which Sinatra will
|
|
pick up if available.
|
|
|
|
== Routes
|
|
|
|
In Sinatra, a route is an HTTP method paired with a URL-matching pattern.
|
|
Each route is associated with a block:
|
|
|
|
get '/' do
|
|
.. show something ..
|
|
end
|
|
|
|
post '/' do
|
|
.. create something ..
|
|
end
|
|
|
|
put '/' do
|
|
.. update something ..
|
|
end
|
|
|
|
delete '/' do
|
|
.. annihilate something ..
|
|
end
|
|
|
|
options '/' do
|
|
.. appease something ..
|
|
end
|
|
|
|
Routes are matched in the order they are defined. The first route that
|
|
matches the request is invoked.
|
|
|
|
Route patterns may include named parameters, accessible via the
|
|
<tt>params</tt> hash:
|
|
|
|
get '/hello/:name' do
|
|
# matches "GET /hello/foo" and "GET /hello/bar"
|
|
# params[:name] is 'foo' or 'bar'
|
|
"Hello #{params[:name]}!"
|
|
end
|
|
|
|
You can also access named parameters via block parameters:
|
|
|
|
get '/hello/:name' do |n|
|
|
"Hello #{n}!"
|
|
end
|
|
|
|
Route patterns may also include splat (or wildcard) parameters, accessible
|
|
via the <tt>params[:splat]</tt> array.
|
|
|
|
get '/say/*/to/*' do
|
|
# matches /say/hello/to/world
|
|
params[:splat] # => ["hello", "world"]
|
|
end
|
|
|
|
get '/download/*.*' do
|
|
# matches /download/path/to/file.xml
|
|
params[:splat] # => ["path/to/file", "xml"]
|
|
end
|
|
|
|
Route matching with Regular Expressions:
|
|
|
|
get %r{/hello/([\w]+)} do
|
|
"Hello, #{params[:captures].first}!"
|
|
end
|
|
|
|
Or with a block parameter:
|
|
|
|
get %r{/hello/([\w]+)} do |c|
|
|
"Hello, #{c}!"
|
|
end
|
|
|
|
=== Conditions
|
|
|
|
Routes may include a variety of matching conditions, such as the user agent:
|
|
|
|
get '/foo', :agent => /Songbird (\d\.\d)[\d\/]*?/ do
|
|
"You're using Songbird version #{params[:agent][0]}"
|
|
end
|
|
|
|
get '/foo' do
|
|
# Matches non-songbird browsers
|
|
end
|
|
|
|
Other available conditions are +host_name+ and +provides+:
|
|
|
|
get '/', :host_name => /^admin\./ do
|
|
"Admin Area, Access denied!"
|
|
end
|
|
|
|
get '/', :provides => 'html' do
|
|
haml :index
|
|
end
|
|
|
|
get '/', :provides => ['rss', 'atom', 'xml'] do
|
|
builder :feed
|
|
end
|
|
|
|
You can easily define your own conditions:
|
|
|
|
set(:probability) { |value| condition { rand <= value } }
|
|
|
|
get '/win_a_car', :probability => 0.1 do
|
|
"You won!"
|
|
end
|
|
|
|
get '/win_a_car' do
|
|
"Sorry, you lost."
|
|
end
|
|
|
|
=== 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.
|
|
Most commonly, this is a string, as in the above examples. But other values are
|
|
also accepted.
|
|
|
|
You can return any object that would either be a valid Rack response, Rack
|
|
body object or HTTP status code:
|
|
|
|
* An Array with three elements: <tt>[status (Fixnum), headers (Hash), response body (responds to #each)]</tt>
|
|
* An Array with two elements: <tt>[status (Fixnum), response body (responds to #each)]</tt>
|
|
* An object that responds to <tt>#each</tt> and passes nothing but strings to the given block
|
|
* A Fixnum representing the status code
|
|
|
|
That way we can, for instance, easily implement a streaming example:
|
|
|
|
class Stream
|
|
def each
|
|
100.times { |i| yield "#{i}\n" }
|
|
end
|
|
end
|
|
|
|
get('/') { Stream.new }
|
|
|
|
=== Custom Route Matchers
|
|
|
|
As shown above, Sinatra ships with built-in support for using String patterns
|
|
and regular expressions as route matches. However, it does not stop there. You
|
|
can easily define your own matchers:
|
|
|
|
class AllButPattern
|
|
Match = Struct.new(:captures)
|
|
|
|
def initialize(except)
|
|
@except = except
|
|
@caputres = Match.new([])
|
|
end
|
|
|
|
def match(str)
|
|
@caputres unless @except === str
|
|
end
|
|
end
|
|
|
|
def all_but(pattern)
|
|
AllButPattern.new(pattern)
|
|
end
|
|
|
|
get all_but("/index") do
|
|
# ...
|
|
end
|
|
|
|
Note that the above example might be over-engineered, as it can also be
|
|
expressed as:
|
|
|
|
get // do
|
|
pass if request.path_info == "/index"
|
|
# ...
|
|
end
|
|
|
|
Or, using negative look ahead:
|
|
|
|
get %r{^(?!/index$)} do
|
|
# ...
|
|
end
|
|
|
|
== Static Files
|
|
|
|
Static files are served from the <tt>./public</tt> directory. You can specify
|
|
a different location by setting the <tt>:public</tt> option:
|
|
|
|
set :public, File.dirname(__FILE__) + '/static'
|
|
|
|
Note that the public directory name is not included in the URL. A file
|
|
<tt>./public/css/style.css</tt> is made available as
|
|
<tt>http://example.com/css/style.css</tt>.
|
|
|
|
== Views / Templates
|
|
|
|
Templates are assumed to be located directly under the <tt>./views</tt>
|
|
directory. To use a different views directory:
|
|
|
|
set :views, File.dirname(__FILE__) + '/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
|
|
case, use <tt>:'subdir/template'</tt>). You must use a symbol because
|
|
otherwise rendering methods will render any strings passed to them
|
|
directly.
|
|
|
|
=== 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'
|
|
|
|
get '/' do
|
|
haml :index
|
|
end
|
|
|
|
Renders <tt>./views/index.haml</tt>.
|
|
|
|
{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
|
|
|
|
|
|
=== Erb Templates
|
|
|
|
# You'll need to require erb in your app
|
|
require 'erb'
|
|
|
|
get '/' do
|
|
erb :index
|
|
end
|
|
|
|
Renders <tt>./views/index.erb</tt>.
|
|
|
|
=== 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'
|
|
|
|
get '/' do
|
|
erubis :index
|
|
end
|
|
|
|
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 <tt>builder</tt> gem/library is required to render builder templates:
|
|
|
|
# You'll need to require builder in your app
|
|
require 'builder'
|
|
|
|
get '/' do
|
|
builder :index
|
|
end
|
|
|
|
Renders <tt>./views/index.builder</tt>.
|
|
|
|
=== 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'
|
|
|
|
get '/' do
|
|
nokogiri :index
|
|
end
|
|
|
|
Renders <tt>./views/index.nokogiri</tt>.
|
|
|
|
=== 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'
|
|
|
|
get '/stylesheet.css' do
|
|
sass :stylesheet
|
|
end
|
|
|
|
Renders <tt>./views/stylesheet.sass</tt>.
|
|
|
|
{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 <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'
|
|
|
|
get '/stylesheet.css' do
|
|
scss :stylesheet
|
|
end
|
|
|
|
Renders <tt>./views/stylesheet.scss</tt>.
|
|
|
|
{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
|
|
|
|
=== 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'
|
|
|
|
get '/stylesheet.css' do
|
|
less :stylesheet
|
|
end
|
|
|
|
Renders <tt>./views/stylesheet.less</tt>.
|
|
|
|
=== 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'
|
|
|
|
get '/' do
|
|
liquid :index
|
|
end
|
|
|
|
Renders <tt>./views/index.liquid</tt>.
|
|
|
|
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' }
|
|
|
|
=== 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"
|
|
|
|
get '/' do
|
|
markdown :index
|
|
end
|
|
|
|
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:
|
|
|
|
erb :overview, :locals => { :text => markdown(:introduction) }
|
|
|
|
Note that you may also call the +markdown+ method from within other templates:
|
|
|
|
%h1 Hello From Haml!
|
|
%p= markdown(:greetings)
|
|
|
|
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 <tt>:layout_engine</tt> option:
|
|
|
|
get '/' do
|
|
markdown :index, :layout_engine => :erb
|
|
end
|
|
|
|
This will render <tt>./views/index.md</tt> with <tt>./views/layout.erb</tt> 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 <tt>./views/index.md</tt> (and any other Markdown template)
|
|
with <tt>./views/post.haml</tt> 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 <tt>./views/index.md</tt> with BlueCloth.
|
|
|
|
=== 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"
|
|
|
|
get '/' do
|
|
textile :index
|
|
end
|
|
|
|
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:
|
|
|
|
erb :overview, :locals => { :text => textile(:introduction) }
|
|
|
|
Note that you may also call the +textile+ method from within other templates:
|
|
|
|
%h1 Hello From Haml!
|
|
%p= textile(:greetings)
|
|
|
|
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 <tt>:layout_engine</tt> option:
|
|
|
|
get '/' do
|
|
textile :index, :layout_engine => :erb
|
|
end
|
|
|
|
This will render <tt>./views/index.textile</tt> with
|
|
<tt>./views/layout.erb</tt> 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 <tt>./views/index.textile</tt> (and any other Textile
|
|
template) with <tt>./views/post.haml</tt> as layout.
|
|
|
|
=== RDoc Templates
|
|
|
|
The <tt>rdoc</tt> 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 <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:
|
|
|
|
erb :overview, :locals => { :text => rdoc(:introduction) }
|
|
|
|
Note that you may also call the +rdoc+ method from within other templates:
|
|
|
|
%h1 Hello From Haml!
|
|
%p= rdoc(:greetings)
|
|
|
|
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 <tt>:layout_engine</tt> option:
|
|
|
|
get '/' do
|
|
rdoc :index, :layout_engine => :erb
|
|
end
|
|
|
|
This will render <tt>./views/index.rdoc</tt> with <tt>./views/layout.erb</tt> 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 <tt>./views/index.rdoc</tt> (and any other RDoc template)
|
|
with <tt>./views/post.haml</tt> as layout.
|
|
|
|
=== 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'
|
|
|
|
get '/' do
|
|
radius :index
|
|
end
|
|
|
|
Renders <tt>./views/index.radius</tt>.
|
|
|
|
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' }
|
|
|
|
=== 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'
|
|
|
|
get '/' do
|
|
markaby :index
|
|
end
|
|
|
|
Renders <tt>./views/index.mab</tt>.
|
|
|
|
You may also use inline Markaby:
|
|
|
|
get '/' do
|
|
markaby { h1 "Welcome!" }
|
|
end
|
|
|
|
=== Slim Templates
|
|
|
|
The <tt>slim</tt> 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 <tt>./views/index.slim</tt>.
|
|
|
|
=== 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'
|
|
|
|
get '/application.js' do
|
|
coffee :application
|
|
end
|
|
|
|
Renders <tt>./views/application.coffee</tt>.
|
|
|
|
=== Embedded Templates
|
|
|
|
get '/' do
|
|
haml '%div.title Hello World'
|
|
end
|
|
|
|
Renders the embedded template string.
|
|
|
|
=== Accessing Variables in Templates
|
|
|
|
Templates are evaluated within the same context as route handlers. Instance
|
|
variables set in route handlers are directly accessible by templates:
|
|
|
|
get '/:id' do
|
|
@foo = Foo.find(params[:id])
|
|
haml '%h1= @foo.name'
|
|
end
|
|
|
|
Or, specify an explicit Hash of local variables:
|
|
|
|
get '/:id' do
|
|
foo = Foo.find(params[:id])
|
|
haml '%h1= foo.name', :locals => { :foo => foo }
|
|
end
|
|
|
|
This is typically used when rendering templates as partials from within
|
|
other templates.
|
|
|
|
=== Inline Templates
|
|
|
|
Templates may be defined at the end of the source file:
|
|
|
|
require 'sinatra'
|
|
|
|
get '/' do
|
|
haml :index
|
|
end
|
|
|
|
__END__
|
|
|
|
@@ layout
|
|
%html
|
|
= yield
|
|
|
|
@@ index
|
|
%div.title Hello world!!!!!
|
|
|
|
NOTE: Inline templates defined in the source file that requires sinatra are
|
|
automatically loaded. Call <tt>enable :inline_templates</tt> explicitly if you
|
|
have inline templates in other source files.
|
|
|
|
=== Named Templates
|
|
|
|
Templates may also be defined using the top-level <tt>template</tt> method:
|
|
|
|
template :layout do
|
|
"%html\n =yield\n"
|
|
end
|
|
|
|
template :index do
|
|
'%div.title Hello World!'
|
|
end
|
|
|
|
get '/' do
|
|
haml :index
|
|
end
|
|
|
|
If a template named "layout" exists, it will be used each time a template
|
|
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 Your 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.
|
|
|
|
== Filters
|
|
|
|
Before filters are evaluated before each request within the same
|
|
context as the routes will be and can modify the request and response. Instance
|
|
variables set in filters are accessible by routes and templates:
|
|
|
|
before do
|
|
@note = 'Hi!'
|
|
request.path_info = '/foo/bar/baz'
|
|
end
|
|
|
|
get '/foo/*' do
|
|
@note #=> 'Hi!'
|
|
params[:splat] #=> 'bar/baz'
|
|
end
|
|
|
|
After filters are evaluated after each request within the same context and can
|
|
also modify the request and response. Instance variables set in before filters
|
|
and routes are accessible by after filters:
|
|
|
|
after do
|
|
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 take a pattern, causing them to be evaluated only if the
|
|
request path matches that pattern:
|
|
|
|
before '/protected/*' do
|
|
authenticate!
|
|
end
|
|
|
|
after '/create/:slug' do |slug|
|
|
session[:last_slug] = slug
|
|
end
|
|
|
|
Like routes, filters also take conditions:
|
|
|
|
before :agent => /Songbird/ do
|
|
# ...
|
|
end
|
|
|
|
after '/blog/*', :host_name => 'example.com' do
|
|
# ...
|
|
end
|
|
|
|
== Helpers
|
|
|
|
Use the top-level <tt>helpers</tt> method to define helper methods for use in
|
|
route handlers and templates:
|
|
|
|
helpers do
|
|
def bar(name)
|
|
"#{name}bar"
|
|
end
|
|
end
|
|
|
|
get '/:name' do
|
|
bar(params[:name])
|
|
end
|
|
|
|
=== Using Sessions
|
|
|
|
A session is used to keep state during requests. If activated, you have one
|
|
session hash per user session:
|
|
|
|
enable :sessions
|
|
|
|
get '/' do
|
|
"value = " << session[:value].inspect
|
|
end
|
|
|
|
get '/:value' do
|
|
session[:value] = params[:value]
|
|
end
|
|
|
|
Note that <tt>enable :sessions</tt> actually stores all data in a cookie. This
|
|
might not always be what you want (storing lots of data will increase your
|
|
traffic, for instance). You can use any Rack session middleware, in order to
|
|
do so, do *not* call <tt>enable :sessions</tt>, but instead pull in your
|
|
middleware of choice how you would any other middleware:
|
|
|
|
use Rack::Session::Pool, :expire_after => 2592000
|
|
|
|
get '/' do
|
|
"value = " << session[:value].inspect
|
|
end
|
|
|
|
get '/:value' do
|
|
session[:value] = params[:value]
|
|
end
|
|
|
|
=== Halting
|
|
|
|
To immediately stop a request within a filter or route use:
|
|
|
|
halt
|
|
|
|
You can also specify the status when halting:
|
|
|
|
halt 410
|
|
|
|
Or the body:
|
|
|
|
halt 'this will be the body'
|
|
|
|
Or both:
|
|
|
|
halt 401, 'go away!'
|
|
|
|
With headers:
|
|
|
|
halt 402, {'Content-Type' => 'text/plain'}, 'revenge'
|
|
|
|
It is of course possible to combine a template with +halt+:
|
|
|
|
halt erb(:error)
|
|
|
|
=== Passing
|
|
|
|
A route can punt processing to the next matching route using <tt>pass</tt>:
|
|
|
|
get '/guess/:who' do
|
|
pass unless params[:who] == 'Frank'
|
|
'You got me!'
|
|
end
|
|
|
|
get '/guess/*' do
|
|
'You missed!'
|
|
end
|
|
|
|
The route block is immediately exited and control continues with the next
|
|
matching route. If no matching route is found, a 404 is returned.
|
|
|
|
=== Triggering Another Route
|
|
|
|
Sometimes +pass+ is not what you want, instead you would like to get the result
|
|
of calling another route. Simply use +call+ to achieve this:
|
|
|
|
get '/foo' do
|
|
status, headers, body = call request.env.merge("PATH_INFO" => '/bar')
|
|
[status, body.upcase]
|
|
end
|
|
|
|
get '/bar' do
|
|
"bar"
|
|
end
|
|
|
|
Note that in the example above, you would ease testing and increase performance
|
|
by simply moving <tt>"bar"</tt> into a helper used by both <tt>/foo</tt>
|
|
and <tt>/bar</tt>.
|
|
|
|
If you want the request to be sent to the same application instance rather than
|
|
a duplicate, use <tt>call!</tt> instead of <tt>call</tt>.
|
|
|
|
Check out the Rack specification if you want to learn more about <tt>call</tt>.
|
|
|
|
=== Setting Body, Status Code and Headers
|
|
|
|
It is possible and recommended to set the status code and response body with the
|
|
return value of the route block. However, in some scenarios you might want to
|
|
set the body at an arbitrary point in the execution flow. You can do so with the
|
|
+body+ helper method. If you do so, you can use that method from there on to
|
|
access the body:
|
|
|
|
get '/foo' do
|
|
body "bar"
|
|
end
|
|
|
|
after do
|
|
puts body
|
|
end
|
|
|
|
It is also possible to pass a block to +body+, which will be executed by the Rack
|
|
handler (this can be used to implement streaming, see "Return Values").
|
|
|
|
Similar to the body, you can also set the status code and headers:
|
|
|
|
get '/foo' do
|
|
status 418
|
|
headers \
|
|
"Allow" => "BREW, POST, GET, PROPFIND, WHEN"
|
|
"Refresh" => "Refresh: 20; http://www.ietf.org/rfc/rfc2324.txt"
|
|
body "I'm a tea pot!"
|
|
end
|
|
|
|
Like +body+, +headers+ and +status+ with no arguments can be used to access
|
|
their current values.
|
|
|
|
=== 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:
|
|
|
|
mime_type :foo, 'text/foo'
|
|
|
|
You can also use it with the +content_type+ helper:
|
|
|
|
get '/' do
|
|
content_type :foo
|
|
"foo foo foo"
|
|
end
|
|
|
|
=== Generating URLs
|
|
|
|
For generating URLs you should use the +url+ helper method, for instance, in
|
|
Haml:
|
|
|
|
%a{:href => url('/foo')} foo
|
|
|
|
It takes reverse proxies and Rack routers into account, if present.
|
|
|
|
This method is also aliased to +to+ (see below for an example).
|
|
|
|
=== Browser Redirect
|
|
|
|
You can trigger a browser redirect with the +redirect+ helper method:
|
|
|
|
get '/foo' do
|
|
redirect to('/bar')
|
|
end
|
|
|
|
Any additional parameters are handled like arguments passed to +halt+:
|
|
|
|
redirect to('/bar'), 303
|
|
redirect 'http://google.com', 'wrong place, buddy'
|
|
|
|
You can also easily redirect back to the page the user came from with
|
|
<tt>redirect back</tt>:
|
|
|
|
get '/foo' do
|
|
"<a href='/bar'>do something</a>"
|
|
end
|
|
|
|
get '/bar' do
|
|
do_something
|
|
redirect back
|
|
end
|
|
|
|
To pass arguments with a redirect, either add them to the query:
|
|
|
|
redirect to('/bar?sum=42')
|
|
|
|
Or use a session:
|
|
|
|
enable :session
|
|
|
|
get '/foo' do
|
|
session[:secret] = 'foo'
|
|
redirect to('/bar')
|
|
end
|
|
|
|
get '/bar' do
|
|
session[:secret]
|
|
end
|
|
|
|
=== Cache Control
|
|
|
|
Setting your headers correctly is the foundation for proper HTTP caching.
|
|
|
|
You can easily set the Cache-Control header with like this:
|
|
|
|
get '/' do
|
|
cache_control :public
|
|
"cache it!"
|
|
end
|
|
|
|
Pro tip: Set up caching in a before filter.
|
|
|
|
before do
|
|
cache_control :public, :must_revalidate, :max_age => 60
|
|
end
|
|
|
|
If you are using the +expires+ helper to set the corresponding header,
|
|
<tt>Cache-Control</tt> will be set automatically for you:
|
|
|
|
before do
|
|
expires 500, :public, :must_revalidate
|
|
end
|
|
|
|
To properly use caches, you should consider using +etag+ and +last_modified+.
|
|
It is recommended to call those helpers *before* doing heavy lifting, as they
|
|
will immediately flush a response if the client already has the current
|
|
version in its cache.
|
|
|
|
get '/article/:id' do
|
|
@article = Article.find params[:id]
|
|
last_modified @article.updated_at
|
|
etag @article.sha1
|
|
erb :article
|
|
end
|
|
|
|
It is also possible to use a
|
|
{weak ETag}[http://en.wikipedia.org/wiki/HTTP_ETag#Strong_and_weak_validation]:
|
|
|
|
etag @article.sha1, :weak
|
|
|
|
These helpers will not do any caching for you, but rather feed the necessary
|
|
information to your cache. If you are looking for a quick caching solutions, try
|
|
{rack-cache}[http://rtomayko.github.com/rack-cache/]:
|
|
|
|
require "rack/cache"
|
|
require "sinatra"
|
|
|
|
use Rack::Cache
|
|
|
|
get '/' do
|
|
cache_control :public, :max_age => 36000
|
|
sleep 5
|
|
"hello"
|
|
end
|
|
|
|
=== Sending Files
|
|
|
|
For sending files, you can use the <tt>send_file</tt> helper method:
|
|
|
|
get '/' do
|
|
send_file 'foo.png'
|
|
end
|
|
|
|
It also takes a couple of options:
|
|
|
|
send_file 'foo.png', :type => :jpg
|
|
|
|
The options are:
|
|
|
|
[filename]
|
|
file name, in response, defaults to the real file name.
|
|
|
|
[last_modified]
|
|
value for Last-Modified header, defaults to the file's mtime.
|
|
|
|
[type]
|
|
content type to use, guessed from the file extension if missing.
|
|
|
|
[disposition]
|
|
used for Content-Disposition, possible values: +nil+ (default),
|
|
<tt>:attachment</tt> and <tt>:inline</tt>
|
|
|
|
[length]
|
|
Content-Length header, defaults to file size.
|
|
|
|
If supported by the Rack handler, other means than streaming from the Ruby
|
|
process will be used. If you use this helper method, Sinatra will automatically
|
|
handle range requests.
|
|
|
|
=== Accessing the Request Object
|
|
|
|
The incoming request object can be accessed from request level (filter, routes,
|
|
error handlers) through the <tt>request</tt> method:
|
|
|
|
# app running on http://example.com/example
|
|
get '/foo' do
|
|
request.body # request body sent by the client (see below)
|
|
request.scheme # "http"
|
|
request.script_name # "/example"
|
|
request.path_info # "/foo"
|
|
request.port # 80
|
|
request.request_method # "GET"
|
|
request.query_string # ""
|
|
request.content_length # length of request.body
|
|
request.media_type # media type of request.body
|
|
request.host # "example.com"
|
|
request.get? # true (similar methods for other verbs)
|
|
request.form_data? # false
|
|
request["SOME_HEADER"] # value of SOME_HEADER header
|
|
request.referrer # the referrer of the client or '/'
|
|
request.user_agent # user agent (used by :agent condition)
|
|
request.cookies # hash of browser cookies
|
|
request.xhr? # is this an ajax request?
|
|
request.url # "http://example.com/example/foo"
|
|
request.path # "/example/foo"
|
|
request.ip # client IP address
|
|
request.secure? # false (would be true over ssl)
|
|
request.forwarded? # true (if running behind a reverse proxy)
|
|
request.env # raw env hash handed in by Rack
|
|
end
|
|
|
|
Some options, like <tt>script_name</tt> or <tt>path_info</tt>, can also be
|
|
written:
|
|
|
|
before { request.path_info = "/" }
|
|
|
|
get "/" do
|
|
"all requests end up here"
|
|
end
|
|
|
|
The <tt>request.body</tt> is an IO or StringIO object:
|
|
|
|
post "/api" do
|
|
request.body.rewind # in case someone already read it
|
|
data = JSON.parse request.body.read
|
|
"Hello #{data['name']}!"
|
|
end
|
|
|
|
=== Attachments
|
|
|
|
You can use the +attachment+ helper to tell the browser the response should be
|
|
stored on disk rather than displayed in the browser.
|
|
|
|
get '/' do
|
|
attachment
|
|
"store it!"
|
|
end
|
|
|
|
You can also pass it a file name:
|
|
|
|
get '/' do
|
|
attachment "info.txt"
|
|
"store it!"
|
|
end
|
|
|
|
=== Looking Up Template Files
|
|
|
|
The <tt>find_template</tt> helper is used to find template files for rendering:
|
|
|
|
find_template settings.views, 'foo', Tilt[:haml] do |file|
|
|
puts "could be #{file}"
|
|
end
|
|
|
|
This is not really useful. But it is useful that you can actually override this
|
|
method to hook in your own lookup mechanism. For instance, if you want to be
|
|
able to use more than one view directory:
|
|
|
|
set :views, ['views', 'templates']
|
|
|
|
helpers do
|
|
def find_template(views, name, engine, &block)
|
|
Array(views).each { |v| super(v, name, engine, &block) }
|
|
end
|
|
end
|
|
|
|
Another example would be using different directories for different engines:
|
|
|
|
set :views, :sass => 'views/sass', :haml => 'templates', :default => 'views'
|
|
|
|
helpers do
|
|
def find_template(views, name, engine, &block)
|
|
_, folder = views.detect { |k,v| engine == Tilt[k] }
|
|
folder ||= views[:default]
|
|
super(folder, name, engine, &block)
|
|
end
|
|
end
|
|
|
|
You can also easily wrap this up in an extension and share with others!
|
|
|
|
Note that <tt>find_template</tt> does not check if the file really exists but
|
|
rather calls the given block for all possible paths. This is not a performance
|
|
issue, since +render+ will use +break+ as soon as a file is found. Also,
|
|
template locations (and content) will be cached if you are not running in
|
|
development mode. You should keep that in mind if you write a really crazy
|
|
method.
|
|
|
|
== Configuration
|
|
|
|
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
|
|
<tt>:production</tt>:
|
|
|
|
configure :production do
|
|
...
|
|
end
|
|
|
|
Run when the environment is set to either <tt>:production</tt> or
|
|
<tt>:test</tt>:
|
|
|
|
configure :production, :test do
|
|
...
|
|
end
|
|
|
|
You can access those options via <tt>settings</tt>:
|
|
|
|
configure do
|
|
set :foo, 'bar'
|
|
end
|
|
|
|
get '/' do
|
|
settings.foo? # => true
|
|
settings.foo # => 'bar'
|
|
...
|
|
end
|
|
|
|
=== Available Settings
|
|
|
|
[absolute_redirects] If disabled, Sinatra will allow relative redirects,
|
|
however, Sinatra will no longer conform with RFC 2616
|
|
(HTTP 1.1), which only allows absolute redirects.
|
|
|
|
Enable if your app is running behind a reverse proxy that
|
|
has not been set up properly. Note that the +url+ helper
|
|
will still produce absolute URLs, unless you pass in
|
|
+false+ as second parameter.
|
|
|
|
Disabled per default.
|
|
|
|
[add_charsets] mime types the <tt>content_type</tt> helper will
|
|
automatically add the charset info to.
|
|
|
|
You should add to it rather than overriding this option:
|
|
|
|
settings.add_charsets << "application/foobar"
|
|
|
|
[app_file] main application file, used to detect project root,
|
|
views and public folder and inline templates.
|
|
|
|
[bind] IP address to bind to (default: 0.0.0.0).
|
|
Only used for built-in server.
|
|
|
|
[default_encoding] encoding to assume if unknown
|
|
(defaults to <tt>"utf-8"</tt>).
|
|
|
|
[dump_errors] display errors in the log.
|
|
|
|
[environment] current environment, defaults to <tt>ENV['RACK_ENV']</tt>,
|
|
or <tt>"development"</tt> if not available.
|
|
|
|
[logging] use the logger.
|
|
|
|
[lock] Places a lock around every request, only running
|
|
processing on request per Ruby process concurrently.
|
|
|
|
Enabled if your app is not thread-safe.
|
|
Disabled per default.
|
|
|
|
[method_override] use <tt>_method</tt> magic to allow put/delete forms in
|
|
browsers that don't support it.
|
|
|
|
[port] Port to listen on. Only used for built-in server.
|
|
|
|
[prefixed_redirects] Whether or not to insert <tt>request.script_name</tt> into
|
|
redirects if no absolute path is given. That way
|
|
<tt>redirect '/foo'</tt> would behave like
|
|
<tt>redirect to('/foo')</tt>. Disabled per default.
|
|
|
|
[public] folder public files are served from
|
|
|
|
[reload_templates] whether or not to reload templates between requests.
|
|
Enabled in development mode and on Ruby 1.8.6 (to
|
|
compensate a bug in Ruby causing a memory leak).
|
|
|
|
[root] project root folder.
|
|
|
|
[raise_errors] raise exceptions (will stop application).
|
|
|
|
[run] if enabled, Sinatra will handle starting the web server,
|
|
do not enable if using rackup or other means.
|
|
|
|
[running] is the built-in server running now?
|
|
do not change this setting!
|
|
|
|
[server] server or list of servers to use for built-in server.
|
|
defaults to ['thin', 'mongrel', 'webrick'], order indicates
|
|
priority.
|
|
|
|
[sessions] enable cookie based sessions.
|
|
|
|
[show_exceptions] show a stack trace in the browser.
|
|
|
|
[static] Whether Sinatra should handle serving static files.
|
|
Disable when using a Server able to do this on its own.
|
|
Disabling will boost performance.
|
|
Enabled per default.
|
|
|
|
[views] views folder.
|
|
|
|
== 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>,
|
|
<tt>erb</tt>, <tt>halt</tt>, etc.
|
|
|
|
=== Not Found
|
|
|
|
When a <tt>Sinatra::NotFound</tt> exception is raised, or the response's status
|
|
code is 404, the <tt>not_found</tt> handler is invoked:
|
|
|
|
not_found do
|
|
'This is nowhere to be found.'
|
|
end
|
|
|
|
=== Error
|
|
|
|
The +error+ handler is invoked any time an exception is raised from a route
|
|
block or a filter. The exception object can be obtained from the
|
|
<tt>sinatra.error</tt> Rack variable:
|
|
|
|
error do
|
|
'Sorry there was a nasty error - ' + env['sinatra.error'].name
|
|
end
|
|
|
|
Custom errors:
|
|
|
|
error MyCustomError do
|
|
'So what happened was...' + request.env['sinatra.error'].message
|
|
end
|
|
|
|
Then, if this happens:
|
|
|
|
get '/' do
|
|
raise MyCustomError, 'something bad'
|
|
end
|
|
|
|
You get this:
|
|
|
|
So what happened was... something bad
|
|
|
|
Alternatively, you can install an error handler for a status code:
|
|
|
|
error 403 do
|
|
'Access forbidden'
|
|
end
|
|
|
|
get '/secret' do
|
|
403
|
|
end
|
|
|
|
Or a range:
|
|
|
|
error 400..510 do
|
|
'Boom'
|
|
end
|
|
|
|
Sinatra installs special <tt>not_found</tt> and <tt>error</tt> handlers when
|
|
running under the development environment.
|
|
|
|
== Rack Middleware
|
|
|
|
Sinatra rides on Rack[http://rack.rubyforge.org/], a minimal standard
|
|
interface for Ruby web frameworks. One of Rack's most interesting capabilities
|
|
for application developers is support for "middleware" -- components that sit
|
|
between the server and your application monitoring and/or manipulating the
|
|
HTTP request/response to provide various types of common functionality.
|
|
|
|
Sinatra makes building Rack middleware pipelines a cinch via a top-level
|
|
+use+ method:
|
|
|
|
require 'sinatra'
|
|
require 'my_custom_middleware'
|
|
|
|
use Rack::Lint
|
|
use MyCustomMiddleware
|
|
|
|
get '/hello' do
|
|
'Hello World'
|
|
end
|
|
|
|
The semantics of +use+ are identical to those defined for the
|
|
Rack::Builder[http://rack.rubyforge.org/doc/classes/Rack/Builder.html] DSL
|
|
(most frequently used from rackup files). For example, the +use+ method
|
|
accepts multiple/variable args as well as blocks:
|
|
|
|
use Rack::Auth::Basic do |username, password|
|
|
username == 'admin' && password == 'secret'
|
|
end
|
|
|
|
Rack is distributed with a variety of standard middleware for logging,
|
|
debugging, URL routing, authentication, and session handling. Sinatra uses
|
|
many of these components automatically based on configuration so you
|
|
typically don't have to +use+ them explicitly.
|
|
|
|
== Testing
|
|
|
|
Sinatra tests can be written using any Rack-based testing library
|
|
or framework. {Rack::Test}[http://gitrdoc.com/brynary/rack-test] is
|
|
recommended:
|
|
|
|
require 'my_sinatra_app'
|
|
require 'test/unit'
|
|
require 'rack/test'
|
|
|
|
class MyAppTest < Test::Unit::TestCase
|
|
include Rack::Test::Methods
|
|
|
|
def app
|
|
Sinatra::Application
|
|
end
|
|
|
|
def test_my_default
|
|
get '/'
|
|
assert_equal 'Hello World!', last_response.body
|
|
end
|
|
|
|
def test_with_params
|
|
get '/meet', :name => 'Frank'
|
|
assert_equal 'Hello Frank!', last_response.body
|
|
end
|
|
|
|
def test_with_rack_env
|
|
get '/', {}, 'HTTP_USER_AGENT' => 'Songbird'
|
|
assert_equal "You're using Songbird!", last_response.body
|
|
end
|
|
end
|
|
|
|
NOTE: The built-in Sinatra::Test module and Sinatra::TestHarness class
|
|
are deprecated as of the 0.9.2 release.
|
|
|
|
== Sinatra::Base - Middleware, Libraries, and Modular Apps
|
|
|
|
Defining your app at the top-level works well for micro-apps but has
|
|
considerable drawbacks when building reusable components such as Rack
|
|
middleware, Rails metal, simple libraries with a server component, or
|
|
even Sinatra extensions. The top-level DSL pollutes the Object namespace
|
|
and assumes a micro-app style configuration (e.g., a single application
|
|
file, ./public and ./views directories, logging, exception detail page,
|
|
etc.). That's where Sinatra::Base comes into play:
|
|
|
|
require 'sinatra/base'
|
|
|
|
class MyApp < Sinatra::Base
|
|
set :sessions, true
|
|
set :foo, 'bar'
|
|
|
|
get '/' do
|
|
'Hello world!'
|
|
end
|
|
end
|
|
|
|
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:
|
|
|
|
* Your file should require <tt>sinatra/base</tt> instead of +sinatra+;
|
|
otherwise, all of Sinatra's DSL methods are imported into the main
|
|
namespace.
|
|
* Put your app's routes, error handlers, filters, and options in a subclass
|
|
of Sinatra::Base.
|
|
|
|
<tt>Sinatra::Base</tt> is a blank slate. Most options are disabled by default,
|
|
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 belief, 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 with modular 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, actively 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
|
|
can in turn be added in front of any Rack endpoint as middleware itself. This
|
|
endpoint could be another Sinatra application, or any other Rack-based
|
|
application (Rails/Ramaze/Camping/...).
|
|
|
|
require 'sinatra/base'
|
|
|
|
class LoginScreen < Sinatra::Base
|
|
enable :sessions
|
|
|
|
get('/login') { haml :login }
|
|
|
|
post('/login') do
|
|
if params[:name] = 'admin' and params[:password] = 'admin'
|
|
session['user_name'] = params[:name]
|
|
else
|
|
redirect '/login'
|
|
end
|
|
end
|
|
end
|
|
|
|
class MyApp < Sinatra::Base
|
|
# middleware will run before filters
|
|
use LoginScreen
|
|
|
|
before do
|
|
unless session['user_name']
|
|
halt "Access denied, please <a href='/login'>login</a>."
|
|
end
|
|
end
|
|
|
|
get('/') { "Hello #{session['user_name']}." }
|
|
end
|
|
|
|
== Scopes and Binding
|
|
|
|
The scope you are currently in determines what methods and variables are
|
|
available.
|
|
|
|
=== Application/Class Scope
|
|
|
|
Every Sinatra application corresponds to a subclass of Sinatra::Base. If you
|
|
are using the top-level DSL (<tt>require 'sinatra'</tt>), then this class is
|
|
Sinatra::Application, otherwise it is the subclass you created explicitly. At
|
|
class level you have methods like +get+ or +before+, but you cannot access the
|
|
+request+ object or the +session+, as there only is a single application class
|
|
for all requests.
|
|
|
|
Options created via +set+ are methods at class level:
|
|
|
|
class MyApp < Sinatra::Base
|
|
# Hey, I'm in the application scope!
|
|
set :foo, 42
|
|
foo # => 42
|
|
|
|
get '/foo' do
|
|
# Hey, I'm no longer in the application scope!
|
|
end
|
|
end
|
|
|
|
You have the application scope binding inside:
|
|
|
|
* Your application class body
|
|
* Methods defined by extensions
|
|
* The block passed to +helpers+
|
|
* Procs/blocks used as value for +set+
|
|
|
|
You can reach the scope object (the class) like this:
|
|
|
|
* Via the object passed to configure blocks (<tt>configure { |c| ... }</tt>)
|
|
* +settings+ from within request scope
|
|
|
|
=== Request/Instance Scope
|
|
|
|
For every incoming request, a new instance of your application class is
|
|
created and all handler blocks run in that scope. From within this scope you
|
|
can access the +request+ and +session+ object or call rendering methods like
|
|
+erb+ or +haml+. You can access the application scope from within the request
|
|
scope via the +settings+ helper:
|
|
|
|
class MyApp < Sinatra::Base
|
|
# Hey, I'm in the application scope!
|
|
get '/define_route/:name' do
|
|
# Request scope for '/define_route/:name'
|
|
@value = 42
|
|
|
|
settings.get("/#{params[:name]}") do
|
|
# Request scope for "/#{params[:name]}"
|
|
@value # => nil (not the same request)
|
|
end
|
|
|
|
"Route defined!"
|
|
end
|
|
end
|
|
|
|
You have the request scope binding inside:
|
|
|
|
* get/head/post/put/delete/options blocks
|
|
* before/after filters
|
|
* helper methods
|
|
* templates/views
|
|
|
|
=== Delegation Scope
|
|
|
|
The delegation scope just forwards methods to the class scope. However, it
|
|
does not behave 100% like the class scope, as you do not have the class
|
|
binding. Only methods explicitly marked for delegation are available and you
|
|
do not share variables/state with the class scope (read: you have a different
|
|
+self+). You can explicitly add method delegations by calling
|
|
<tt>Sinatra::Delegator.delegate :method_name</tt>.
|
|
|
|
You have the delegate scope binding inside:
|
|
|
|
* The top level binding, if you did <tt>require "sinatra"</tt>
|
|
* An object extended with the <tt>Sinatra::Delegator</tt> mixin
|
|
|
|
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
|
|
|
|
Sinatra applications can be run directly:
|
|
|
|
ruby myapp.rb [-h] [-x] [-e ENVIRONMENT] [-p PORT] [-o HOST] [-s HANDLER]
|
|
|
|
Options are:
|
|
|
|
-h # help
|
|
-p # set the port (default is 4567)
|
|
-o # set the host (default is 0.0.0.0)
|
|
-e # set the environment (default is development)
|
|
-s # specify rack server/handler (default is thin)
|
|
-x # turn on the mutex lock (default is off)
|
|
|
|
== Requirements
|
|
|
|
It is recommended to install Sinatra on Ruby 1.8.7, 1.9.2, JRuby or Rubinius.
|
|
|
|
The following Ruby versions are officially supported:
|
|
|
|
[ Ruby 1.8.6 ]
|
|
It is not recommended to use 1.8.6 for Sinatra. However, it will be
|
|
officially supported until Sinatra 1.3.0 is released. RDoc and CoffeScript
|
|
templates are not supported by this Ruby version. 1.8.6 includes a major
|
|
memory leak in its Hash implementation, which is triggered by Sinatra
|
|
versions prior to 1.1.1. The current version explicitly prevents this leak
|
|
at the cost of performance. You will have to downgrade Rack to 1.1.x, as
|
|
Rack >= 1.2 no longer supports 1.8.6.
|
|
|
|
[ Ruby 1.8.7 ]
|
|
1.8.7 is fully supported, however, if nothing is keeping you from it, we
|
|
recommend upgrading to 1.9.2 or switching to JRuby or Rubinius.
|
|
|
|
[ Ruby 1.9.2 ]
|
|
1.9.2 is supported and recommended. Note that Radius and Markaby are
|
|
currently not 1.9 compatible. Do not use 1.9.2p0, it is known to cause
|
|
segmentation faults when using Sinatra.
|
|
|
|
[ Rubinius ]
|
|
Rubinius is officially supported (Rubinius >= 1.2.2), with the exception
|
|
of Textile templates.
|
|
|
|
[ JRuby ]
|
|
JRuby is officially supported (JRuby >= 1.5.6). No issues with third party
|
|
template libraries are known, however, if you choose to use JRuby, please
|
|
look into JRuby rack handlers, as the Thin web server is not (yet) supported
|
|
on JRuby.
|
|
|
|
We also keep an eye on upcoming Ruby versions.
|
|
|
|
The following Ruby implementations are not officially supported but still are
|
|
known to run Sinatra:
|
|
|
|
* Older versions of JRuby and Rubinius
|
|
* MacRuby
|
|
* Maglev
|
|
* IronRuby
|
|
* Ruby 1.9.0 and 1.9.1
|
|
|
|
Not being officially supported means if things only break there and not on a
|
|
supported platform, we assume it's not our issue but theirs.
|
|
|
|
Sinatra should work on any operating system supported by the chosen Ruby
|
|
implementation.
|
|
|
|
== 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
|
|
|
|
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 recommended way.
|
|
|
|
First, install bundler, if you haven't:
|
|
|
|
gem install bundler
|
|
|
|
Then, in your 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
|
|
|
|
To update the Sinatra sources in the future:
|
|
|
|
cd myapp/sinatra
|
|
git pull
|
|
|
|
=== Install Globally
|
|
|
|
You can build the gem on your own:
|
|
|
|
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
|
|
|
|
== Further Reading
|
|
|
|
* {Project Website}[http://www.sinatrarb.com/] - Additional documentation,
|
|
news, and links to other resources.
|
|
* {Contributing}[http://www.sinatrarb.com/contributing] - Find a bug? Need
|
|
help? Have a patch?
|
|
* {Issue tracker}[http://github.com/sinatra/sinatra/issues]
|
|
* {Twitter}[http://twitter.com/sinatra]
|
|
* {Mailing List}[http://groups.google.com/group/sinatrarb/topics]
|
|
* {IRC: #sinatra}[irc://chat.freenode.net/#sinatra] on http://freenode.net
|