Skip to content

HTTPS clone URL

Subversion checkout URL

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