Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

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