Skip to content
This repository
Newer
Older
100644 622 lines (431 sloc) 15.459 kb
df800b5c » Blake Mizerany
2008-03-24 Docs are started
1 = Sinatra
2
4c91e540 » watchdogtimer
2009-04-20 Web applications should not be hyphenated
3 Sinatra is a DSL for quickly creating web applications in Ruby with minimal
17cb177e » cypher
2009-01-11 README and CHANGES tweaks for 0.9.0 release (#63)
4 effort:
df800b5c » Blake Mizerany
2008-03-24 Docs are started
5
6 # myapp.rb
7 require 'rubygems'
8 require 'sinatra'
9 get '/' do
10 'Hello world!'
11 end
12
4298a777 » rtomayko
2009-01-23 Tweak README formatting; move community/contributing to website
13 Install the gem and run with:
df800b5c » Blake Mizerany
2008-03-24 Docs are started
14
4298a777 » rtomayko
2009-01-23 Tweak README formatting; move community/contributing to website
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:
df800b5c » Blake Mizerany
2008-03-24 Docs are started
24
25 get '/' do
4298a777 » rtomayko
2009-01-23 Tweak README formatting; move community/contributing to website
26 .. show something ..
df800b5c » Blake Mizerany
2008-03-24 Docs are started
27 end
f44fb6aa » rtomayko
2008-08-31 grammar/formatting pass over README
28
df800b5c » Blake Mizerany
2008-03-24 Docs are started
29 post '/' do
30 .. create something ..
31 end
f44fb6aa » rtomayko
2008-08-31 grammar/formatting pass over README
32
df800b5c » Blake Mizerany
2008-03-24 Docs are started
33 put '/' do
34 .. update something ..
35 end
f44fb6aa » rtomayko
2008-08-31 grammar/formatting pass over README
36
df800b5c » Blake Mizerany
2008-03-24 Docs are started
37 delete '/' do
38 .. annihilate something ..
39 end
f44fb6aa » rtomayko
2008-08-31 grammar/formatting pass over README
40
4298a777 » rtomayko
2009-01-23 Tweak README formatting; move community/contributing to website
41 Routes are matched in the order they are defined. The first route that
f44fb6aa » rtomayko
2008-08-31 grammar/formatting pass over README
42 matches the request is invoked.
1776a80d » Blake Mizerany
2008-03-24 Added Version and Docs
43
17cb177e » cypher
2009-01-11 README and CHANGES tweaks for 0.9.0 release (#63)
44 Route patterns may include named parameters, accessible via the
45 <tt>params</tt> hash:
1776a80d » Blake Mizerany
2008-03-24 Added Version and Docs
46
4298a777 » rtomayko
2009-01-23 Tweak README formatting; move community/contributing to website
47 get '/hello/:name' do
ce0fe87a » scottj97
2009-05-20 fix inaccurate comment in README
48 # matches "GET /hello/foo" and "GET /hello/bar"
a734cf38 » rtomayko
2008-12-13 I knew I shoulda taken that left turn at Hoboken
49 # params[:name] is 'foo' or 'bar'
17cb177e » cypher
2009-01-11 README and CHANGES tweaks for 0.9.0 release (#63)
50 "Hello #{params[:name]}!"
1776a80d » Blake Mizerany
2008-03-24 Added Version and Docs
51 end
f44fb6aa » rtomayko
2008-08-31 grammar/formatting pass over README
52
6569d1b0 » bdimcheff
2009-01-28 Added route block params in routing statements [#140]
53 You can also access named parameters via block parameters:
54
55 get '/hello/:name' do |n|
56 "Hello #{n}!"
57 end
58
17cb177e » cypher
2009-01-11 README and CHANGES tweaks for 0.9.0 release (#63)
59 Route patterns may also include splat (or wildcard) parameters, accessible
60 via the <tt>params[:splat]</tt> array.
1776a80d » Blake Mizerany
2008-03-24 Added Version and Docs
61
9c85e99c » vic
2008-04-24 Specs, documentation and fixes for splat'n routes
62 get '/say/*/to/*' do
63 # matches /say/hello/to/world
a734cf38 » rtomayko
2008-12-13 I knew I shoulda taken that left turn at Hoboken
64 params[:splat] # => ["hello", "world"]
9c85e99c » vic
2008-04-24 Specs, documentation and fixes for splat'n routes
65 end
66
67 get '/download/*.*' do
68 # matches /download/path/to/file.xml
a734cf38 » rtomayko
2008-12-13 I knew I shoulda taken that left turn at Hoboken
69 params[:splat] # => ["path/to/file", "xml"]
1776a80d » Blake Mizerany
2008-03-24 Added Version and Docs
70 end
f44fb6aa » rtomayko
2008-08-31 grammar/formatting pass over README
71
17cb177e » cypher
2009-01-11 README and CHANGES tweaks for 0.9.0 release (#63)
72 Route matching with Regular Expressions:
73
74 get %r{/hello/([\w]+)} do
75 "Hello, #{params[:captures].first}!"
76 end
77
6569d1b0 » bdimcheff
2009-01-28 Added route block params in routing statements [#140]
78 Or with a block parameter:
79
80 get %r{/hello/([\w]+)} do |c|
81 "Hello, #{c}!"
82 end
83
17cb177e » cypher
2009-01-11 README and CHANGES tweaks for 0.9.0 release (#63)
84 Routes may include a variety of matching conditions, such as the user agent:
f44fb6aa » rtomayko
2008-08-31 grammar/formatting pass over README
85
1776a80d » Blake Mizerany
2008-03-24 Added Version and Docs
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
a734cf38 » rtomayko
2008-12-13 I knew I shoulda taken that left turn at Hoboken
91 # Matches non-songbird browsers
1776a80d » Blake Mizerany
2008-03-24 Added Version and Docs
92 end
df800b5c » Blake Mizerany
2008-03-24 Docs are started
93
a734cf38 » rtomayko
2008-12-13 I knew I shoulda taken that left turn at Hoboken
94 == Static Files
047edc6a » Blake Mizerany
2008-03-26 update README with Static help
95
17cb177e » cypher
2009-01-11 README and CHANGES tweaks for 0.9.0 release (#63)
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:
a734cf38 » rtomayko
2008-12-13 I knew I shoulda taken that left turn at Hoboken
98
99 set :public, File.dirname(__FILE__) + '/static'
df800b5c » Blake Mizerany
2008-03-24 Docs are started
100
4298a777 » rtomayko
2009-01-23 Tweak README formatting; move community/contributing to website
101 Note that the public directory name is not included in the URL. A file
85b4462b » rtomayko
2009-01-24 README: fix formatting on static file note
102 <tt>./public/css/style.css</tt> is made available as
103 <tt>http://example.com/css/style.css</tt>.
4298a777 » rtomayko
2009-01-23 Tweak README formatting; move community/contributing to website
104
17cb177e » cypher
2009-01-11 README and CHANGES tweaks for 0.9.0 release (#63)
105 == Views / Templates
df800b5c » Blake Mizerany
2008-03-24 Docs are started
106
4298a777 » rtomayko
2009-01-23 Tweak README formatting; move community/contributing to website
107 Templates are assumed to be located directly under the <tt>./views</tt>
17cb177e » cypher
2009-01-11 README and CHANGES tweaks for 0.9.0 release (#63)
108 directory. To use a different views directory:
a734cf38 » rtomayko
2008-12-13 I knew I shoulda taken that left turn at Hoboken
109
110 set :views, File.dirname(__FILE__) + '/templates'
111
06161bf7 » cypher
2009-03-25 Note on passing template symbols vs. strings in README
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
f44fb6aa » rtomayko
2008-08-31 grammar/formatting pass over README
117 === Haml Templates
df800b5c » Blake Mizerany
2008-03-24 Docs are started
118
17cb177e » cypher
2009-01-11 README and CHANGES tweaks for 0.9.0 release (#63)
119 The haml gem/library is required to render HAML templates:
120
801163e9 » bmizerany
2009-04-24 closes #9779 Auto-require haml/erb/builder/sass
121 ## You'll need to require haml in your app
122 require 'haml'
123
df800b5c » Blake Mizerany
2008-03-24 Docs are started
124 get '/' do
125 haml :index
126 end
f44fb6aa » rtomayko
2008-08-31 grammar/formatting pass over README
127
128 Renders <tt>./views/index.haml</tt>.
129
d359dc9c » kematzy
2009-03-15 Merge app-level haml/sass options with call options [#184]
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
17cb177e » cypher
2009-01-11 README and CHANGES tweaks for 0.9.0 release (#63)
142 === Erb Templates
f44fb6aa » rtomayko
2008-08-31 grammar/formatting pass over README
143
801163e9 » bmizerany
2009-04-24 closes #9779 Auto-require haml/erb/builder/sass
144 ## You'll need to require erb in your app
145 require 'erb'
146
f44fb6aa » rtomayko
2008-08-31 grammar/formatting pass over README
147 get '/' do
148 erb :index
149 end
150
151 Renders <tt>./views/index.erb</tt>
152
7c5d6937 » sr
2009-12-23 Doc for erubis
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
17cb177e » cypher
2009-01-11 README and CHANGES tweaks for 0.9.0 release (#63)
166 === Builder Templates
f44fb6aa » rtomayko
2008-08-31 grammar/formatting pass over README
167
17cb177e » cypher
2009-01-11 README and CHANGES tweaks for 0.9.0 release (#63)
168 The builder gem/library is required to render builder templates:
df800b5c » Blake Mizerany
2008-03-24 Docs are started
169
801163e9 » bmizerany
2009-04-24 closes #9779 Auto-require haml/erb/builder/sass
170 ## You'll need to require builder in your app
171 require 'builder'
172
17cb177e » cypher
2009-01-11 README and CHANGES tweaks for 0.9.0 release (#63)
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:
f44fb6aa » rtomayko
2008-08-31 grammar/formatting pass over README
183
801163e9 » bmizerany
2009-04-24 closes #9779 Auto-require haml/erb/builder/sass
184 ## You'll need to require haml or sass in your app
185 require 'sass'
186
4144ac1a » nmeans
2008-04-08 Added Sass information to documentation.
187 get '/stylesheet.css' do
ccc19b04 » rtomayko
2008-04-13 content_type response helper with mime type lookup and parameter supp…
188 content_type 'text/css', :charset => 'utf-8'
4144ac1a » nmeans
2008-04-08 Added Sass information to documentation.
189 sass :stylesheet
190 end
191
f44fb6aa » rtomayko
2008-08-31 grammar/formatting pass over README
192 Renders <tt>./views/stylesheet.sass</tt>.
193
d359dc9c » kematzy
2009-03-15 Merge app-level haml/sass options with call options [#184]
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'
b90d00c8 » sr
2009-12-19 Update sass example re. options
203 sass :stylesheet, :style => :expanded # overridden
d359dc9c » kematzy
2009-03-15 Merge app-level haml/sass options with call options [#184]
204 end
205
f44fb6aa » rtomayko
2008-08-31 grammar/formatting pass over README
206 === Inline Templates
df800b5c » Blake Mizerany
2008-03-24 Docs are started
207
208 get '/' do
209 haml '%div.title Hello World'
210 end
f44fb6aa » rtomayko
2008-08-31 grammar/formatting pass over README
211
212 Renders the inlined template string.
df800b5c » Blake Mizerany
2008-03-24 Docs are started
213
4298a777 » rtomayko
2009-01-23 Tweak README formatting; move community/contributing to website
214 === Accessing Variables in Templates
df800b5c » Blake Mizerany
2008-03-24 Docs are started
215
5018264d » rtomayko
2009-03-01 Tidy up README a bit; link to @sinatra on Twitter
216 Templates are evaluated within the same context as route handlers. Instance
217 variables set in route handlers are direcly accessible by templates:
df800b5c » Blake Mizerany
2008-03-24 Docs are started
218
219 get '/:id' do
220 @foo = Foo.find(params[:id])
95aca761 » bleything
2008-11-30 fix documentation of variable interpolation into templates
221 haml '%h1= @foo.name'
df800b5c » Blake Mizerany
2008-03-24 Docs are started
222 end
223
f44fb6aa » rtomayko
2008-08-31 grammar/formatting pass over README
224 Or, specify an explicit Hash of local variables:
df800b5c » Blake Mizerany
2008-03-24 Docs are started
225
226 get '/:id' do
f44fb6aa » rtomayko
2008-08-31 grammar/formatting pass over README
227 foo = Foo.find(params[:id])
95aca761 » bleything
2008-11-30 fix documentation of variable interpolation into templates
228 haml '%h1= foo.name', :locals => { :foo => foo }
df800b5c » Blake Mizerany
2008-03-24 Docs are started
229 end
230
f44fb6aa » rtomayko
2008-08-31 grammar/formatting pass over README
231 This is typically used when rendering templates as partials from within
232 other templates.
233
3ef8eede » sr
2009-12-19 Deprecate use_in_file_templates!
234 === Inline Templates
83cba9cf » bmizerany
2008-03-29 updated README with helpful tidbits
235
f44fb6aa » rtomayko
2008-08-31 grammar/formatting pass over README
236 Templates may be defined at the end of the source file:
83cba9cf » bmizerany
2008-03-29 updated README with helpful tidbits
237
eec7d214 » bmizerany
2009-01-16 In-file-templates are automaticly loaded for you.
238 require 'rubygems'
239 require 'sinatra'
240
83cba9cf » bmizerany
2008-03-29 updated README with helpful tidbits
241 get '/' do
242 haml :index
243 end
f44fb6aa » rtomayko
2008-08-31 grammar/formatting pass over README
244
83cba9cf » bmizerany
2008-03-29 updated README with helpful tidbits
245 __END__
f44fb6aa » rtomayko
2008-08-31 grammar/formatting pass over README
246
f71330e6 » bmizerany
2008-05-07 quick doc fix
247 @@ layout
17cb177e » cypher
2009-01-11 README and CHANGES tweaks for 0.9.0 release (#63)
248 %html
249 = yield
f44fb6aa » rtomayko
2008-08-31 grammar/formatting pass over README
250
f71330e6 » bmizerany
2008-05-07 quick doc fix
251 @@ index
83cba9cf » bmizerany
2008-03-29 updated README with helpful tidbits
252 %div.title Hello world!!!!!
253
3ef8eede » sr
2009-12-19 Deprecate use_in_file_templates!
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.
eec7d214 » bmizerany
2009-01-16 In-file-templates are automaticly loaded for you.
257
4298a777 » rtomayko
2009-01-23 Tweak README formatting; move community/contributing to website
258 === Named Templates
259
5018264d » rtomayko
2009-03-01 Tidy up README a bit; link to @sinatra on Twitter
260 Templates may also be defined using the top-level <tt>template</tt> method:
83cba9cf » bmizerany
2008-03-29 updated README with helpful tidbits
261
262 template :layout do
17cb177e » cypher
2009-01-11 README and CHANGES tweaks for 0.9.0 release (#63)
263 "%html\n =yield\n"
83cba9cf » bmizerany
2008-03-29 updated README with helpful tidbits
264 end
265
266 template :index do
267 '%div.title Hello World!'
268 end
269
270 get '/' do
271 haml :index
272 end
273
17cb177e » cypher
2009-01-11 README and CHANGES tweaks for 0.9.0 release (#63)
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>.
578bbabd » djanowski
2009-01-09 Updating README for :layout => true.
276
277 get '/' do
278 haml :index, :layout => !request.xhr?
279 end
280
f44fb6aa » rtomayko
2008-08-31 grammar/formatting pass over README
281 == Helpers
df800b5c » Blake Mizerany
2008-03-24 Docs are started
282
17cb177e » cypher
2009-01-11 README and CHANGES tweaks for 0.9.0 release (#63)
283 Use the top-level <tt>helpers</tt> method to define helper methods for use in
5018264d » rtomayko
2009-03-01 Tidy up README a bit; link to @sinatra on Twitter
284 route handlers and templates:
df800b5c » Blake Mizerany
2008-03-24 Docs are started
285
286 helpers do
287 def bar(name)
288 "#{name}bar"
289 end
290 end
f44fb6aa » rtomayko
2008-08-31 grammar/formatting pass over README
291
1776a80d » Blake Mizerany
2008-03-24 Added Version and Docs
292 get '/:name' do
293 bar(params[:name])
294 end
df800b5c » Blake Mizerany
2008-03-24 Docs are started
295
f44fb6aa » rtomayko
2008-08-31 grammar/formatting pass over README
296 == Filters
df800b5c » Blake Mizerany
2008-03-24 Docs are started
297
17cb177e » cypher
2009-01-11 README and CHANGES tweaks for 0.9.0 release (#63)
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
5018264d » rtomayko
2009-03-01 Tidy up README a bit; link to @sinatra on Twitter
300 filters are accessible by routes and templates:
1776a80d » Blake Mizerany
2008-03-24 Added Version and Docs
301
df800b5c » Blake Mizerany
2008-03-24 Docs are started
302 before do
a734cf38 » rtomayko
2008-12-13 I knew I shoulda taken that left turn at Hoboken
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'
df800b5c » Blake Mizerany
2008-03-24 Docs are started
310 end
f44fb6aa » rtomayko
2008-08-31 grammar/formatting pass over README
311
4e50ddbc » jschementi
2008-12-21 Adds after filters
312 After filter are evaluated after each request within the context of the
03dcff73 » rtomayko
2009-12-13 Typo in README
313 request and can also modify the request and response. Instance variables
4e50ddbc » jschementi
2008-12-21 Adds after filters
314 set in before filters and routes are accessible by after filters:
315
316 after do
317 puts response.status
318 end
319
17cb177e » cypher
2009-01-11 README and CHANGES tweaks for 0.9.0 release (#63)
320 == Halting
a734cf38 » rtomayko
2008-12-13 I knew I shoulda taken that left turn at Hoboken
321
4e50ddbc » jschementi
2008-12-21 Adds after filters
322 To immediately stop a request within a filter or route use:
df800b5c » Blake Mizerany
2008-03-24 Docs are started
323
17cb177e » cypher
2009-01-11 README and CHANGES tweaks for 0.9.0 release (#63)
324 halt
f44fb6aa » rtomayko
2008-08-31 grammar/formatting pass over README
325
fbbd8227 » sr
2009-12-19 More 'halt' doc
326 You can also specify the status when halting ...
327
328 halt 410
329
330 Or the body ...
df800b5c » Blake Mizerany
2008-03-24 Docs are started
331
17cb177e » cypher
2009-01-11 README and CHANGES tweaks for 0.9.0 release (#63)
332 halt 'this will be the body'
df800b5c » Blake Mizerany
2008-03-24 Docs are started
333
fbbd8227 » sr
2009-12-19 More 'halt' doc
334 Or both ...
f44fb6aa » rtomayko
2008-08-31 grammar/formatting pass over README
335
17cb177e » cypher
2009-01-11 README and CHANGES tweaks for 0.9.0 release (#63)
336 halt 401, 'go away!'
df800b5c » Blake Mizerany
2008-03-24 Docs are started
337
fbbd8227 » sr
2009-12-19 More 'halt' doc
338 With headers ...
339
340 halt 402, {'Content-Type' => 'text/plain'}, 'revenge'
341
17cb177e » cypher
2009-01-11 README and CHANGES tweaks for 0.9.0 release (#63)
342 == Passing
f44fb6aa » rtomayko
2008-08-31 grammar/formatting pass over README
343
5018264d » rtomayko
2009-03-01 Tidy up README a bit; link to @sinatra on Twitter
344 A route can punt processing to the next matching route using <tt>pass</tt>:
df800b5c » Blake Mizerany
2008-03-24 Docs are started
345
17cb177e » cypher
2009-01-11 README and CHANGES tweaks for 0.9.0 release (#63)
346 get '/guess/:who' do
347 pass unless params[:who] == 'Frank'
6c9488e2 » sr
2009-12-23 Stick to single quote; kill a blank line
348 'You got me!'
17cb177e » cypher
2009-01-11 README and CHANGES tweaks for 0.9.0 release (#63)
349 end
350
351 get '/guess/*' do
6c9488e2 » sr
2009-12-23 Stick to single quote; kill a blank line
352 'You missed!'
17cb177e » cypher
2009-01-11 README and CHANGES tweaks for 0.9.0 release (#63)
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.
df800b5c » Blake Mizerany
2008-03-24 Docs are started
357
13fc79d3 » rtomayko
2009-03-24 Remove support for source file reloading [#166]
358 == Configuration
1776a80d » Blake Mizerany
2008-03-24 Added Version and Docs
359
17cb177e » cypher
2009-01-11 README and CHANGES tweaks for 0.9.0 release (#63)
360 Run once, at startup, in any environment:
1776a80d » Blake Mizerany
2008-03-24 Added Version and Docs
361
362 configure do
e75f4b3f » rtomayko
2008-09-09 misc README formatting tweaks
363 ...
1776a80d » Blake Mizerany
2008-03-24 Added Version and Docs
364 end
f44fb6aa » rtomayko
2008-08-31 grammar/formatting pass over README
365
17cb177e » cypher
2009-01-11 README and CHANGES tweaks for 0.9.0 release (#63)
366 Run only when the environment (RACK_ENV environment variable) is set to
13fc79d3 » rtomayko
2009-03-24 Remove support for source file reloading [#166]
367 <tt>:production</tt>:
1776a80d » Blake Mizerany
2008-03-24 Added Version and Docs
368
369 configure :production do
e75f4b3f » rtomayko
2008-09-09 misc README formatting tweaks
370 ...
1776a80d » Blake Mizerany
2008-03-24 Added Version and Docs
371 end
f44fb6aa » rtomayko
2008-08-31 grammar/formatting pass over README
372
13fc79d3 » rtomayko
2009-03-24 Remove support for source file reloading [#166]
373 Run when the environment is set to either <tt>:production</tt> or
374 <tt>:test</tt>:
1776a80d » Blake Mizerany
2008-03-24 Added Version and Docs
375
376 configure :production, :test do
e75f4b3f » rtomayko
2008-09-09 misc README formatting tweaks
377 ...
1776a80d » Blake Mizerany
2008-03-24 Added Version and Docs
378 end
f44fb6aa » rtomayko
2008-08-31 grammar/formatting pass over README
379
e75f4b3f » rtomayko
2008-09-09 misc README formatting tweaks
380 == Error handling
1776a80d » Blake Mizerany
2008-03-24 Added Version and Docs
381
17cb177e » cypher
2009-01-11 README and CHANGES tweaks for 0.9.0 release (#63)
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.
1776a80d » Blake Mizerany
2008-03-24 Added Version and Docs
385
e75f4b3f » rtomayko
2008-09-09 misc README formatting tweaks
386 === Not Found
1776a80d » Blake Mizerany
2008-03-24 Added Version and Docs
387
17cb177e » cypher
2009-01-11 README and CHANGES tweaks for 0.9.0 release (#63)
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:
1776a80d » Blake Mizerany
2008-03-24 Added Version and Docs
390
391 not_found do
392 'This is nowhere to be found'
393 end
f44fb6aa » rtomayko
2008-08-31 grammar/formatting pass over README
394
e75f4b3f » rtomayko
2008-09-09 misc README formatting tweaks
395 === Error
83cba9cf » bmizerany
2008-03-29 updated README with helpful tidbits
396
17cb177e » cypher
2009-01-11 README and CHANGES tweaks for 0.9.0 release (#63)
397 The +error+ handler is invoked any time an exception is raised from a route
63fd7734 » sr
2009-12-19 Small doc fix re. after filter
398 block or a filter. The exception object can be obtained from the
4298a777 » rtomayko
2009-01-23 Tweak README formatting; move community/contributing to website
399 <tt>sinatra.error</tt> Rack variable:
83cba9cf » bmizerany
2008-03-29 updated README with helpful tidbits
400
1776a80d » Blake Mizerany
2008-03-24 Added Version and Docs
401 error do
17cb177e » cypher
2009-01-11 README and CHANGES tweaks for 0.9.0 release (#63)
402 'Sorry there was a nasty error - ' + env['sinatra.error'].name
83cba9cf » bmizerany
2008-03-29 updated README with helpful tidbits
403 end
404
e75f4b3f » rtomayko
2008-09-09 misc README formatting tweaks
405 Custom errors:
83cba9cf » bmizerany
2008-03-29 updated README with helpful tidbits
406
407 error MyCustomError do
e7e0e558 » rtomayko
2008-04-14 Minor docfixes in README.rdoc
408 'So what happened was...' + request.env['sinatra.error'].message
1776a80d » Blake Mizerany
2008-03-24 Added Version and Docs
409 end
83cba9cf » bmizerany
2008-03-29 updated README with helpful tidbits
410
e75f4b3f » rtomayko
2008-09-09 misc README formatting tweaks
411 Then, if this happens:
83cba9cf » bmizerany
2008-03-29 updated README with helpful tidbits
412
413 get '/' do
414 raise MyCustomError, 'something bad'
415 end
416
e75f4b3f » rtomayko
2008-09-09 misc README formatting tweaks
417 You get this:
83cba9cf » bmizerany
2008-03-29 updated README with helpful tidbits
418
419 So what happened was... something bad
f44fb6aa » rtomayko
2008-08-31 grammar/formatting pass over README
420
59e797e9 » sr
2009-12-23 Doc for error(500) { }
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
4298a777 » rtomayko
2009-01-23 Tweak README formatting; move community/contributing to website
437 Sinatra installs special <tt>not_found</tt> and <tt>error</tt> handlers when
438 running under the development environment.
83cba9cf » bmizerany
2008-03-29 updated README with helpful tidbits
439
f44fb6aa » rtomayko
2008-08-31 grammar/formatting pass over README
440 == Mime types
441
17cb177e » cypher
2009-01-11 README and CHANGES tweaks for 0.9.0 release (#63)
442 When using <tt>send_file</tt> or static files you may have mime types Sinatra
6d8b333a » sr
2009-10-18 Update README re. mime_type
443 doesn't understand. Use +mime_type+ to register them by file extension:
83cba9cf » bmizerany
2008-03-29 updated README with helpful tidbits
444
6d8b333a » sr
2009-10-18 Update README re. mime_type
445 mime_type :foo, 'text/foo'
1776a80d » Blake Mizerany
2008-03-24 Added Version and Docs
446
cb8fcb63 » sr
2009-12-23 Doc for content_type :foo
447 You can also use it with the +content_type+ helper:
448
449 content_type :foo
450
f44fb6aa » rtomayko
2008-08-31 grammar/formatting pass over README
451 == Rack Middleware
bda21f1f » rtomayko
2008-05-19 add doc on using Rack middleware to README
452
f44fb6aa » rtomayko
2008-08-31 grammar/formatting pass over README
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.
bda21f1f » rtomayko
2008-05-19 add doc on using Rack middleware to README
458
e75f4b3f » rtomayko
2008-09-09 misc README formatting tweaks
459 Sinatra makes building Rack middleware pipelines a cinch via a top-level
460 +use+ method:
bda21f1f » rtomayko
2008-05-19 add doc on using Rack middleware to README
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
f44fb6aa » rtomayko
2008-08-31 grammar/formatting pass over README
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:
bda21f1f » rtomayko
2008-05-19 add doc on using Rack middleware to README
476
477 use Rack::Auth::Basic do |username, password|
478 username == 'admin' && password == 'secret'
479 end
480
f44fb6aa » rtomayko
2008-08-31 grammar/formatting pass over README
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.
bda21f1f » rtomayko
2008-05-19 add doc on using Rack middleware to README
485
f44fb6aa » rtomayko
2008-08-31 grammar/formatting pass over README
486 == Testing
1776a80d » Blake Mizerany
2008-03-24 Added Version and Docs
487
c831278a » rtomayko
2009-05-18 Recommend Rack::Test in README / note Sinatra::Test deprecation
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:
c00a25ee » rtomayko
2009-01-13 Test framework refactoring
491
7cfe04a9 » jcrosby
2008-09-24 Fix for test/unit and test/spec docs
492 require 'my_sinatra_app'
c831278a » rtomayko
2009-05-18 Recommend Rack::Test in README / note Sinatra::Test deprecation
493 require 'rack/test'
f44fb6aa » rtomayko
2008-08-31 grammar/formatting pass over README
494
1776a80d » Blake Mizerany
2008-03-24 Added Version and Docs
495 class MyAppTest < Test::Unit::TestCase
c831278a » rtomayko
2009-05-18 Recommend Rack::Test in README / note Sinatra::Test deprecation
496 include Rack::Test::Methods
497
498 def app
499 Sinatra::Application
500 end
f44fb6aa » rtomayko
2008-08-31 grammar/formatting pass over README
501
2f377e26 » rtomayko
2009-03-01 Trim down Testing section in the README; link to doc site instead
502 def test_my_default
c00a25ee » rtomayko
2009-01-13 Test framework refactoring
503 get '/'
c831278a » rtomayko
2009-05-18 Recommend Rack::Test in README / note Sinatra::Test deprecation
504 assert_equal 'Hello World!', last_response.body
1776a80d » Blake Mizerany
2008-03-24 Added Version and Docs
505 end
10c90d5f » sr
2008-09-27 document testing with rspec
506
2f377e26 » rtomayko
2009-03-01 Trim down Testing section in the README; link to doc site instead
507 def test_with_params
c831278a » rtomayko
2009-05-18 Recommend Rack::Test in README / note Sinatra::Test deprecation
508 get '/meet', :name => 'Frank'
509 assert_equal 'Hello Frank!', last_response.body
10c90d5f » sr
2008-09-27 document testing with rspec
510 end
511
2f377e26 » rtomayko
2009-03-01 Trim down Testing section in the README; link to doc site instead
512 def test_with_rack_env
c831278a » rtomayko
2009-05-18 Recommend Rack::Test in README / note Sinatra::Test deprecation
513 get '/', {}, 'HTTP_USER_AGENT' => 'Songbird'
514 assert_equal "You're using Songbird!", last_response.body
1fb5b99d » dylanegan
2009-01-09 Bacon support
515 end
516 end
517
c831278a » rtomayko
2009-05-18 Recommend Rack::Test in README / note Sinatra::Test deprecation
518 NOTE: The built-in Sinatra::Test module and Sinatra::TestHarness class
519 are deprecated as of the 0.9.2 release.
1776a80d » Blake Mizerany
2008-03-24 Added Version and Docs
520
53603333 » sr
2009-06-06 Add a note about Sinatra::Base to the README
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
f44fb6aa » rtomayko
2008-08-31 grammar/formatting pass over README
571 == Command line
1776a80d » Blake Mizerany
2008-03-24 Added Version and Docs
572
e75f4b3f » rtomayko
2008-09-09 misc README formatting tweaks
573 Sinatra applications can be run directly:
f44fb6aa » rtomayko
2008-08-31 grammar/formatting pass over README
574
2624423b » sr
2009-12-23 Doc for -h option
575 ruby myapp.rb [-h] [-x] [-e ENVIRONMENT] [-p PORT] [-h HOST] [-s HANDLER]
1776a80d » Blake Mizerany
2008-03-24 Added Version and Docs
576
577 Options are:
578
579 -h # help
580 -p # set the port (default is 4567)
2624423b » sr
2009-12-23 Doc for -h option
581 -h # set the host (default is 0.0.0.0)
1776a80d » Blake Mizerany
2008-03-24 Added Version and Docs
582 -e # set the environment (default is development)
f29486ba » karmi
2009-01-15 Note "-s" (server) command line option in README
583 -s # specify rack server/handler (default is thin)
e7e0e558 » rtomayko
2008-04-14 Minor docfixes in README.rdoc
584 -x # turn on the mutex lock (default is off)
1776a80d » Blake Mizerany
2008-03-24 Added Version and Docs
585
4298a777 » rtomayko
2009-01-23 Tweak README formatting; move community/contributing to website
586 == The Bleeding Edge
6326809e » cypher
2008-08-31 Add a subsection about tools needed for Sinatra to the Contributing s…
587
4298a777 » rtomayko
2009-01-23 Tweak README formatting; move community/contributing to website
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>:
6326809e » cypher
2008-08-31 Add a subsection about tools needed for Sinatra to the Contributing s…
591
4298a777 » rtomayko
2009-01-23 Tweak README formatting; move community/contributing to website
592 cd myapp
ba92616e » bmizerany
2009-01-18 Updated README to point to github.com/sinatra/sinatra.git
593 git clone git://github.com/sinatra/sinatra.git
4298a777 » rtomayko
2009-01-23 Tweak README formatting; move community/contributing to website
594 ruby -Isinatra/lib myapp.rb
480fbfa7 » rtomayko
2008-08-31 minor formatting tweaks to cypher's README updates
595
4f30c1ce » Mathew Cucuzella
2009-05-12 fix unclosed <tt> in README
596 Alternatively, you can add the <tt>sinatra/lib</tt> directory to the
4298a777 » rtomayko
2009-01-23 Tweak README formatting; move community/contributing to website
597 <tt>LOAD_PATH</tt> in your application:
1776a80d » Blake Mizerany
2008-03-24 Added Version and Docs
598
17cb177e » cypher
2009-01-11 README and CHANGES tweaks for 0.9.0 release (#63)
599 $LOAD_PATH.unshift File.dirname(__FILE__) + '/sinatra/lib'
4298a777 » rtomayko
2009-01-23 Tweak README formatting; move community/contributing to website
600 require 'rubygems'
1776a80d » Blake Mizerany
2008-03-24 Added Version and Docs
601 require 'sinatra'
602
603 get '/about' do
4298a777 » rtomayko
2009-01-23 Tweak README formatting; move community/contributing to website
604 "I'm running version " + Sinatra::VERSION
1776a80d » Blake Mizerany
2008-03-24 Added Version and Docs
605 end
e6c5471a » cypher
2008-08-31 Add a community section with info about the mailing list and irc channel
606
4298a777 » rtomayko
2009-01-23 Tweak README formatting; move community/contributing to website
607 To update the Sinatra sources in the future:
d8fec168 » cypher
2008-08-31 Add subsection about contributing a patch as well as a link to the is…
608
4298a777 » rtomayko
2009-01-23 Tweak README formatting; move community/contributing to website
609 cd myproject/sinatra
610 git pull
e6c5471a » cypher
2008-08-31 Add a community section with info about the mailing list and irc channel
611
4298a777 » rtomayko
2009-01-23 Tweak README formatting; move community/contributing to website
612 == More
e6c5471a » cypher
2008-08-31 Add a community section with info about the mailing list and irc channel
613
4298a777 » rtomayko
2009-01-23 Tweak README formatting; move community/contributing to website
614 * {Project Website}[http://sinatra.github.com/] - Additional documentation,
615 news, and links to other resources.
00446837 » Aupajo
2009-02-18 Fixed broken link in README.
616 * {Contributing}[http://sinatra.github.com/contributing.html] - Find a bug? Need
4298a777 » rtomayko
2009-01-23 Tweak README formatting; move community/contributing to website
617 help? Have a patch?
618 * {Lighthouse}[http://sinatra.lighthouseapp.com] - Issue tracking and release
619 planning.
5018264d » rtomayko
2009-03-01 Tidy up README a bit; link to @sinatra on Twitter
620 * {Twitter}[http://twitter.com/sinatra]
4298a777 » rtomayko
2009-01-23 Tweak README formatting; move community/contributing to website
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.