README and CHANGES tweaks for 0.9.0 release (#63)
* Add support for regex routes to README * Use $LOAD_PATH instead of $: * EventContext is no longer present * Misc cleanup from rtomayko
This commit is contained in:
parent
9ab1b600c9
commit
17cb177ea3
32
CHANGES
32
CHANGES
|
@ -1,31 +1,37 @@
|
||||||
= 0.9.0 (unreleased)
|
= 0.9.0 (unreleased)
|
||||||
|
|
||||||
* New "dump_errors" option controls whether the backtrace is dumped to
|
* Works with and requires Rack >= 0.9.1
|
||||||
rack.errors when an exception is raised from a route. The option is
|
|
||||||
enabled by default for top-level apps.
|
* Multiple Sinatra applications can now co-exist peacefully within a
|
||||||
|
single process. The new "Sinatra::Base" class can be subclassed to
|
||||||
|
establish a blank-slate Rack application or middleware component.
|
||||||
|
Documentation on using these features is forth-coming; the following
|
||||||
|
provides the basic gist: http://gist.github.com/38605
|
||||||
|
|
||||||
|
* Regular expressions may now be used in route pattens; captures are
|
||||||
|
available at "params[:captures]".
|
||||||
|
|
||||||
* New ":provides" route condition takes an array of mime types and
|
* New ":provides" route condition takes an array of mime types and
|
||||||
matches only when an Accept request header is present with a
|
matches only when an Accept request header is present with a
|
||||||
corresponding type. [cypher]
|
corresponding type. [cypher]
|
||||||
|
|
||||||
* Work with and require Rack >= 0.9
|
* New request-level "pass" method; immediately exits the current block
|
||||||
|
and passes control to the next matching route.
|
||||||
* Regular expressions may now be used in route pattens; captures are
|
|
||||||
available at "params[:captures]".
|
|
||||||
|
|
||||||
* The request-level "body" method now takes a block; evaluation is
|
* The request-level "body" method now takes a block; evaluation is
|
||||||
deferred until an attempt is made to read the body. The block must
|
deferred until an attempt is made to read the body. The block must
|
||||||
return a String or Array.
|
return a String or Array.
|
||||||
|
|
||||||
* Better default "app_file", "root", "public", and "views" location
|
|
||||||
detection; changes to "root" and "app_file" automatically cascade to
|
|
||||||
other options that depend on them.
|
|
||||||
|
|
||||||
* New "route conditions" system for attaching rules for when a route
|
* New "route conditions" system for attaching rules for when a route
|
||||||
matches. The :agent and :host route options now use this system.
|
matches. The :agent and :host route options now use this system.
|
||||||
|
|
||||||
* New request-level "pass" method; immediately exits the current block
|
* New "dump_errors" option controls whether the backtrace is dumped to
|
||||||
and passes control to the next matching route.
|
rack.errors when an exception is raised from a route. The option is
|
||||||
|
enabled by default for top-level apps.
|
||||||
|
|
||||||
|
* Better default "app_file", "root", "public", and "views" location
|
||||||
|
detection; changes to "root" and "app_file" automatically cascade to
|
||||||
|
other options that depend on them.
|
||||||
|
|
||||||
* Error mappings are now split into two distinct layers: exception
|
* Error mappings are now split into two distinct layers: exception
|
||||||
mappings and custom error pages. Exception mappings are registered
|
mappings and custom error pages. Exception mappings are registered
|
||||||
|
|
158
README.rdoc
158
README.rdoc
|
@ -1,9 +1,7 @@
|
||||||
= Sinatra
|
= Sinatra
|
||||||
|
|
||||||
Sinatra is a DSL for quickly creating web-applications in Ruby with minimal
|
Sinatra is a DSL for quickly creating web-applications in Ruby with minimal
|
||||||
effort.
|
effort:
|
||||||
|
|
||||||
== Sample App
|
|
||||||
|
|
||||||
# myapp.rb
|
# myapp.rb
|
||||||
require 'rubygems'
|
require 'rubygems'
|
||||||
|
@ -32,10 +30,6 @@ Run with <tt>ruby myapp.rb</tt> and view at <tt>http://localhost:4567</tt>
|
||||||
.. annihilate something ..
|
.. annihilate something ..
|
||||||
end
|
end
|
||||||
|
|
||||||
head '/' do
|
|
||||||
|
|
||||||
end
|
|
||||||
|
|
||||||
== Routes
|
== Routes
|
||||||
|
|
||||||
Routes are matched based on the order of declaration. The first route that
|
Routes are matched based on the order of declaration. The first route that
|
||||||
|
@ -47,14 +41,17 @@ Basic routes:
|
||||||
...
|
...
|
||||||
end
|
end
|
||||||
|
|
||||||
Named parameters:
|
Route patterns may include named parameters, accessible via the
|
||||||
|
<tt>params</tt> hash:
|
||||||
|
|
||||||
get '/:name' do
|
get '/:name' do
|
||||||
# matches "GET /foo" and "GET /bar"
|
# matches "GET /foo" and "GET /bar"
|
||||||
# params[:name] is 'foo' or 'bar'
|
# params[:name] is 'foo' or 'bar'
|
||||||
|
"Hello #{params[:name]}!"
|
||||||
end
|
end
|
||||||
|
|
||||||
Splat parameters:
|
Route patterns may also include splat (or wildcard) parameters, accessible
|
||||||
|
via the <tt>params[:splat]</tt> array.
|
||||||
|
|
||||||
get '/say/*/to/*' do
|
get '/say/*/to/*' do
|
||||||
# matches /say/hello/to/world
|
# matches /say/hello/to/world
|
||||||
|
@ -66,7 +63,13 @@ Splat parameters:
|
||||||
params[:splat] # => ["path/to/file", "xml"]
|
params[:splat] # => ["path/to/file", "xml"]
|
||||||
end
|
end
|
||||||
|
|
||||||
User agent matching:
|
Route matching with Regular Expressions:
|
||||||
|
|
||||||
|
get %r{/hello/([\w]+)} do
|
||||||
|
"Hello, #{params[:captures].first}!"
|
||||||
|
end
|
||||||
|
|
||||||
|
Routes may include a variety of matching conditions, such as the user agent:
|
||||||
|
|
||||||
get '/foo', :agent => /Songbird (\d\.\d)[\d\/]*?/ do
|
get '/foo', :agent => /Songbird (\d\.\d)[\d\/]*?/ do
|
||||||
"You're using Songbird version #{params[:agent][0]}"
|
"You're using Songbird version #{params[:agent][0]}"
|
||||||
|
@ -78,33 +81,29 @@ User agent matching:
|
||||||
|
|
||||||
== Static Files
|
== Static Files
|
||||||
|
|
||||||
Put all of your static content in the ./public directory
|
Static files are served from the <tt>./public</tt> directory. You can specify
|
||||||
|
a different location by setting the <tt>:public</tt> option:
|
||||||
root
|
|
||||||
\ public
|
|
||||||
|
|
||||||
To use a different static directory:
|
|
||||||
|
|
||||||
set :public, File.dirname(__FILE__) + '/static'
|
set :public, File.dirname(__FILE__) + '/static'
|
||||||
|
|
||||||
== Views
|
== Views / Templates
|
||||||
|
|
||||||
Views are searched for in a ./views directory in the same location as
|
Templates are assumed to be located directly under a <tt>./views</tt>
|
||||||
your main application.
|
directory. To use a different views directory:
|
||||||
|
|
||||||
To use a different views directory:
|
|
||||||
|
|
||||||
set :views, File.dirname(__FILE__) + '/templates'
|
set :views, File.dirname(__FILE__) + '/templates'
|
||||||
|
|
||||||
=== Haml Templates
|
=== Haml Templates
|
||||||
|
|
||||||
|
The haml gem/library is required to render HAML templates:
|
||||||
|
|
||||||
get '/' do
|
get '/' do
|
||||||
haml :index
|
haml :index
|
||||||
end
|
end
|
||||||
|
|
||||||
Renders <tt>./views/index.haml</tt>.
|
Renders <tt>./views/index.haml</tt>.
|
||||||
|
|
||||||
=== Erb
|
=== Erb Templates
|
||||||
|
|
||||||
get '/' do
|
get '/' do
|
||||||
erb :index
|
erb :index
|
||||||
|
@ -112,11 +111,20 @@ Renders <tt>./views/index.haml</tt>.
|
||||||
|
|
||||||
Renders <tt>./views/index.erb</tt>
|
Renders <tt>./views/index.erb</tt>
|
||||||
|
|
||||||
=== Builder
|
=== Builder Templates
|
||||||
|
|
||||||
See Sinatra::Builder
|
The builder gem/library is required to render builder templates:
|
||||||
|
|
||||||
=== Sass
|
get '/' do
|
||||||
|
content_type 'application/xml', :charset => 'utf-8'
|
||||||
|
builder :index
|
||||||
|
end
|
||||||
|
|
||||||
|
Renders <tt>./views/index.builder</tt>.
|
||||||
|
|
||||||
|
=== Sass Templates
|
||||||
|
|
||||||
|
The sass gem/library is required to render Sass templates:
|
||||||
|
|
||||||
get '/stylesheet.css' do
|
get '/stylesheet.css' do
|
||||||
content_type 'text/css', :charset => 'utf-8'
|
content_type 'text/css', :charset => 'utf-8'
|
||||||
|
@ -135,9 +143,8 @@ Renders the inlined template string.
|
||||||
|
|
||||||
=== Accessing Variables
|
=== Accessing Variables
|
||||||
|
|
||||||
Templates are evaluated within the Sinatra::EventContext instance
|
Templates are evaluated within the same context as the route blocks. Instance
|
||||||
used to evaluate event blocks. Instance variables set in event
|
variables set in route blocks are available in templates:
|
||||||
blocks can be accessed direcly in views:
|
|
||||||
|
|
||||||
get '/:id' do
|
get '/:id' do
|
||||||
@foo = Foo.find(params[:id])
|
@foo = Foo.find(params[:id])
|
||||||
|
@ -167,9 +174,8 @@ Templates may be defined at the end of the source file:
|
||||||
__END__
|
__END__
|
||||||
|
|
||||||
@@ layout
|
@@ layout
|
||||||
X
|
%html
|
||||||
= yield
|
= yield
|
||||||
X
|
|
||||||
|
|
||||||
@@ index
|
@@ index
|
||||||
%div.title Hello world!!!!!
|
%div.title Hello world!!!!!
|
||||||
|
@ -178,7 +184,7 @@ It's also possible to define named templates using the top-level template
|
||||||
method:
|
method:
|
||||||
|
|
||||||
template :layout do
|
template :layout do
|
||||||
"X\n=yield\nX"
|
"%html\n =yield\n"
|
||||||
end
|
end
|
||||||
|
|
||||||
template :index do
|
template :index do
|
||||||
|
@ -189,8 +195,8 @@ method:
|
||||||
haml :index
|
haml :index
|
||||||
end
|
end
|
||||||
|
|
||||||
Some times you'll want to render a specific template with or without a
|
If a template named "layout" exists, it will be used each time a template
|
||||||
layout (i.e. if a request is Ajax or not).
|
is rendered. You can disable layouts by passing <tt>:layout => false</tt>.
|
||||||
|
|
||||||
get '/' do
|
get '/' do
|
||||||
haml :index, :layout => !request.xhr?
|
haml :index, :layout => !request.xhr?
|
||||||
|
@ -198,7 +204,8 @@ layout (i.e. if a request is Ajax or not).
|
||||||
|
|
||||||
== Helpers
|
== Helpers
|
||||||
|
|
||||||
The top-level <tt>helpers</tt> method
|
Use the top-level <tt>helpers</tt> method to define helper methods for use in
|
||||||
|
route blocks and templates:
|
||||||
|
|
||||||
helpers do
|
helpers do
|
||||||
def bar(name)
|
def bar(name)
|
||||||
|
@ -212,7 +219,9 @@ The top-level <tt>helpers</tt> method
|
||||||
|
|
||||||
== Filters
|
== Filters
|
||||||
|
|
||||||
Before filters are evaluated in request context before routing is performed:
|
Before filters are evaluated before each request within the context of the
|
||||||
|
request and can modify the request and response. Instance variables set in
|
||||||
|
filters are accessible by routes and templates.
|
||||||
|
|
||||||
before do
|
before do
|
||||||
@note = 'Hi!'
|
@note = 'Hi!'
|
||||||
|
@ -224,64 +233,75 @@ Before filters are evaluated in request context before routing is performed:
|
||||||
params[:splat] #=> 'bar/baz'
|
params[:splat] #=> 'bar/baz'
|
||||||
end
|
end
|
||||||
|
|
||||||
Before filters can modify the request and response; instance variables are
|
== Halting
|
||||||
available to routes.
|
|
||||||
|
|
||||||
== Halt!
|
To immediately stop a request during a before filter or route use:
|
||||||
|
|
||||||
To immediately stop a request during a before filter or event use:
|
halt
|
||||||
|
|
||||||
throw :halt
|
You can also specify a body when halting ...
|
||||||
|
|
||||||
Set the body to a simple string
|
halt 'this will be the body'
|
||||||
|
|
||||||
throw :halt, 'this will be the body'
|
Set the status and body ...
|
||||||
|
|
||||||
Set status then the body
|
halt 401, 'go away!'
|
||||||
|
|
||||||
throw :halt, [401, 'go away!']
|
== Passing
|
||||||
|
|
||||||
Run a proc inside the Sinatra::EventContext instance and set the body to the
|
A route can punt processing to the next matching route using the <tt>pass</tt>
|
||||||
result
|
statement:
|
||||||
|
|
||||||
throw :halt, lambda { puts 'In a proc!'; 'I just wrote to $stdout!' }
|
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.
|
||||||
|
|
||||||
== Configuration and Reloading
|
== Configuration and Reloading
|
||||||
|
|
||||||
Sinatra supports multiple environments and reloading. Reloading happens
|
Sinatra supports multiple environments and reloading. Reloading happens
|
||||||
before every request when running under the :development environment. Wrap
|
before each request when running under the <tt>:development</tt>
|
||||||
your configurations in <tt>configure</tt> (i.e. Database connections, Constants,
|
environment. Wrap your configurations (e.g., database connections, constants,
|
||||||
etc.) to protect them from reloading or to target specific environments.
|
etc.) in <tt>configure</tt> blocks to protect them from reloading or to
|
||||||
|
target specific environments.
|
||||||
|
|
||||||
All environments:
|
Run once, at startup, in any environment:
|
||||||
|
|
||||||
configure do
|
configure do
|
||||||
...
|
...
|
||||||
end
|
end
|
||||||
|
|
||||||
Production:
|
Run only when the environment (RACK_ENV environment variable) is set to
|
||||||
|
<tt>:production</tt>.
|
||||||
|
|
||||||
configure :production do
|
configure :production do
|
||||||
...
|
...
|
||||||
end
|
end
|
||||||
|
|
||||||
Two at a time:
|
Run when the environment (RACK_ENV environment variable) is set to
|
||||||
|
either <tt>:production</tt> or <tt>:test</tt>.
|
||||||
|
|
||||||
configure :production, :test do
|
configure :production, :test do
|
||||||
...
|
...
|
||||||
end
|
end
|
||||||
|
|
||||||
This is also really nifty for error handling.
|
|
||||||
|
|
||||||
== Error handling
|
== Error handling
|
||||||
|
|
||||||
Error handlers run inside the current Sinatra::EventContext instance, which
|
Error handlers run within the same context as routes and before filters, which
|
||||||
means you get all the goodies it has to offer (i.e. haml, erb, throw :halt,
|
means you get all the goodies it has to offer, like <tt>haml</tt>, <tt>erb</tt>,
|
||||||
etc.)
|
<tt>halt</tt>, etc.
|
||||||
|
|
||||||
=== Not Found
|
=== Not Found
|
||||||
|
|
||||||
When Sinatra::NotFound is raised, the not_found handler is invoked:
|
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
|
not_found do
|
||||||
'This is nowhere to be found'
|
'This is nowhere to be found'
|
||||||
|
@ -289,14 +309,12 @@ When Sinatra::NotFound is raised, the not_found handler is invoked:
|
||||||
|
|
||||||
=== Error
|
=== Error
|
||||||
|
|
||||||
By default, the +error+ handler is invoked on Sinatra::ServerError or when
|
The +error+ handler is invoked any time an exception is raised from a route
|
||||||
an unknown error occurs.
|
block or before filter. The exception object can be obtained from the
|
||||||
|
'sinatra.error' Rack variable:
|
||||||
The exception can be obtained from the 'sinatra.error' variable in
|
|
||||||
request.env.
|
|
||||||
|
|
||||||
error do
|
error do
|
||||||
'Sorry there was a nasty error - ' + request.env['sinatra.error'].name
|
'Sorry there was a nasty error - ' + env['sinatra.error'].name
|
||||||
end
|
end
|
||||||
|
|
||||||
Custom errors:
|
Custom errors:
|
||||||
|
@ -316,12 +334,12 @@ You get this:
|
||||||
So what happened was... something bad
|
So what happened was... something bad
|
||||||
|
|
||||||
Sinatra installs special not_found and error handlers when running under
|
Sinatra installs special not_found and error handlers when running under
|
||||||
the development.
|
the development environment.
|
||||||
|
|
||||||
== Mime types
|
== Mime types
|
||||||
|
|
||||||
When using send_file or static files you may have mime types Sinatra doesn't
|
When using <tt>send_file</tt> or static files you may have mime types Sinatra
|
||||||
understand. Use +mime+ in those cases.
|
doesn't understand. Use +mime+ to register them by file extension:
|
||||||
|
|
||||||
mime :foo, 'text/foo'
|
mime :foo, 'text/foo'
|
||||||
|
|
||||||
|
@ -469,7 +487,7 @@ screencasts about Git, which you can find here: http://www.gitcasts.com/
|
||||||
|
|
||||||
at the top of your sinatra_app.rb file:
|
at the top of your sinatra_app.rb file:
|
||||||
|
|
||||||
$:.unshift File.dirname(__FILE__) + '/sinatra/lib'
|
$LOAD_PATH.unshift File.dirname(__FILE__) + '/sinatra/lib'
|
||||||
require 'sinatra'
|
require 'sinatra'
|
||||||
|
|
||||||
get '/about' do
|
get '/about' do
|
||||||
|
|
Loading…
Reference in New Issue