Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

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