Skip to content
Newer
Older
100644 508 lines (349 sloc) 11.8 KB
df800b5 Docs are started
Blake Mizerany authored
1 = Sinatra
2
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko 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
a734cf3 @rtomayko I knew I shoulda taken that left turn at Hoboken
rtomayko authored
48 # matches "GET /foo" and "GET /bar"
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
df800b5 Docs are started
Blake Mizerany authored
121 get '/' do
122 haml :index
123 end
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
124
125 Renders <tt>./views/index.haml</tt>.
126
d359dc9 @kematzy Merge app-level haml/sass options with call options [#184]
kematzy authored
127 {Haml's options}[http://haml.hamptoncatlin.com/docs/rdoc/classes/Haml.html]
128 can be set globally through Sinatra's configurations,
129 see {Options and Configurations}[http://www.sinatrarb.com/configuration.html],
130 and overridden on an individual basis.
131
132 set :haml, {:format => :html5 } # default Haml format is :xhtml
133
134 get '/' do
135 haml :index, :haml_options => {:format => :html4 } # overridden
136 end
137
138
17cb177 @cypher README and CHANGES tweaks for 0.9.0 release (#63)
cypher authored
139 === Erb Templates
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
140
141 get '/' do
142 erb :index
143 end
144
145 Renders <tt>./views/index.erb</tt>
146
17cb177 @cypher README and CHANGES tweaks for 0.9.0 release (#63)
cypher authored
147 === Builder Templates
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
148
17cb177 @cypher README and CHANGES tweaks for 0.9.0 release (#63)
cypher authored
149 The builder gem/library is required to render builder templates:
df800b5 Docs are started
Blake Mizerany authored
150
17cb177 @cypher README and CHANGES tweaks for 0.9.0 release (#63)
cypher authored
151 get '/' do
152 content_type 'application/xml', :charset => 'utf-8'
153 builder :index
154 end
155
156 Renders <tt>./views/index.builder</tt>.
157
158 === Sass Templates
159
160 The sass gem/library is required to render Sass templates:
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
161
4144ac1 @nmeans Added Sass information to documentation.
nmeans authored
162 get '/stylesheet.css' do
ccc19b0 @rtomayko content_type response helper with mime type lookup and parameter supp…
rtomayko authored
163 content_type 'text/css', :charset => 'utf-8'
4144ac1 @nmeans Added Sass information to documentation.
nmeans authored
164 sass :stylesheet
165 end
166
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
167 Renders <tt>./views/stylesheet.sass</tt>.
168
d359dc9 @kematzy Merge app-level haml/sass options with call options [#184]
kematzy authored
169 {Sass' options}[http://haml.hamptoncatlin.com/docs/rdoc/classes/Sass.html]
170 can be set globally through Sinatra's configurations,
171 see {Options and Configurations}[http://www.sinatrarb.com/configuration.html],
172 and overridden on an individual basis.
173
174 set :sass, {:style => :compact } # default Sass style is :nested
175
176 get '/stylesheet.css' do
177 content_type 'text/css', :charset => 'utf-8'
178 sass :stylesheet, :sass_options => {:style => :expanded } # overridden
179 end
180
181
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
182 === Inline Templates
df800b5 Docs are started
Blake Mizerany authored
183
184 get '/' do
185 haml '%div.title Hello World'
186 end
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
187
188 Renders the inlined template string.
df800b5 Docs are started
Blake Mizerany authored
189
4298a77 @rtomayko Tweak README formatting; move community/contributing to website
rtomayko authored
190 === Accessing Variables in Templates
df800b5 Docs are started
Blake Mizerany authored
191
5018264 @rtomayko Tidy up README a bit; link to @sinatra on Twitter
rtomayko authored
192 Templates are evaluated within the same context as route handlers. Instance
193 variables set in route handlers are direcly accessible by templates:
df800b5 Docs are started
Blake Mizerany authored
194
195 get '/:id' do
196 @foo = Foo.find(params[:id])
95aca76 @bleything fix documentation of variable interpolation into templates
bleything authored
197 haml '%h1= @foo.name'
df800b5 Docs are started
Blake Mizerany authored
198 end
199
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
200 Or, specify an explicit Hash of local variables:
df800b5 Docs are started
Blake Mizerany authored
201
202 get '/:id' do
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
203 foo = Foo.find(params[:id])
95aca76 @bleything fix documentation of variable interpolation into templates
bleything authored
204 haml '%h1= foo.name', :locals => { :foo => foo }
df800b5 Docs are started
Blake Mizerany authored
205 end
206
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
207 This is typically used when rendering templates as partials from within
208 other templates.
209
210 === In-file Templates
83cba9c @bmizerany updated README with helpful tidbits
bmizerany authored
211
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
212 Templates may be defined at the end of the source file:
83cba9c @bmizerany updated README with helpful tidbits
bmizerany authored
213
eec7d21 @bmizerany In-file-templates are automaticly loaded for you.
bmizerany authored
214 require 'rubygems'
215 require 'sinatra'
216
83cba9c @bmizerany updated README with helpful tidbits
bmizerany authored
217 get '/' do
218 haml :index
219 end
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
220
83cba9c @bmizerany updated README with helpful tidbits
bmizerany authored
221 __END__
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
222
f71330e @bmizerany quick doc fix
bmizerany authored
223 @@ layout
17cb177 @cypher README and CHANGES tweaks for 0.9.0 release (#63)
cypher authored
224 %html
225 = yield
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
226
f71330e @bmizerany quick doc fix
bmizerany authored
227 @@ index
83cba9c @bmizerany updated README with helpful tidbits
bmizerany authored
228 %div.title Hello world!!!!!
229
4298a77 @rtomayko Tweak README formatting; move community/contributing to website
rtomayko authored
230 NOTE: In-file templates defined in the source file that requires sinatra
231 are automatically loaded. Call the <tt>use_in_file_templates!</tt>
5018264 @rtomayko Tidy up README a bit; link to @sinatra on Twitter
rtomayko authored
232 method explicitly if you have in-file templates in other source files.
eec7d21 @bmizerany In-file-templates are automaticly loaded for you.
bmizerany authored
233
4298a77 @rtomayko Tweak README formatting; move community/contributing to website
rtomayko authored
234 === Named Templates
235
5018264 @rtomayko Tidy up README a bit; link to @sinatra on Twitter
rtomayko authored
236 Templates may also be defined using the top-level <tt>template</tt> method:
83cba9c @bmizerany updated README with helpful tidbits
bmizerany authored
237
238 template :layout do
17cb177 @cypher README and CHANGES tweaks for 0.9.0 release (#63)
cypher authored
239 "%html\n =yield\n"
83cba9c @bmizerany updated README with helpful tidbits
bmizerany authored
240 end
241
242 template :index do
243 '%div.title Hello World!'
244 end
245
246 get '/' do
247 haml :index
248 end
249
17cb177 @cypher README and CHANGES tweaks for 0.9.0 release (#63)
cypher authored
250 If a template named "layout" exists, it will be used each time a template
251 is rendered. You can disable layouts by passing <tt>:layout => false</tt>.
578bbab @djanowski Updating README for :layout => true.
djanowski authored
252
253 get '/' do
254 haml :index, :layout => !request.xhr?
255 end
256
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
257 == Helpers
df800b5 Docs are started
Blake Mizerany authored
258
17cb177 @cypher README and CHANGES tweaks for 0.9.0 release (#63)
cypher authored
259 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
260 route handlers and templates:
df800b5 Docs are started
Blake Mizerany authored
261
262 helpers do
263 def bar(name)
264 "#{name}bar"
265 end
266 end
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
267
1776a80 Added Version and Docs
Blake Mizerany authored
268 get '/:name' do
269 bar(params[:name])
270 end
df800b5 Docs are started
Blake Mizerany authored
271
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
272 == Filters
df800b5 Docs are started
Blake Mizerany authored
273
17cb177 @cypher README and CHANGES tweaks for 0.9.0 release (#63)
cypher authored
274 Before filters are evaluated before each request within the context of the
275 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
276 filters are accessible by routes and templates:
1776a80 Added Version and Docs
Blake Mizerany authored
277
df800b5 Docs are started
Blake Mizerany authored
278 before do
a734cf3 @rtomayko I knew I shoulda taken that left turn at Hoboken
rtomayko authored
279 @note = 'Hi!'
280 request.path_info = '/foo/bar/baz'
281 end
282
283 get '/foo/*' do
284 @note #=> 'Hi!'
285 params[:splat] #=> 'bar/baz'
df800b5 Docs are started
Blake Mizerany authored
286 end
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
287
17cb177 @cypher README and CHANGES tweaks for 0.9.0 release (#63)
cypher authored
288 == Halting
a734cf3 @rtomayko I knew I shoulda taken that left turn at Hoboken
rtomayko authored
289
17cb177 @cypher README and CHANGES tweaks for 0.9.0 release (#63)
cypher authored
290 To immediately stop a request during a before filter or route use:
df800b5 Docs are started
Blake Mizerany authored
291
17cb177 @cypher README and CHANGES tweaks for 0.9.0 release (#63)
cypher authored
292 halt
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
293
17cb177 @cypher README and CHANGES tweaks for 0.9.0 release (#63)
cypher authored
294 You can also specify a body when halting ...
df800b5 Docs are started
Blake Mizerany authored
295
17cb177 @cypher README and CHANGES tweaks for 0.9.0 release (#63)
cypher authored
296 halt 'this will be the body'
df800b5 Docs are started
Blake Mizerany authored
297
4298a77 @rtomayko Tweak README formatting; move community/contributing to website
rtomayko authored
298 Or set the status and body ...
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
299
17cb177 @cypher README and CHANGES tweaks for 0.9.0 release (#63)
cypher authored
300 halt 401, 'go away!'
df800b5 Docs are started
Blake Mizerany authored
301
17cb177 @cypher README and CHANGES tweaks for 0.9.0 release (#63)
cypher authored
302 == Passing
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
303
5018264 @rtomayko Tidy up README a bit; link to @sinatra on Twitter
rtomayko authored
304 A route can punt processing to the next matching route using <tt>pass</tt>:
df800b5 Docs are started
Blake Mizerany authored
305
17cb177 @cypher README and CHANGES tweaks for 0.9.0 release (#63)
cypher authored
306 get '/guess/:who' do
307 pass unless params[:who] == 'Frank'
308 "You got me!"
309 end
310
311 get '/guess/*' do
312 "You missed!"
313 end
314
315 The route block is immediately exited and control continues with the next
316 matching route. If no matching route is found, a 404 is returned.
df800b5 Docs are started
Blake Mizerany authored
317
13fc79d @rtomayko Remove support for source file reloading [#166]
rtomayko authored
318 == Configuration
1776a80 Added Version and Docs
Blake Mizerany authored
319
17cb177 @cypher README and CHANGES tweaks for 0.9.0 release (#63)
cypher authored
320 Run once, at startup, in any environment:
1776a80 Added Version and Docs
Blake Mizerany authored
321
322 configure do
e75f4b3 @rtomayko misc README formatting tweaks
rtomayko authored
323 ...
1776a80 Added Version and Docs
Blake Mizerany authored
324 end
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
325
17cb177 @cypher README and CHANGES tweaks for 0.9.0 release (#63)
cypher authored
326 Run only when the environment (RACK_ENV environment variable) is set to
13fc79d @rtomayko Remove support for source file reloading [#166]
rtomayko authored
327 <tt>:production</tt>:
1776a80 Added Version and Docs
Blake Mizerany authored
328
329 configure :production do
e75f4b3 @rtomayko misc README formatting tweaks
rtomayko authored
330 ...
1776a80 Added Version and Docs
Blake Mizerany authored
331 end
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
332
13fc79d @rtomayko Remove support for source file reloading [#166]
rtomayko authored
333 Run when the environment is set to either <tt>:production</tt> or
334 <tt>:test</tt>:
1776a80 Added Version and Docs
Blake Mizerany authored
335
336 configure :production, :test do
e75f4b3 @rtomayko misc README formatting tweaks
rtomayko authored
337 ...
1776a80 Added Version and Docs
Blake Mizerany authored
338 end
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
339
e75f4b3 @rtomayko misc README formatting tweaks
rtomayko authored
340 == Error handling
1776a80 Added Version and Docs
Blake Mizerany authored
341
17cb177 @cypher README and CHANGES tweaks for 0.9.0 release (#63)
cypher authored
342 Error handlers run within the same context as routes and before filters, which
343 means you get all the goodies it has to offer, like <tt>haml</tt>, <tt>erb</tt>,
344 <tt>halt</tt>, etc.
1776a80 Added Version and Docs
Blake Mizerany authored
345
e75f4b3 @rtomayko misc README formatting tweaks
rtomayko authored
346 === Not Found
1776a80 Added Version and Docs
Blake Mizerany authored
347
17cb177 @cypher README and CHANGES tweaks for 0.9.0 release (#63)
cypher authored
348 When a <tt>Sinatra::NotFound</tt> exception is raised, or the response's status
349 code is 404, the <tt>not_found</tt> handler is invoked:
1776a80 Added Version and Docs
Blake Mizerany authored
350
351 not_found do
352 'This is nowhere to be found'
353 end
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
354
e75f4b3 @rtomayko misc README formatting tweaks
rtomayko authored
355 === Error
83cba9c @bmizerany updated README with helpful tidbits
bmizerany authored
356
17cb177 @cypher README and CHANGES tweaks for 0.9.0 release (#63)
cypher authored
357 The +error+ handler is invoked any time an exception is raised from a route
358 block or before filter. The exception object can be obtained from the
4298a77 @rtomayko Tweak README formatting; move community/contributing to website
rtomayko authored
359 <tt>sinatra.error</tt> Rack variable:
83cba9c @bmizerany updated README with helpful tidbits
bmizerany authored
360
1776a80 Added Version and Docs
Blake Mizerany authored
361 error do
17cb177 @cypher README and CHANGES tweaks for 0.9.0 release (#63)
cypher authored
362 'Sorry there was a nasty error - ' + env['sinatra.error'].name
83cba9c @bmizerany updated README with helpful tidbits
bmizerany authored
363 end
364
e75f4b3 @rtomayko misc README formatting tweaks
rtomayko authored
365 Custom errors:
83cba9c @bmizerany updated README with helpful tidbits
bmizerany authored
366
367 error MyCustomError do
e7e0e55 @rtomayko Minor docfixes in README.rdoc
rtomayko authored
368 'So what happened was...' + request.env['sinatra.error'].message
1776a80 Added Version and Docs
Blake Mizerany authored
369 end
83cba9c @bmizerany updated README with helpful tidbits
bmizerany authored
370
e75f4b3 @rtomayko misc README formatting tweaks
rtomayko authored
371 Then, if this happens:
83cba9c @bmizerany updated README with helpful tidbits
bmizerany authored
372
373 get '/' do
374 raise MyCustomError, 'something bad'
375 end
376
e75f4b3 @rtomayko misc README formatting tweaks
rtomayko authored
377 You get this:
83cba9c @bmizerany updated README with helpful tidbits
bmizerany authored
378
379 So what happened was... something bad
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
380
4298a77 @rtomayko Tweak README formatting; move community/contributing to website
rtomayko authored
381 Sinatra installs special <tt>not_found</tt> and <tt>error</tt> handlers when
382 running under the development environment.
83cba9c @bmizerany updated README with helpful tidbits
bmizerany authored
383
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
384 == Mime types
385
17cb177 @cypher README and CHANGES tweaks for 0.9.0 release (#63)
cypher authored
386 When using <tt>send_file</tt> or static files you may have mime types Sinatra
387 doesn't understand. Use +mime+ to register them by file extension:
83cba9c @bmizerany updated README with helpful tidbits
bmizerany authored
388
389 mime :foo, 'text/foo'
1776a80 Added Version and Docs
Blake Mizerany authored
390
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
391 == Rack Middleware
bda21f1 @rtomayko add doc on using Rack middleware to README
rtomayko authored
392
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
393 Sinatra rides on Rack[http://rack.rubyforge.org/], a minimal standard
394 interface for Ruby web frameworks. One of Rack's most interesting capabilities
395 for application developers is support for "middleware" -- components that sit
396 between the server and your application monitoring and/or manipulating the
397 HTTP request/response to provide various types of common functionality.
bda21f1 @rtomayko add doc on using Rack middleware to README
rtomayko authored
398
e75f4b3 @rtomayko misc README formatting tweaks
rtomayko authored
399 Sinatra makes building Rack middleware pipelines a cinch via a top-level
400 +use+ method:
bda21f1 @rtomayko add doc on using Rack middleware to README
rtomayko authored
401
402 require 'sinatra'
403 require 'my_custom_middleware'
404
405 use Rack::Lint
406 use MyCustomMiddleware
407
408 get '/hello' do
409 'Hello World'
410 end
411
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
412 The semantics of +use+ are identical to those defined for the
413 Rack::Builder[http://rack.rubyforge.org/doc/classes/Rack/Builder.html] DSL
414 (most frequently used from rackup files). For example, the +use+ method
415 accepts multiple/variable args as well as blocks:
bda21f1 @rtomayko add doc on using Rack middleware to README
rtomayko authored
416
417 use Rack::Auth::Basic do |username, password|
418 username == 'admin' && password == 'secret'
419 end
420
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
421 Rack is distributed with a variety of standard middleware for logging,
422 debugging, URL routing, authentication, and session handling. Sinatra uses
423 many of of these components automatically based on configuration so you
424 typically don't have to +use+ them explicitly.
bda21f1 @rtomayko add doc on using Rack middleware to README
rtomayko authored
425
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
426 == Testing
1776a80 Added Version and Docs
Blake Mizerany authored
427
2f377e2 @rtomayko Trim down Testing section in the README; link to doc site instead
rtomayko authored
428 The Sinatra::Test mixin and Sinatra::TestHarness class include a variety of
429 helper methods for testing your Sinatra app:
c00a25e @rtomayko Test framework refactoring
rtomayko authored
430
7cfe04a @jcrosby Fix for test/unit and test/spec docs
jcrosby authored
431 require 'my_sinatra_app'
2f377e2 @rtomayko Trim down Testing section in the README; link to doc site instead
rtomayko authored
432 require 'test/unit'
433 require 'sinatra/test'
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
434
1776a80 Added Version and Docs
Blake Mizerany authored
435 class MyAppTest < Test::Unit::TestCase
2f377e2 @rtomayko Trim down Testing section in the README; link to doc site instead
rtomayko authored
436 include Sinatra::Test
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
437
2f377e2 @rtomayko Trim down Testing section in the README; link to doc site instead
rtomayko authored
438 def test_my_default
c00a25e @rtomayko Test framework refactoring
rtomayko authored
439 get '/'
2f377e2 @rtomayko Trim down Testing section in the README; link to doc site instead
rtomayko authored
440 assert_equal 'Hello World!', @response.body
1776a80 Added Version and Docs
Blake Mizerany authored
441 end
10c90d5 @sr document testing with rspec
sr authored
442
2f377e2 @rtomayko Trim down Testing section in the README; link to doc site instead
rtomayko authored
443 def test_with_params
444 get '/meet', {:name => 'Frank'}
445 assert_equal 'Hello Frank!', @response.body
10c90d5 @sr document testing with rspec
sr authored
446 end
447
2f377e2 @rtomayko Trim down Testing section in the README; link to doc site instead
rtomayko authored
448 def test_with_rack_env
c2940f6 @cypher Fix test_with_rack_env example in README
cypher authored
449 get '/', {}, :agent => 'Songbird'
2f377e2 @rtomayko Trim down Testing section in the README; link to doc site instead
rtomayko authored
450 assert_equal "You're using Songbird!", @response.body
1fb5b99 @dylanegan Bacon support
dylanegan authored
451 end
452 end
453
8446c5a @rtomayko Fix broken link to testing doc in README
rtomayko authored
454 See http://www.sinatrarb.com/testing.html for more on Sinatra::Test and using it
2f377e2 @rtomayko Trim down Testing section in the README; link to doc site instead
rtomayko authored
455 with other test frameworks such as RSpec, Bacon, and test/spec.
1776a80 Added Version and Docs
Blake Mizerany authored
456
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
457 == Command line
1776a80 Added Version and Docs
Blake Mizerany authored
458
e75f4b3 @rtomayko misc README formatting tweaks
rtomayko authored
459 Sinatra applications can be run directly:
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
460
f29486b @karmi Note "-s" (server) command line option in README
karmi authored
461 ruby myapp.rb [-h] [-x] [-e ENVIRONMENT] [-p PORT] [-s HANDLER]
1776a80 Added Version and Docs
Blake Mizerany authored
462
463 Options are:
464
465 -h # help
466 -p # set the port (default is 4567)
467 -e # set the environment (default is development)
f29486b @karmi Note "-s" (server) command line option in README
karmi authored
468 -s # specify rack server/handler (default is thin)
e7e0e55 @rtomayko Minor docfixes in README.rdoc
rtomayko authored
469 -x # turn on the mutex lock (default is off)
1776a80 Added Version and Docs
Blake Mizerany authored
470
4298a77 @rtomayko Tweak README formatting; move community/contributing to website
rtomayko authored
471 == The Bleeding Edge
6326809 @cypher Add a subsection about tools needed for Sinatra to the Contributing s…
cypher authored
472
4298a77 @rtomayko Tweak README formatting; move community/contributing to website
rtomayko authored
473 If you would like to use Sinatra's latest bleeding code, create a local
474 clone and run your app with the <tt>sinatra/lib</tt> directory on the
475 <tt>LOAD_PATH</tt>:
6326809 @cypher Add a subsection about tools needed for Sinatra to the Contributing s…
cypher authored
476
4298a77 @rtomayko Tweak README formatting; move community/contributing to website
rtomayko authored
477 cd myapp
ba92616 @bmizerany Updated README to point to github.com/sinatra/sinatra.git
bmizerany authored
478 git clone git://github.com/sinatra/sinatra.git
4298a77 @rtomayko Tweak README formatting; move community/contributing to website
rtomayko authored
479 ruby -Isinatra/lib myapp.rb
480fbfa @rtomayko minor formatting tweaks to cypher's README updates
rtomayko authored
480
4298a77 @rtomayko Tweak README formatting; move community/contributing to website
rtomayko authored
481 Alternatively, you can add the <tt>sinatra/lib<tt> directory to the
482 <tt>LOAD_PATH</tt> in your application:
1776a80 Added Version and Docs
Blake Mizerany authored
483
17cb177 @cypher README and CHANGES tweaks for 0.9.0 release (#63)
cypher authored
484 $LOAD_PATH.unshift File.dirname(__FILE__) + '/sinatra/lib'
4298a77 @rtomayko Tweak README formatting; move community/contributing to website
rtomayko authored
485 require 'rubygems'
1776a80 Added Version and Docs
Blake Mizerany authored
486 require 'sinatra'
487
488 get '/about' do
4298a77 @rtomayko Tweak README formatting; move community/contributing to website
rtomayko authored
489 "I'm running version " + Sinatra::VERSION
1776a80 Added Version and Docs
Blake Mizerany authored
490 end
e6c5471 @cypher Add a community section with info about the mailing list and irc channel
cypher authored
491
4298a77 @rtomayko Tweak README formatting; move community/contributing to website
rtomayko authored
492 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
493
4298a77 @rtomayko Tweak README formatting; move community/contributing to website
rtomayko authored
494 cd myproject/sinatra
495 git pull
e6c5471 @cypher Add a community section with info about the mailing list and irc channel
cypher authored
496
4298a77 @rtomayko Tweak README formatting; move community/contributing to website
rtomayko authored
497 == More
e6c5471 @cypher Add a community section with info about the mailing list and irc channel
cypher authored
498
4298a77 @rtomayko Tweak README formatting; move community/contributing to website
rtomayko authored
499 * {Project Website}[http://sinatra.github.com/] - Additional documentation,
500 news, and links to other resources.
0044683 @Aupajo Fixed broken link in README.
Aupajo authored
501 * {Contributing}[http://sinatra.github.com/contributing.html] - Find a bug? Need
4298a77 @rtomayko Tweak README formatting; move community/contributing to website
rtomayko authored
502 help? Have a patch?
503 * {Lighthouse}[http://sinatra.lighthouseapp.com] - Issue tracking and release
504 planning.
5018264 @rtomayko Tidy up README a bit; link to @sinatra on Twitter
rtomayko authored
505 * {Twitter}[http://twitter.com/sinatra]
4298a77 @rtomayko Tweak README formatting; move community/contributing to website
rtomayko authored
506 * {Mailing List}[http://groups.google.com/group/sinatrarb]
507 * {IRC: #sinatra}[irc://chat.freenode.net/#sinatra] on http://freenode.net
Something went wrong with that request. Please try again.