Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 478 lines (313 sloc) 9.488 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
4 effort.
df800b5 Docs are started
Blake Mizerany authored
5
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
6 == Sample App
df800b5 Docs are started
Blake Mizerany authored
7
8 # myapp.rb
9 require 'rubygems'
10 require 'sinatra'
11 get '/' do
12 'Hello world!'
13 end
14
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
15 Run with <tt>ruby myapp.rb</tt> and view at <tt>http://localhost:4567</tt>
df800b5 Docs are started
Blake Mizerany authored
16
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
17 == HTTP Methods
df800b5 Docs are started
Blake Mizerany authored
18
19 get '/' do
20 .. show things ..
21 end
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
22
df800b5 Docs are started
Blake Mizerany authored
23 post '/' do
24 .. create something ..
25 end
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
26
df800b5 Docs are started
Blake Mizerany authored
27 put '/' do
28 .. update something ..
29 end
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
30
df800b5 Docs are started
Blake Mizerany authored
31 delete '/' do
32 .. annihilate something ..
33 end
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
34
1776a80 Added Version and Docs
Blake Mizerany authored
35 head '/' do
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
36
1776a80 Added Version and Docs
Blake Mizerany authored
37 end
38
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
39 NOTE: <tt>put</tt> and <tt>delete</tt> are also triggered when a
40 <tt>_method</tt> parameter is set to PUT or DELETE and the HTTP request method
41 is POST
1776a80 Added Version and Docs
Blake Mizerany authored
42
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
43 == Routes
1776a80 Added Version and Docs
Blake Mizerany authored
44
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
45 Routes are matched based on the order of declaration. The first route that
46 matches the request is invoked.
1776a80 Added Version and Docs
Blake Mizerany authored
47
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
48 Simple:
1776a80 Added Version and Docs
Blake Mizerany authored
49
50 get '/hi' do
51 ...
52 end
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
53
54 Named parameters:
1776a80 Added Version and Docs
Blake Mizerany authored
55
56 get '/:name' do
57 # matches /sinatra and the like and sets params[:name]
58 end
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
59
60 Splat parameters:
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
64 params["splat"] # => ["hello", "world"]
65 end
66
67 get '/download/*.*' do
68 # matches /download/path/to/file.xml
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
72 User agent matching:
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
79 # matches non-songbird browsers
80 end
df800b5 Docs are started
Blake Mizerany authored
81
047edc6 update README with Static help
Blake Mizerany authored
82 = Static files
83
84 Put all of your static content in the ./public directory
85
86 root
87 \ public
88
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
89 If a file exists that maps to the REQUEST_PATH then it is served and the
90 request ends. Otherwise, Sinatra will look for an event that matches the
91 path.
df800b5 Docs are started
Blake Mizerany authored
92
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
93 == Views
df800b5 Docs are started
Blake Mizerany authored
94
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
95 Views are searched for in a "views" directory in the same location as
96 your main application.
df800b5 Docs are started
Blake Mizerany authored
97
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
98 === Haml Templates
df800b5 Docs are started
Blake Mizerany authored
99
100 get '/' do
101 haml :index
102 end
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
103
104 Renders <tt>./views/index.haml</tt>.
105
106 === Erb
107
108 get '/' do
109 erb :index
110 end
111
112 Renders <tt>./views/index.erb</tt>
113
114 === Builder
115
116 See Sinatra::Builder
df800b5 Docs are started
Blake Mizerany authored
117
4144ac1 @nmeans Added Sass information to documentation.
nmeans authored
118 === Sass
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
119
4144ac1 @nmeans Added Sass information to documentation.
nmeans authored
120 get '/stylesheet.css' do
ccc19b0 @rtomayko content_type response helper with mime type lookup and parameter supp…
rtomayko authored
121 content_type 'text/css', :charset => 'utf-8'
4144ac1 @nmeans Added Sass information to documentation.
nmeans authored
122 sass :stylesheet
123 end
124
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
125 Renders <tt>./views/stylesheet.sass</tt>.
126
127 === Inline Templates
df800b5 Docs are started
Blake Mizerany authored
128
129 get '/' do
130 haml '%div.title Hello World'
131 end
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
132
133 Renders the inlined template string.
df800b5 Docs are started
Blake Mizerany authored
134
135 === Accessing Variables
136
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
137 Templates are evaluated within the Sinatra::EventContext instance
138 used to evaluate event blocks. Instance variables set in event
139 blocks can be accessed direcly in views:
df800b5 Docs are started
Blake Mizerany authored
140
141 get '/:id' do
142 @foo = Foo.find(params[:id])
143 haml '%h1== @foo.name'
144 end
145
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
146 Or, specify an explicit Hash of local variables:
df800b5 Docs are started
Blake Mizerany authored
147
148 get '/:id' do
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
149 foo = Foo.find(params[:id])
150 haml '%h1== foo.name', :locals => { :foo => foo }
df800b5 Docs are started
Blake Mizerany authored
151 end
152
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
153 This is typically used when rendering templates as partials from within
154 other templates.
155
156 === In-file Templates
83cba9c @bmizerany updated README with helpful tidbits
bmizerany authored
157
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
158 Templates may be defined at the end of the source file:
83cba9c @bmizerany updated README with helpful tidbits
bmizerany authored
159
160 get '/' do
161 haml :index
162 end
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
163
83cba9c @bmizerany updated README with helpful tidbits
bmizerany authored
164 use_in_file_templates!
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
165
83cba9c @bmizerany updated README with helpful tidbits
bmizerany authored
166 __END__
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
167
f71330e @bmizerany quick doc fix
bmizerany authored
168 @@ layout
83cba9c @bmizerany updated README with helpful tidbits
bmizerany authored
169 X
170 = yield
171 X
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
172
f71330e @bmizerany quick doc fix
bmizerany authored
173 @@ index
83cba9c @bmizerany updated README with helpful tidbits
bmizerany authored
174 %div.title Hello world!!!!!
175
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
176 It's also possible to define named templates using the
83cba9c @bmizerany updated README with helpful tidbits
bmizerany authored
177
178 template :layout do
179 "X\n=yield\nX"
180 end
181
182 template :index do
183 '%div.title Hello World!'
184 end
185
186 get '/' do
187 haml :index
188 end
189
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
190 == Helpers
df800b5 Docs are started
Blake Mizerany authored
191
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
192 The top-level <tt>helpers</tt> method takes a block and extends all
193 EventContext instances with the methods defined:
df800b5 Docs are started
Blake Mizerany authored
194
195 helpers do
196 def bar(name)
197 "#{name}bar"
198 end
199 end
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
200
1776a80 Added Version and Docs
Blake Mizerany authored
201 get '/:name' do
202 bar(params[:name])
203 end
df800b5 Docs are started
Blake Mizerany authored
204
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
205 == Filters
df800b5 Docs are started
Blake Mizerany authored
206
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
207 These are run in Sinatra::EventContext before every event.
1776a80 Added Version and Docs
Blake Mizerany authored
208
df800b5 Docs are started
Blake Mizerany authored
209 before do
210 .. this code will run before each event ..
211 end
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
212
213 == Halt!
df800b5 Docs are started
Blake Mizerany authored
214
215 To immediately stop a request during a before filter or event use:
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
216
df800b5 Docs are started
Blake Mizerany authored
217 throw :halt
218
219 Set the body to the result of a helper method
220
221 throw :halt, :helper_method
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
222
223 Set the body to the result of a helper method after sending it parameters from
224 the local scope
225
df800b5 Docs are started
Blake Mizerany authored
226 throw :halt, [:helper_method, foo, bar]
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
227
df800b5 Docs are started
Blake Mizerany authored
228 Set the body to a simple string
229
230 throw :halt, 'this will be the body'
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
231
df800b5 Docs are started
Blake Mizerany authored
232 Set status then the body
233
234 throw :halt, [401, 'go away!']
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
235
df800b5 Docs are started
Blake Mizerany authored
236 Set the status then call a helper method with params from local scope
237
238 throw :halt, [401, [:helper_method, foo, bar]]
239
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
240 Run a proc inside the Sinatra::EventContext instance and set the body to the
241 result
df800b5 Docs are started
Blake Mizerany authored
242
243 throw :halt, lambda { puts 'In a proc!'; 'I just wrote to $stdout!' }
244
245 Create you own to_result
246
247 class MyResultObject
248 def to_result(event_context, *args)
249 event_context.body = 'This will be the body!
250 end
251 end
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
252
df800b5 Docs are started
Blake Mizerany authored
253 get '/' do
254 throw :halt, MyResultObject.new
255 end
256
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
257 Get the gist? If you want more fun with this then checkout <tt>to_result</tt>
258 on Array, Symbol, Fixnum, NilClass.
df800b5 Docs are started
Blake Mizerany authored
259
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
260 == Configuration and Reloading
1776a80 Added Version and Docs
Blake Mizerany authored
261
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
262 Sinatra supports multiple environments and re-loading. Re-loading happens on
263 every request when in :development. Wrap your configurations in
264 <tt>configure</tt> (i.e. Database connections, Constants, etc.) to protect
265 them from re-loading and to only work in certain environments.
1776a80 Added Version and Docs
Blake Mizerany authored
266
267 All environments:
268
269 configure do
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
270
1776a80 Added Version and Docs
Blake Mizerany authored
271 end
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
272
1776a80 Added Version and Docs
Blake Mizerany authored
273 Production
274
275 configure :production do
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
276
1776a80 Added Version and Docs
Blake Mizerany authored
277 end
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
278
1776a80 Added Version and Docs
Blake Mizerany authored
279 Two at a time:
280
281 configure :production, :test do
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
282
1776a80 Added Version and Docs
Blake Mizerany authored
283 end
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
284
1776a80 Added Version and Docs
Blake Mizerany authored
285 This is also really nifty for error handling.
286
287 = Error handling
288
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
289 == Not Found
1776a80 Added Version and Docs
Blake Mizerany authored
290
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
291 Remember: These are run inside the Sinatra::EventContext which means you get
292 all the goodies is has to offer (i.e. haml, erb, :halt, etc.)
1776a80 Added Version and Docs
Blake Mizerany authored
293
294 Whenever NotFound is raised this will be called
295
296 not_found do
297 'This is nowhere to be found'
298 end
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
299
300 == Error
83cba9c @bmizerany updated README with helpful tidbits
bmizerany authored
301
302 By default +error+ will catch Sinatra::ServerError
303
304 Sinatra will pass you the error via the 'sinatra.error' in request.env
305
1776a80 Added Version and Docs
Blake Mizerany authored
306 error do
83cba9c @bmizerany updated README with helpful tidbits
bmizerany authored
307 'Sorry there was a nasty error - ' + request.env['sinatra.error'].name
308 end
309
310 Custom error mapping:
311
312 error MyCustomError do
e7e0e55 @rtomayko Minor docfixes in README.rdoc
rtomayko authored
313 'So what happened was...' + request.env['sinatra.error'].message
1776a80 Added Version and Docs
Blake Mizerany authored
314 end
83cba9c @bmizerany updated README with helpful tidbits
bmizerany authored
315
316 then if this happens:
317
318 get '/' do
319 raise MyCustomError, 'something bad'
320 end
321
322 you gets this:
323
324 So what happened was... something bad
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
325
83cba9c @bmizerany updated README with helpful tidbits
bmizerany authored
326 one guess what this does ;)
327
328 not_found do
329 'I have no clue what you're looking for'
330 end
331
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
332 Because Sinatra gives you a default <tt>not_found</tt> and <tt>error</tt> do
333 :production that are secure. If you want to customize only for :production
334 but want to keep the friendly helper screens for :development then do this:
1776a80 Added Version and Docs
Blake Mizerany authored
335
336 configure :production do
337
338 not_found do
339 "We're so sorry, but we don't what this is"
340 end
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
341
1776a80 Added Version and Docs
Blake Mizerany authored
342 error do
343 "Something really nasty happened. We're on it!"
344 end
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
345
1776a80 Added Version and Docs
Blake Mizerany authored
346 end
83cba9c @bmizerany updated README with helpful tidbits
bmizerany authored
347
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
348 == Mime types
349
350 When using send_file or static files you may have mime types Sinatra doesn't
351 understand. Use +mime+ in those cases.
83cba9c @bmizerany updated README with helpful tidbits
bmizerany authored
352
353 mime :foo, 'text/foo'
1776a80 Added Version and Docs
Blake Mizerany authored
354
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
355 == Rack Middleware
bda21f1 @rtomayko add doc on using Rack middleware to README
rtomayko authored
356
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
357 Sinatra rides on Rack[http://rack.rubyforge.org/], a minimal standard
358 interface for Ruby web frameworks. One of Rack's most interesting capabilities
359 for application developers is support for "middleware" -- components that sit
360 between the server and your application monitoring and/or manipulating the
361 HTTP request/response to provide various types of common functionality.
362 What's more, middleware is portable between web frameworks, so middleware
363 components developed under, e.g., Merb, can be used with Sinatra and vice
364 versa.
bda21f1 @rtomayko add doc on using Rack middleware to README
rtomayko authored
365
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
366 Sinatra makes building Rack middleware pipelines a cinch via a top-level +use+
367 method:
bda21f1 @rtomayko add doc on using Rack middleware to README
rtomayko authored
368
369 require 'sinatra'
370 require 'my_custom_middleware'
371
372 use Rack::Lint
373 use MyCustomMiddleware
374
375 get '/hello' do
376 'Hello World'
377 end
378
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
379 The semantics of +use+ are identical to those defined for the
380 Rack::Builder[http://rack.rubyforge.org/doc/classes/Rack/Builder.html] DSL
381 (most frequently used from rackup files). For example, the +use+ method
382 accepts multiple/variable args as well as blocks:
bda21f1 @rtomayko add doc on using Rack middleware to README
rtomayko authored
383
384 use Rack::Auth::Basic do |username, password|
385 username == 'admin' && password == 'secret'
386 end
387
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
388 Rack is distributed with a variety of standard middleware for logging,
389 debugging, URL routing, authentication, and session handling. Sinatra uses
390 many of of these components automatically based on configuration so you
391 typically don't have to +use+ them explicitly.
bda21f1 @rtomayko add doc on using Rack middleware to README
rtomayko authored
392
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
393 == Testing
1776a80 Added Version and Docs
Blake Mizerany authored
394
28b1285 better docs on testing
Blake Mizerany authored
395 === Methods
396
397 get_it path, params
398 get_it path, params.merge(:env => { 'HTTP_HOST' => 'www.sinatrarb.com' }) or
399 get_it path, params.merge(:env => { :host => 'www.sinatrarb.com' })
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
400
28b1285 better docs on testing
Blake Mizerany authored
401 RESTful:
402
403 post_it '/foo', '<myxml></myxml>', 'HTTP_ACCEPT' => 'application/xml'
404
405 also works with:
406
407 get_it, post_it, put_it, delete_it, head_it
408
1776a80 Added Version and Docs
Blake Mizerany authored
409 === Test/Unit
410
411 require 'my_sinatra_app'
412 require 'sinatra/test/unit'
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
413
1776a80 Added Version and Docs
Blake Mizerany authored
414 class MyAppTest < Test::Unit::TestCase
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
415
1776a80 Added Version and Docs
Blake Mizerany authored
416 def test_my_default
417 get_it '/'
418 assert_equal 'My Default Page!', @response.body
419 end
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
420
1776a80 Added Version and Docs
Blake Mizerany authored
421 def test_with_agent
422 get_it '/', :agent => 'Songbird'
423 assert_equal 'You're in Songbird!', @response.body
424 end
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
425
1776a80 Added Version and Docs
Blake Mizerany authored
426 ...
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
427
1776a80 Added Version and Docs
Blake Mizerany authored
428 end
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
429
430 === Specs
1776a80 Added Version and Docs
Blake Mizerany authored
431
432 require 'my_sinatra_app'
433 require 'sinatra/test/spec'
434
435 context 'My app'
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
436
1776a80 Added Version and Docs
Blake Mizerany authored
437 should "show a default page" do
438 get_it '/'
439 should.be.ok
83cba9c @bmizerany updated README with helpful tidbits
bmizerany authored
440 body.should.equal 'My Default Page!'
1776a80 Added Version and Docs
Blake Mizerany authored
441 end
442 ...
443
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
444 end
1776a80 Added Version and Docs
Blake Mizerany authored
445
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
446 === Test Helpers
1776a80 Added Version and Docs
Blake Mizerany authored
447
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
448 See Sinatra::Test::Methods
1776a80 Added Version and Docs
Blake Mizerany authored
449
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
450 == Command line
1776a80 Added Version and Docs
Blake Mizerany authored
451
452 Run your sinatra file like:
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
453
1776a80 Added Version and Docs
Blake Mizerany authored
454 ruby myapp.rb [options]
455
456 Options are:
457
458 -h # help
459 -p # set the port (default is 4567)
460 -e # set the environment (default is development)
e7e0e55 @rtomayko Minor docfixes in README.rdoc
rtomayko authored
461 -x # turn on the mutex lock (default is off)
1776a80 Added Version and Docs
Blake Mizerany authored
462
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
463 == Contribute
1776a80 Added Version and Docs
Blake Mizerany authored
464
465 cd where/you/keep/your/projects
466 git clone git://github.com/bmizerany/sinatra.git
467 cd your_project
468 ln -s ../sinatra/
469
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
470 At the top of your sinatra.rb file:
1776a80 Added Version and Docs
Blake Mizerany authored
471
472 $:.unshift File.dirname(__FILE__) + '/sinatra/lib'
473 require 'sinatra'
474
475 get '/about' do
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
476 "I'm running on Version " + Sinatra::VERSION
1776a80 Added Version and Docs
Blake Mizerany authored
477 end
Something went wrong with that request. Please try again.