Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 623 lines (431 sloc) 15.459 kb
df800b5 Docs are started
Blake Mizerany authored
1 = Sinatra
2
4c91e54 @watchdogtimer Web applications should not be hyphenated
watchdogtimer authored
3 Sinatra is a DSL for quickly creating web applications in Ruby with minimal
17cb177 @cypher README and CHANGES tweaks for 0.9.0 release (#63)
cypher authored
4 effort:
df800b5 Docs are started
Blake Mizerany authored
5
6 # myapp.rb
7 require 'rubygems'
8 require 'sinatra'
9 get '/' do
10 'Hello world!'
11 end
12
4298a77 @rtomayko Tweak README formatting; move community/contributing to website
rtomayko authored
13 Install the gem and run with:
df800b5 Docs are started
Blake Mizerany authored
14
4298a77 @rtomayko Tweak README formatting; move community/contributing to website
rtomayko authored
15 sudo gem install sinatra
16 ruby myapp.rb
17
18 View at: http://localhost:4567
19
20 == Routes
21
22 In Sinatra, a route is an HTTP method paired with an URL matching pattern.
23 Each route is associated with a block:
df800b5 Docs are started
Blake Mizerany authored
24
25 get '/' do
4298a77 @rtomayko Tweak README formatting; move community/contributing to website
rtomayko authored
26 .. show something ..
df800b5 Docs are started
Blake Mizerany authored
27 end
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
28
df800b5 Docs are started
Blake Mizerany authored
29 post '/' do
30 .. create something ..
31 end
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
32
df800b5 Docs are started
Blake Mizerany authored
33 put '/' do
34 .. update something ..
35 end
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
36
df800b5 Docs are started
Blake Mizerany authored
37 delete '/' do
38 .. annihilate something ..
39 end
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
40
4298a77 @rtomayko Tweak README formatting; move community/contributing to website
rtomayko authored
41 Routes are matched in the order they are defined. The first route that
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
42 matches the request is invoked.
1776a80 Added Version and Docs
Blake Mizerany authored
43
17cb177 @cypher README and CHANGES tweaks for 0.9.0 release (#63)
cypher authored
44 Route patterns may include named parameters, accessible via the
45 <tt>params</tt> hash:
1776a80 Added Version and Docs
Blake Mizerany authored
46
4298a77 @rtomayko Tweak README formatting; move community/contributing to website
rtomayko authored
47 get '/hello/:name' do
ce0fe87 @scottj97 fix inaccurate comment in README
scottj97 authored
48 # matches "GET /hello/foo" and "GET /hello/bar"
a734cf3 @rtomayko I knew I shoulda taken that left turn at Hoboken
rtomayko authored
49 # params[:name] is 'foo' or 'bar'
17cb177 @cypher README and CHANGES tweaks for 0.9.0 release (#63)
cypher authored
50 "Hello #{params[:name]}!"
1776a80 Added Version and Docs
Blake Mizerany authored
51 end
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
52
6569d1b @bdimcheff Added route block params in routing statements [#140]
bdimcheff authored
53 You can also access named parameters via block parameters:
54
55 get '/hello/:name' do |n|
56 "Hello #{n}!"
57 end
58
17cb177 @cypher README and CHANGES tweaks for 0.9.0 release (#63)
cypher authored
59 Route patterns may also include splat (or wildcard) parameters, accessible
60 via the <tt>params[:splat]</tt> array.
1776a80 Added Version and Docs
Blake Mizerany authored
61
9c85e99 @vic Specs, documentation and fixes for splat'n routes
vic authored
62 get '/say/*/to/*' do
63 # matches /say/hello/to/world
a734cf3 @rtomayko I knew I shoulda taken that left turn at Hoboken
rtomayko authored
64 params[:splat] # => ["hello", "world"]
9c85e99 @vic Specs, documentation and fixes for splat'n routes
vic authored
65 end
66
67 get '/download/*.*' do
68 # matches /download/path/to/file.xml
a734cf3 @rtomayko I knew I shoulda taken that left turn at Hoboken
rtomayko authored
69 params[:splat] # => ["path/to/file", "xml"]
1776a80 Added Version and Docs
Blake Mizerany authored
70 end
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
71
17cb177 @cypher README and CHANGES tweaks for 0.9.0 release (#63)
cypher authored
72 Route matching with Regular Expressions:
73
74 get %r{/hello/([\w]+)} do
75 "Hello, #{params[:captures].first}!"
76 end
77
6569d1b @bdimcheff Added route block params in routing statements [#140]
bdimcheff authored
78 Or with a block parameter:
79
80 get %r{/hello/([\w]+)} do |c|
81 "Hello, #{c}!"
82 end
83
17cb177 @cypher README and CHANGES tweaks for 0.9.0 release (#63)
cypher authored
84 Routes may include a variety of matching conditions, such as the user agent:
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
85
1776a80 Added Version and Docs
Blake Mizerany authored
86 get '/foo', :agent => /Songbird (\d\.\d)[\d\/]*?/ do
87 "You're using Songbird version #{params[:agent][0]}"
88 end
89
90 get '/foo' do
a734cf3 @rtomayko I knew I shoulda taken that left turn at Hoboken
rtomayko authored
91 # Matches non-songbird browsers
1776a80 Added Version and Docs
Blake Mizerany authored
92 end
df800b5 Docs are started
Blake Mizerany authored
93
a734cf3 @rtomayko I knew I shoulda taken that left turn at Hoboken
rtomayko authored
94 == Static Files
047edc6 update README with Static help
Blake Mizerany authored
95
17cb177 @cypher README and CHANGES tweaks for 0.9.0 release (#63)
cypher authored
96 Static files are served from the <tt>./public</tt> directory. You can specify
97 a different location by setting the <tt>:public</tt> option:
a734cf3 @rtomayko I knew I shoulda taken that left turn at Hoboken
rtomayko authored
98
99 set :public, File.dirname(__FILE__) + '/static'
df800b5 Docs are started
Blake Mizerany authored
100
4298a77 @rtomayko Tweak README formatting; move community/contributing to website
rtomayko authored
101 Note that the public directory name is not included in the URL. A file
85b4462 @rtomayko README: fix formatting on static file note
rtomayko authored
102 <tt>./public/css/style.css</tt> is made available as
103 <tt>http://example.com/css/style.css</tt>.
4298a77 @rtomayko Tweak README formatting; move community/contributing to website
rtomayko authored
104
17cb177 @cypher README and CHANGES tweaks for 0.9.0 release (#63)
cypher authored
105 == Views / Templates
df800b5 Docs are started
Blake Mizerany authored
106
4298a77 @rtomayko Tweak README formatting; move community/contributing to website
rtomayko authored
107 Templates are assumed to be located directly under the <tt>./views</tt>
17cb177 @cypher README and CHANGES tweaks for 0.9.0 release (#63)
cypher authored
108 directory. To use a different views directory:
a734cf3 @rtomayko I knew I shoulda taken that left turn at Hoboken
rtomayko authored
109
110 set :views, File.dirname(__FILE__) + '/templates'
111
06161bf @cypher Note on passing template symbols vs. strings in README
cypher authored
112 One important thing to remember is that you always have to reference
113 templates with symbols, even if they're in a subdirectory (in this
114 case use <tt>:'subdir/template'</tt>). Rendering methods will render
115 any strings passed to them directly.
116
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
117 === Haml Templates
df800b5 Docs are started
Blake Mizerany authored
118
17cb177 @cypher README and CHANGES tweaks for 0.9.0 release (#63)
cypher authored
119 The haml gem/library is required to render HAML templates:
120
801163e @bmizerany closes #9779 Auto-require haml/erb/builder/sass
bmizerany authored
121 ## You'll need to require haml in your app
122 require 'haml'
123
df800b5 Docs are started
Blake Mizerany authored
124 get '/' do
125 haml :index
126 end
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
127
128 Renders <tt>./views/index.haml</tt>.
129
d359dc9 @kematzy Merge app-level haml/sass options with call options [#184]
kematzy authored
130 {Haml's options}[http://haml.hamptoncatlin.com/docs/rdoc/classes/Haml.html]
131 can be set globally through Sinatra's configurations,
132 see {Options and Configurations}[http://www.sinatrarb.com/configuration.html],
133 and overridden on an individual basis.
134
135 set :haml, {:format => :html5 } # default Haml format is :xhtml
136
137 get '/' do
138 haml :index, :haml_options => {:format => :html4 } # overridden
139 end
140
141
17cb177 @cypher README and CHANGES tweaks for 0.9.0 release (#63)
cypher authored
142 === Erb Templates
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
143
801163e @bmizerany closes #9779 Auto-require haml/erb/builder/sass
bmizerany authored
144 ## You'll need to require erb in your app
145 require 'erb'
146
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
147 get '/' do
148 erb :index
149 end
150
151 Renders <tt>./views/index.erb</tt>
152
7c5d693 @sr Doc for erubis
sr authored
153 === Erubis
154
155 The erubis gem/library is required to render builder templates:
156
157 ## You'll need to require erubis in your app
158 require 'erubis'
159
160 get '/' do
161 erubis :index
162 end
163
164 Renders <tt>./views/index.erubis</tt>
165
17cb177 @cypher README and CHANGES tweaks for 0.9.0 release (#63)
cypher authored
166 === Builder Templates
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
167
17cb177 @cypher README and CHANGES tweaks for 0.9.0 release (#63)
cypher authored
168 The builder gem/library is required to render builder templates:
df800b5 Docs are started
Blake Mizerany authored
169
801163e @bmizerany closes #9779 Auto-require haml/erb/builder/sass
bmizerany authored
170 ## You'll need to require builder in your app
171 require 'builder'
172
17cb177 @cypher README and CHANGES tweaks for 0.9.0 release (#63)
cypher authored
173 get '/' do
174 content_type 'application/xml', :charset => 'utf-8'
175 builder :index
176 end
177
178 Renders <tt>./views/index.builder</tt>.
179
180 === Sass Templates
181
182 The sass gem/library is required to render Sass templates:
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
183
801163e @bmizerany closes #9779 Auto-require haml/erb/builder/sass
bmizerany authored
184 ## You'll need to require haml or sass in your app
185 require 'sass'
186
4144ac1 @nmeans Added Sass information to documentation.
nmeans authored
187 get '/stylesheet.css' do
ccc19b0 @rtomayko content_type response helper with mime type lookup and parameter supp…
rtomayko authored
188 content_type 'text/css', :charset => 'utf-8'
4144ac1 @nmeans Added Sass information to documentation.
nmeans authored
189 sass :stylesheet
190 end
191
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
192 Renders <tt>./views/stylesheet.sass</tt>.
193
d359dc9 @kematzy Merge app-level haml/sass options with call options [#184]
kematzy authored
194 {Sass' options}[http://haml.hamptoncatlin.com/docs/rdoc/classes/Sass.html]
195 can be set globally through Sinatra's configurations,
196 see {Options and Configurations}[http://www.sinatrarb.com/configuration.html],
197 and overridden on an individual basis.
198
199 set :sass, {:style => :compact } # default Sass style is :nested
200
201 get '/stylesheet.css' do
202 content_type 'text/css', :charset => 'utf-8'
b90d00c @sr Update sass example re. options
sr authored
203 sass :stylesheet, :style => :expanded # overridden
d359dc9 @kematzy Merge app-level haml/sass options with call options [#184]
kematzy authored
204 end
205
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
206 === Inline Templates
df800b5 Docs are started
Blake Mizerany authored
207
208 get '/' do
209 haml '%div.title Hello World'
210 end
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
211
212 Renders the inlined template string.
df800b5 Docs are started
Blake Mizerany authored
213
4298a77 @rtomayko Tweak README formatting; move community/contributing to website
rtomayko authored
214 === Accessing Variables in Templates
df800b5 Docs are started
Blake Mizerany authored
215
5018264 @rtomayko Tidy up README a bit; link to @sinatra on Twitter
rtomayko authored
216 Templates are evaluated within the same context as route handlers. Instance
217 variables set in route handlers are direcly accessible by templates:
df800b5 Docs are started
Blake Mizerany authored
218
219 get '/:id' do
220 @foo = Foo.find(params[:id])
95aca76 @bleything fix documentation of variable interpolation into templates
bleything authored
221 haml '%h1= @foo.name'
df800b5 Docs are started
Blake Mizerany authored
222 end
223
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
224 Or, specify an explicit Hash of local variables:
df800b5 Docs are started
Blake Mizerany authored
225
226 get '/:id' do
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
227 foo = Foo.find(params[:id])
95aca76 @bleything fix documentation of variable interpolation into templates
bleything authored
228 haml '%h1= foo.name', :locals => { :foo => foo }
df800b5 Docs are started
Blake Mizerany authored
229 end
230
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
231 This is typically used when rendering templates as partials from within
232 other templates.
233
3ef8eed @sr Deprecate use_in_file_templates!
sr authored
234 === Inline Templates
83cba9c @bmizerany updated README with helpful tidbits
bmizerany authored
235
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
236 Templates may be defined at the end of the source file:
83cba9c @bmizerany updated README with helpful tidbits
bmizerany authored
237
eec7d21 @bmizerany In-file-templates are automaticly loaded for you.
bmizerany authored
238 require 'rubygems'
239 require 'sinatra'
240
83cba9c @bmizerany updated README with helpful tidbits
bmizerany authored
241 get '/' do
242 haml :index
243 end
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
244
83cba9c @bmizerany updated README with helpful tidbits
bmizerany authored
245 __END__
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
246
f71330e @bmizerany quick doc fix
bmizerany authored
247 @@ layout
17cb177 @cypher README and CHANGES tweaks for 0.9.0 release (#63)
cypher authored
248 %html
249 = yield
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
250
f71330e @bmizerany quick doc fix
bmizerany authored
251 @@ index
83cba9c @bmizerany updated README with helpful tidbits
bmizerany authored
252 %div.title Hello world!!!!!
253
3ef8eed @sr Deprecate use_in_file_templates!
sr authored
254 NOTE: Inline templates defined in the source file that requires sinatra
255 are automatically loaded. Call `enable :inline_templates` explicitly if you
256 have inline templates in other source files.
eec7d21 @bmizerany In-file-templates are automaticly loaded for you.
bmizerany authored
257
4298a77 @rtomayko Tweak README formatting; move community/contributing to website
rtomayko authored
258 === Named Templates
259
5018264 @rtomayko Tidy up README a bit; link to @sinatra on Twitter
rtomayko authored
260 Templates may also be defined using the top-level <tt>template</tt> method:
83cba9c @bmizerany updated README with helpful tidbits
bmizerany authored
261
262 template :layout do
17cb177 @cypher README and CHANGES tweaks for 0.9.0 release (#63)
cypher authored
263 "%html\n =yield\n"
83cba9c @bmizerany updated README with helpful tidbits
bmizerany authored
264 end
265
266 template :index do
267 '%div.title Hello World!'
268 end
269
270 get '/' do
271 haml :index
272 end
273
17cb177 @cypher README and CHANGES tweaks for 0.9.0 release (#63)
cypher authored
274 If a template named "layout" exists, it will be used each time a template
275 is rendered. You can disable layouts by passing <tt>:layout => false</tt>.
578bbab @djanowski Updating README for :layout => true.
djanowski authored
276
277 get '/' do
278 haml :index, :layout => !request.xhr?
279 end
280
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
281 == Helpers
df800b5 Docs are started
Blake Mizerany authored
282
17cb177 @cypher README and CHANGES tweaks for 0.9.0 release (#63)
cypher authored
283 Use the top-level <tt>helpers</tt> method to define helper methods for use in
5018264 @rtomayko Tidy up README a bit; link to @sinatra on Twitter
rtomayko authored
284 route handlers and templates:
df800b5 Docs are started
Blake Mizerany authored
285
286 helpers do
287 def bar(name)
288 "#{name}bar"
289 end
290 end
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
291
1776a80 Added Version and Docs
Blake Mizerany authored
292 get '/:name' do
293 bar(params[:name])
294 end
df800b5 Docs are started
Blake Mizerany authored
295
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
296 == Filters
df800b5 Docs are started
Blake Mizerany authored
297
17cb177 @cypher README and CHANGES tweaks for 0.9.0 release (#63)
cypher authored
298 Before filters are evaluated before each request within the context of the
299 request and can modify the request and response. Instance variables set in
5018264 @rtomayko Tidy up README a bit; link to @sinatra on Twitter
rtomayko authored
300 filters are accessible by routes and templates:
1776a80 Added Version and Docs
Blake Mizerany authored
301
df800b5 Docs are started
Blake Mizerany authored
302 before do
a734cf3 @rtomayko I knew I shoulda taken that left turn at Hoboken
rtomayko authored
303 @note = 'Hi!'
304 request.path_info = '/foo/bar/baz'
305 end
306
307 get '/foo/*' do
308 @note #=> 'Hi!'
309 params[:splat] #=> 'bar/baz'
df800b5 Docs are started
Blake Mizerany authored
310 end
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
311
4e50ddb @jschementi Adds after filters
jschementi authored
312 After filter are evaluated after each request within the context of the
03dcff7 @rtomayko Typo in README
rtomayko authored
313 request and can also modify the request and response. Instance variables
4e50ddb @jschementi Adds after filters
jschementi authored
314 set in before filters and routes are accessible by after filters:
315
316 after do
317 puts response.status
318 end
319
17cb177 @cypher README and CHANGES tweaks for 0.9.0 release (#63)
cypher authored
320 == Halting
a734cf3 @rtomayko I knew I shoulda taken that left turn at Hoboken
rtomayko authored
321
4e50ddb @jschementi Adds after filters
jschementi authored
322 To immediately stop a request within a filter or route use:
df800b5 Docs are started
Blake Mizerany authored
323
17cb177 @cypher README and CHANGES tweaks for 0.9.0 release (#63)
cypher authored
324 halt
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
325
fbbd822 @sr More 'halt' doc
sr authored
326 You can also specify the status when halting ...
327
328 halt 410
329
330 Or the body ...
df800b5 Docs are started
Blake Mizerany authored
331
17cb177 @cypher README and CHANGES tweaks for 0.9.0 release (#63)
cypher authored
332 halt 'this will be the body'
df800b5 Docs are started
Blake Mizerany authored
333
fbbd822 @sr More 'halt' doc
sr authored
334 Or both ...
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
335
17cb177 @cypher README and CHANGES tweaks for 0.9.0 release (#63)
cypher authored
336 halt 401, 'go away!'
df800b5 Docs are started
Blake Mizerany authored
337
fbbd822 @sr More 'halt' doc
sr authored
338 With headers ...
339
340 halt 402, {'Content-Type' => 'text/plain'}, 'revenge'
341
17cb177 @cypher README and CHANGES tweaks for 0.9.0 release (#63)
cypher authored
342 == Passing
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
343
5018264 @rtomayko Tidy up README a bit; link to @sinatra on Twitter
rtomayko authored
344 A route can punt processing to the next matching route using <tt>pass</tt>:
df800b5 Docs are started
Blake Mizerany authored
345
17cb177 @cypher README and CHANGES tweaks for 0.9.0 release (#63)
cypher authored
346 get '/guess/:who' do
347 pass unless params[:who] == 'Frank'
6c9488e @sr Stick to single quote; kill a blank line
sr authored
348 'You got me!'
17cb177 @cypher README and CHANGES tweaks for 0.9.0 release (#63)
cypher authored
349 end
350
351 get '/guess/*' do
6c9488e @sr Stick to single quote; kill a blank line
sr authored
352 'You missed!'
17cb177 @cypher README and CHANGES tweaks for 0.9.0 release (#63)
cypher authored
353 end
354
355 The route block is immediately exited and control continues with the next
356 matching route. If no matching route is found, a 404 is returned.
df800b5 Docs are started
Blake Mizerany authored
357
13fc79d @rtomayko Remove support for source file reloading [#166]
rtomayko authored
358 == Configuration
1776a80 Added Version and Docs
Blake Mizerany authored
359
17cb177 @cypher README and CHANGES tweaks for 0.9.0 release (#63)
cypher authored
360 Run once, at startup, in any environment:
1776a80 Added Version and Docs
Blake Mizerany authored
361
362 configure do
e75f4b3 @rtomayko misc README formatting tweaks
rtomayko authored
363 ...
1776a80 Added Version and Docs
Blake Mizerany authored
364 end
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
365
17cb177 @cypher README and CHANGES tweaks for 0.9.0 release (#63)
cypher authored
366 Run only when the environment (RACK_ENV environment variable) is set to
13fc79d @rtomayko Remove support for source file reloading [#166]
rtomayko authored
367 <tt>:production</tt>:
1776a80 Added Version and Docs
Blake Mizerany authored
368
369 configure :production do
e75f4b3 @rtomayko misc README formatting tweaks
rtomayko authored
370 ...
1776a80 Added Version and Docs
Blake Mizerany authored
371 end
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
372
13fc79d @rtomayko Remove support for source file reloading [#166]
rtomayko authored
373 Run when the environment is set to either <tt>:production</tt> or
374 <tt>:test</tt>:
1776a80 Added Version and Docs
Blake Mizerany authored
375
376 configure :production, :test do
e75f4b3 @rtomayko misc README formatting tweaks
rtomayko authored
377 ...
1776a80 Added Version and Docs
Blake Mizerany authored
378 end
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
379
e75f4b3 @rtomayko misc README formatting tweaks
rtomayko authored
380 == Error handling
1776a80 Added Version and Docs
Blake Mizerany authored
381
17cb177 @cypher README and CHANGES tweaks for 0.9.0 release (#63)
cypher authored
382 Error handlers run within the same context as routes and before filters, which
383 means you get all the goodies it has to offer, like <tt>haml</tt>, <tt>erb</tt>,
384 <tt>halt</tt>, etc.
1776a80 Added Version and Docs
Blake Mizerany authored
385
e75f4b3 @rtomayko misc README formatting tweaks
rtomayko authored
386 === Not Found
1776a80 Added Version and Docs
Blake Mizerany authored
387
17cb177 @cypher README and CHANGES tweaks for 0.9.0 release (#63)
cypher authored
388 When a <tt>Sinatra::NotFound</tt> exception is raised, or the response's status
389 code is 404, the <tt>not_found</tt> handler is invoked:
1776a80 Added Version and Docs
Blake Mizerany authored
390
391 not_found do
392 'This is nowhere to be found'
393 end
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
394
e75f4b3 @rtomayko misc README formatting tweaks
rtomayko authored
395 === Error
83cba9c @bmizerany updated README with helpful tidbits
bmizerany authored
396
17cb177 @cypher README and CHANGES tweaks for 0.9.0 release (#63)
cypher authored
397 The +error+ handler is invoked any time an exception is raised from a route
63fd773 @sr Small doc fix re. after filter
sr authored
398 block or a filter. The exception object can be obtained from the
4298a77 @rtomayko Tweak README formatting; move community/contributing to website
rtomayko authored
399 <tt>sinatra.error</tt> Rack variable:
83cba9c @bmizerany updated README with helpful tidbits
bmizerany authored
400
1776a80 Added Version and Docs
Blake Mizerany authored
401 error do
17cb177 @cypher README and CHANGES tweaks for 0.9.0 release (#63)
cypher authored
402 'Sorry there was a nasty error - ' + env['sinatra.error'].name
83cba9c @bmizerany updated README with helpful tidbits
bmizerany authored
403 end
404
e75f4b3 @rtomayko misc README formatting tweaks
rtomayko authored
405 Custom errors:
83cba9c @bmizerany updated README with helpful tidbits
bmizerany authored
406
407 error MyCustomError do
e7e0e55 @rtomayko Minor docfixes in README.rdoc
rtomayko authored
408 'So what happened was...' + request.env['sinatra.error'].message
1776a80 Added Version and Docs
Blake Mizerany authored
409 end
83cba9c @bmizerany updated README with helpful tidbits
bmizerany authored
410
e75f4b3 @rtomayko misc README formatting tweaks
rtomayko authored
411 Then, if this happens:
83cba9c @bmizerany updated README with helpful tidbits
bmizerany authored
412
413 get '/' do
414 raise MyCustomError, 'something bad'
415 end
416
e75f4b3 @rtomayko misc README formatting tweaks
rtomayko authored
417 You get this:
83cba9c @bmizerany updated README with helpful tidbits
bmizerany authored
418
419 So what happened was... something bad
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
420
59e797e @sr Doc for error(500) { }
sr authored
421 Alternatively, you can install error handler for a status code:
422
423 error 403 do
424 'Access forbidden'
425 end
426
427 get '/secret' do
428 403
429 end
430
431 Or a range:
432
433 error 400..510 do
434 'Boom'
435 end
436
4298a77 @rtomayko Tweak README formatting; move community/contributing to website
rtomayko authored
437 Sinatra installs special <tt>not_found</tt> and <tt>error</tt> handlers when
438 running under the development environment.
83cba9c @bmizerany updated README with helpful tidbits
bmizerany authored
439
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
440 == Mime types
441
17cb177 @cypher README and CHANGES tweaks for 0.9.0 release (#63)
cypher authored
442 When using <tt>send_file</tt> or static files you may have mime types Sinatra
6d8b333 @sr Update README re. mime_type
sr authored
443 doesn't understand. Use +mime_type+ to register them by file extension:
83cba9c @bmizerany updated README with helpful tidbits
bmizerany authored
444
6d8b333 @sr Update README re. mime_type
sr authored
445 mime_type :foo, 'text/foo'
1776a80 Added Version and Docs
Blake Mizerany authored
446
cb8fcb6 @sr Doc for content_type :foo
sr authored
447 You can also use it with the +content_type+ helper:
448
449 content_type :foo
450
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
451 == Rack Middleware
bda21f1 @rtomayko add doc on using Rack middleware to README
rtomayko authored
452
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
453 Sinatra rides on Rack[http://rack.rubyforge.org/], a minimal standard
454 interface for Ruby web frameworks. One of Rack's most interesting capabilities
455 for application developers is support for "middleware" -- components that sit
456 between the server and your application monitoring and/or manipulating the
457 HTTP request/response to provide various types of common functionality.
bda21f1 @rtomayko add doc on using Rack middleware to README
rtomayko authored
458
e75f4b3 @rtomayko misc README formatting tweaks
rtomayko authored
459 Sinatra makes building Rack middleware pipelines a cinch via a top-level
460 +use+ method:
bda21f1 @rtomayko add doc on using Rack middleware to README
rtomayko authored
461
462 require 'sinatra'
463 require 'my_custom_middleware'
464
465 use Rack::Lint
466 use MyCustomMiddleware
467
468 get '/hello' do
469 'Hello World'
470 end
471
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
472 The semantics of +use+ are identical to those defined for the
473 Rack::Builder[http://rack.rubyforge.org/doc/classes/Rack/Builder.html] DSL
474 (most frequently used from rackup files). For example, the +use+ method
475 accepts multiple/variable args as well as blocks:
bda21f1 @rtomayko add doc on using Rack middleware to README
rtomayko authored
476
477 use Rack::Auth::Basic do |username, password|
478 username == 'admin' && password == 'secret'
479 end
480
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
481 Rack is distributed with a variety of standard middleware for logging,
482 debugging, URL routing, authentication, and session handling. Sinatra uses
483 many of of these components automatically based on configuration so you
484 typically don't have to +use+ them explicitly.
bda21f1 @rtomayko add doc on using Rack middleware to README
rtomayko authored
485
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
486 == Testing
1776a80 Added Version and Docs
Blake Mizerany authored
487
c831278 @rtomayko Recommend Rack::Test in README / note Sinatra::Test deprecation
rtomayko authored
488 Sinatra tests can be written using any Rack-based testing library
489 or framework. {Rack::Test}[http://gitrdoc.com/brynary/rack-test] is
490 recommended:
c00a25e @rtomayko Test framework refactoring
rtomayko authored
491
7cfe04a @jcrosby Fix for test/unit and test/spec docs
jcrosby authored
492 require 'my_sinatra_app'
c831278 @rtomayko Recommend Rack::Test in README / note Sinatra::Test deprecation
rtomayko authored
493 require 'rack/test'
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
494
1776a80 Added Version and Docs
Blake Mizerany authored
495 class MyAppTest < Test::Unit::TestCase
c831278 @rtomayko Recommend Rack::Test in README / note Sinatra::Test deprecation
rtomayko authored
496 include Rack::Test::Methods
497
498 def app
499 Sinatra::Application
500 end
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
501
2f377e2 @rtomayko Trim down Testing section in the README; link to doc site instead
rtomayko authored
502 def test_my_default
c00a25e @rtomayko Test framework refactoring
rtomayko authored
503 get '/'
c831278 @rtomayko Recommend Rack::Test in README / note Sinatra::Test deprecation
rtomayko authored
504 assert_equal 'Hello World!', last_response.body
1776a80 Added Version and Docs
Blake Mizerany authored
505 end
10c90d5 @sr document testing with rspec
sr authored
506
2f377e2 @rtomayko Trim down Testing section in the README; link to doc site instead
rtomayko authored
507 def test_with_params
c831278 @rtomayko Recommend Rack::Test in README / note Sinatra::Test deprecation
rtomayko authored
508 get '/meet', :name => 'Frank'
509 assert_equal 'Hello Frank!', last_response.body
10c90d5 @sr document testing with rspec
sr authored
510 end
511
2f377e2 @rtomayko Trim down Testing section in the README; link to doc site instead
rtomayko authored
512 def test_with_rack_env
c831278 @rtomayko Recommend Rack::Test in README / note Sinatra::Test deprecation
rtomayko authored
513 get '/', {}, 'HTTP_USER_AGENT' => 'Songbird'
514 assert_equal "You're using Songbird!", last_response.body
1fb5b99 @dylanegan Bacon support
dylanegan authored
515 end
516 end
517
c831278 @rtomayko Recommend Rack::Test in README / note Sinatra::Test deprecation
rtomayko authored
518 NOTE: The built-in Sinatra::Test module and Sinatra::TestHarness class
519 are deprecated as of the 0.9.2 release.
1776a80 Added Version and Docs
Blake Mizerany authored
520
5360333 @sr Add a note about Sinatra::Base to the README
sr authored
521 == Sinatra::Base - Middleware, Libraries, and Modular Apps
522
523 Defining your app at the top-level works well for micro-apps but has
524 considerable drawbacks when building reuseable components such as Rack
525 middleware, Rails metal, simple libraries with a server component, or
526 even Sinatra extensions. The top-level DSL pollutes the Object namespace
527 and assumes a micro-app style configuration (e.g., a single application
528 file, ./public and ./views directories, logging, exception detail page,
529 etc.). That's where Sinatra::Base comes into play:
530
531 require 'sinatra/base'
532
533 class MyApp < Sinatra::Base
534 set :sessions, true
535 set :foo, 'bar'
536
537 get '/' do
538 'Hello world!'
539 end
540 end
541
542 The MyApp class is an independent Rack component that can act as
543 Rack middleware, a Rack application, or Rails metal. You can +use+ or
544 +run+ this class from a rackup +config.ru+ file; or, control a server
545 component shipped as a library:
546
547 MyApp.run! :host => 'localhost', :port => 9090
548
549 The methods available to Sinatra::Base subclasses are exactly as those
550 available via the top-level DSL. Most top-level apps can be converted to
551 Sinatra::Base components with two modifications:
552
553 * Your file should require +sinatra/base+ instead of +sinatra+;
554 otherwise, all of Sinatra's DSL methods are imported into the main
555 namespace.
556 * Put your app's routes, error handlers, filters, and options in a subclass
557 of Sinatra::Base.
558
559 +Sinatra::Base+ is a blank slate. Most options are disabled by default,
560 including the built-in server. See {Options and Configuration}[http://sinatra.github.com/configuration.html]
561 for details on available options and their behavior.
562
563 SIDEBAR: Sinatra's top-level DSL is implemented using a simple delegation
564 system. The +Sinatra::Application+ class -- a special subclass of
565 Sinatra::Base -- receives all :get, :put, :post, :delete, :before,
566 :error, :not_found, :configure, and :set messages sent to the
567 top-level. Have a look at the code for yourself: here's the
568 {Sinatra::Delegator mixin}[http://github.com/sinatra/sinatra/blob/master/lib/sinatra/base.rb#L1064]
569 being {included into the main namespace}[http://github.com/sinatra/sinatra/blob/master/lib/sinatra/main.rb#L25].
570
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
571 == Command line
1776a80 Added Version and Docs
Blake Mizerany authored
572
e75f4b3 @rtomayko misc README formatting tweaks
rtomayko authored
573 Sinatra applications can be run directly:
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
574
4d61607 @sr update README/CHANGES re. -o
sr authored
575 ruby myapp.rb [-h] [-x] [-e ENVIRONMENT] [-p PORT] [-o HOST] [-s HANDLER]
1776a80 Added Version and Docs
Blake Mizerany authored
576
577 Options are:
578
579 -h # help
580 -p # set the port (default is 4567)
4d61607 @sr update README/CHANGES re. -o
sr authored
581 -o # set the host (default is 0.0.0.0)
1776a80 Added Version and Docs
Blake Mizerany authored
582 -e # set the environment (default is development)
f29486b @karmi Note "-s" (server) command line option in README
karmi authored
583 -s # specify rack server/handler (default is thin)
e7e0e55 @rtomayko Minor docfixes in README.rdoc
rtomayko authored
584 -x # turn on the mutex lock (default is off)
1776a80 Added Version and Docs
Blake Mizerany authored
585
4298a77 @rtomayko Tweak README formatting; move community/contributing to website
rtomayko authored
586 == The Bleeding Edge
6326809 @cypher Add a subsection about tools needed for Sinatra to the Contributing s…
cypher authored
587
4298a77 @rtomayko Tweak README formatting; move community/contributing to website
rtomayko authored
588 If you would like to use Sinatra's latest bleeding code, create a local
589 clone and run your app with the <tt>sinatra/lib</tt> directory on the
590 <tt>LOAD_PATH</tt>:
6326809 @cypher Add a subsection about tools needed for Sinatra to the Contributing s…
cypher authored
591
4298a77 @rtomayko Tweak README formatting; move community/contributing to website
rtomayko authored
592 cd myapp
ba92616 @bmizerany Updated README to point to github.com/sinatra/sinatra.git
bmizerany authored
593 git clone git://github.com/sinatra/sinatra.git
4298a77 @rtomayko Tweak README formatting; move community/contributing to website
rtomayko authored
594 ruby -Isinatra/lib myapp.rb
480fbfa @rtomayko minor formatting tweaks to cypher's README updates
rtomayko authored
595
4f30c1c fix unclosed <tt> in README
Mathew Cucuzella authored
596 Alternatively, you can add the <tt>sinatra/lib</tt> directory to the
4298a77 @rtomayko Tweak README formatting; move community/contributing to website
rtomayko authored
597 <tt>LOAD_PATH</tt> in your application:
1776a80 Added Version and Docs
Blake Mizerany authored
598
17cb177 @cypher README and CHANGES tweaks for 0.9.0 release (#63)
cypher authored
599 $LOAD_PATH.unshift File.dirname(__FILE__) + '/sinatra/lib'
4298a77 @rtomayko Tweak README formatting; move community/contributing to website
rtomayko authored
600 require 'rubygems'
1776a80 Added Version and Docs
Blake Mizerany authored
601 require 'sinatra'
602
603 get '/about' do
4298a77 @rtomayko Tweak README formatting; move community/contributing to website
rtomayko authored
604 "I'm running version " + Sinatra::VERSION
1776a80 Added Version and Docs
Blake Mizerany authored
605 end
e6c5471 @cypher Add a community section with info about the mailing list and irc channel
cypher authored
606
4298a77 @rtomayko Tweak README formatting; move community/contributing to website
rtomayko authored
607 To update the Sinatra sources in the future:
d8fec16 @cypher Add subsection about contributing a patch as well as a link to the is…
cypher authored
608
4298a77 @rtomayko Tweak README formatting; move community/contributing to website
rtomayko authored
609 cd myproject/sinatra
610 git pull
e6c5471 @cypher Add a community section with info about the mailing list and irc channel
cypher authored
611
4298a77 @rtomayko Tweak README formatting; move community/contributing to website
rtomayko authored
612 == More
e6c5471 @cypher Add a community section with info about the mailing list and irc channel
cypher authored
613
4298a77 @rtomayko Tweak README formatting; move community/contributing to website
rtomayko authored
614 * {Project Website}[http://sinatra.github.com/] - Additional documentation,
615 news, and links to other resources.
0044683 @Aupajo Fixed broken link in README.
Aupajo authored
616 * {Contributing}[http://sinatra.github.com/contributing.html] - Find a bug? Need
4298a77 @rtomayko Tweak README formatting; move community/contributing to website
rtomayko authored
617 help? Have a patch?
618 * {Lighthouse}[http://sinatra.lighthouseapp.com] - Issue tracking and release
619 planning.
5018264 @rtomayko Tidy up README a bit; link to @sinatra on Twitter
rtomayko authored
620 * {Twitter}[http://twitter.com/sinatra]
4298a77 @rtomayko Tweak README formatting; move community/contributing to website
rtomayko authored
621 * {Mailing List}[http://groups.google.com/group/sinatrarb]
622 * {IRC: #sinatra}[irc://chat.freenode.net/#sinatra] on http://freenode.net
Something went wrong with that request. Please try again.