Skip to content
Newer
Older
100644 1527 lines (1036 sloc) 39.2 KB
df800b5 Docs are started
Blake Mizerany authored
1 = Sinatra
2
4c91e54 @watchdogtimer Web applications should not be hyphenated
watchdogtimer authored
3 Sinatra is a DSL for quickly creating web applications in Ruby with minimal
17cb177 @cypher README and CHANGES tweaks for 0.9.0 release (#63)
cypher authored
4 effort:
df800b5 Docs are started
Blake Mizerany authored
5
6 # myapp.rb
7 require 'sinatra'
c37db5c @rkh minor adjustments and fixes for the readme examples
rkh authored
8
df800b5 Docs are started
Blake Mizerany authored
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
8465d49 @rkh Avoid `require "rubygems"` and `sudo` in README.
rkh authored
15 gem install sinatra
16 ruby -rubygems myapp.rb
4298a77 @rtomayko Tweak README formatting; move community/contributing to website
rtomayko authored
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
ba1fd4c @jammur Updated README.rdoc to reflect added OPTIONS request type.
jammur authored
40
41 options '/' do
42 .. appease something ..
43 end
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
44
4298a77 @rtomayko Tweak README formatting; move community/contributing to website
rtomayko authored
45 Routes are matched in the order they are defined. The first route that
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
46 matches the request is invoked.
1776a80 Added Version and Docs
Blake Mizerany authored
47
17cb177 @cypher README and CHANGES tweaks for 0.9.0 release (#63)
cypher authored
48 Route patterns may include named parameters, accessible via the
49 <tt>params</tt> hash:
1776a80 Added Version and Docs
Blake Mizerany authored
50
4298a77 @rtomayko Tweak README formatting; move community/contributing to website
rtomayko authored
51 get '/hello/:name' do
ce0fe87 @scottj97 fix inaccurate comment in README
scottj97 authored
52 # matches "GET /hello/foo" and "GET /hello/bar"
a734cf3 @rtomayko I knew I shoulda taken that left turn at Hoboken
rtomayko authored
53 # params[:name] is 'foo' or 'bar'
17cb177 @cypher README and CHANGES tweaks for 0.9.0 release (#63)
cypher authored
54 "Hello #{params[:name]}!"
1776a80 Added Version and Docs
Blake Mizerany authored
55 end
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
56
6569d1b @bdimcheff Added route block params in routing statements [#140]
bdimcheff authored
57 You can also access named parameters via block parameters:
58
59 get '/hello/:name' do |n|
60 "Hello #{n}!"
61 end
62
17cb177 @cypher README and CHANGES tweaks for 0.9.0 release (#63)
cypher authored
63 Route patterns may also include splat (or wildcard) parameters, accessible
64 via the <tt>params[:splat]</tt> array.
1776a80 Added Version and Docs
Blake Mizerany authored
65
9c85e99 @vic Specs, documentation and fixes for splat'n routes
vic authored
66 get '/say/*/to/*' do
67 # matches /say/hello/to/world
a734cf3 @rtomayko I knew I shoulda taken that left turn at Hoboken
rtomayko authored
68 params[:splat] # => ["hello", "world"]
9c85e99 @vic Specs, documentation and fixes for splat'n routes
vic authored
69 end
70
71 get '/download/*.*' do
72 # matches /download/path/to/file.xml
a734cf3 @rtomayko I knew I shoulda taken that left turn at Hoboken
rtomayko authored
73 params[:splat] # => ["path/to/file", "xml"]
1776a80 Added Version and Docs
Blake Mizerany authored
74 end
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
75
17cb177 @cypher README and CHANGES tweaks for 0.9.0 release (#63)
cypher authored
76 Route matching with Regular Expressions:
77
78 get %r{/hello/([\w]+)} do
79 "Hello, #{params[:captures].first}!"
80 end
81
6569d1b @bdimcheff Added route block params in routing statements [#140]
bdimcheff authored
82 Or with a block parameter:
83
84 get %r{/hello/([\w]+)} do |c|
85 "Hello, #{c}!"
86 end
87
726feeb @rkh Documentation for condition. Fixes GH #15.
rkh authored
88 === Conditions
89
17cb177 @cypher README and CHANGES tweaks for 0.9.0 release (#63)
cypher authored
90 Routes may include a variety of matching conditions, such as the user agent:
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
91
1776a80 Added Version and Docs
Blake Mizerany authored
92 get '/foo', :agent => /Songbird (\d\.\d)[\d\/]*?/ do
93 "You're using Songbird version #{params[:agent][0]}"
94 end
95
96 get '/foo' do
a734cf3 @rtomayko I knew I shoulda taken that left turn at Hoboken
rtomayko authored
97 # Matches non-songbird browsers
1776a80 Added Version and Docs
Blake Mizerany authored
98 end
df800b5 Docs are started
Blake Mizerany authored
99
fa52709 @rkh fix markup for inline code in README
rkh authored
100 Other available conditions are +host_name+ and +provides+:
726feeb @rkh Documentation for condition. Fixes GH #15.
rkh authored
101
102 get '/', :host_name => /^admin\./ do
103 "Admin Area, Access denied!"
104 end
105
106 get '/', :provides => 'html' do
107 haml :index
108 end
109
110 get '/', :provides => ['rss', 'atom', 'xml'] do
111 builder :feed
112 end
113
114 You can easily define your own conditions:
115
116 set(:probability) { |value| condition { rand <= value } }
117
118 get '/win_a_car', :probability => 0.1 do
119 "You won!"
120 end
121
122 get '/win_a_car' do
123 "Sorry, you lost."
124 end
125
aaeb564 @rkh document route return values, fixes GH #23
rkh authored
126 === Return values
127
128 The return value of a route block determines at least the response body passed
129 on to the HTTP client, or at least the next middleware in the Rack stack.
130 Most commonly this is a string, as in the above examples. But other values are
131 also accepted.
132
c6d0614 @rkh Minor README improvements.
rkh authored
133 You can return any object that would either be a valid Rack response, Rack
134 body object or HTTP status code:
aaeb564 @rkh document route return values, fixes GH #23
rkh authored
135
626f689 @rkh fix markup for multi word inline code in README
rkh authored
136 * An Array with three elements: <tt>[status (Fixnum), headers (Hash), response body (responds to #each)]</tt>
137 * An Array with two elements: <tt>[status (Fixnum), response body (responds to #each)]</tt>
9c73cf7 @rkh fix markup for multi word inline code in README, take two (apparently…
rkh authored
138 * An object that responds to <tt>#each</tt> and passes nothing but strings to the given block
aaeb564 @rkh document route return values, fixes GH #23
rkh authored
139 * A Fixnum representing the status code
140
141 That way we can for instance easily implement a streaming example:
142
143 class Stream
144 def each
145 100.times { |i| yield "#{i}\n" }
146 end
147 end
148
8fbd9c2 @rkh Simplify streaming example.
rkh authored
149 get('/') { Stream.new }
aaeb564 @rkh document route return values, fixes GH #23
rkh authored
150
a734cf3 @rtomayko I knew I shoulda taken that left turn at Hoboken
rtomayko authored
151 == Static Files
047edc6 update README with Static help
Blake Mizerany authored
152
17cb177 @cypher README and CHANGES tweaks for 0.9.0 release (#63)
cypher authored
153 Static files are served from the <tt>./public</tt> directory. You can specify
154 a different location by setting the <tt>:public</tt> option:
a734cf3 @rtomayko I knew I shoulda taken that left turn at Hoboken
rtomayko authored
155
156 set :public, File.dirname(__FILE__) + '/static'
df800b5 Docs are started
Blake Mizerany authored
157
4298a77 @rtomayko Tweak README formatting; move community/contributing to website
rtomayko authored
158 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
159 <tt>./public/css/style.css</tt> is made available as
160 <tt>http://example.com/css/style.css</tt>.
4298a77 @rtomayko Tweak README formatting; move community/contributing to website
rtomayko authored
161
17cb177 @cypher README and CHANGES tweaks for 0.9.0 release (#63)
cypher authored
162 == Views / Templates
df800b5 Docs are started
Blake Mizerany authored
163
4298a77 @rtomayko Tweak README formatting; move community/contributing to website
rtomayko authored
164 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
165 directory. To use a different views directory:
a734cf3 @rtomayko I knew I shoulda taken that left turn at Hoboken
rtomayko authored
166
167 set :views, File.dirname(__FILE__) + '/templates'
168
06161bf @cypher Note on passing template symbols vs. strings in README
cypher authored
169 One important thing to remember is that you always have to reference
170 templates with symbols, even if they're in a subdirectory (in this
1255737 @michelc Added a transition to better explain that templates must be defined w…
michelc authored
171 case use <tt>:'subdir/template'</tt>). You must use a symbol because
172 otherwise rendering methods will render any strings passed to them
173 directly.
06161bf @cypher Note on passing template symbols vs. strings in README
cypher authored
174
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
175 === Haml Templates
df800b5 Docs are started
Blake Mizerany authored
176
9fc3f1d @rkh README formatting adjustments
rkh authored
177 The <tt>haml</tt> gem/library is required to render HAML templates:
17cb177 @cypher README and CHANGES tweaks for 0.9.0 release (#63)
cypher authored
178
314a98f @rkh Remove uneccessary # from READMEs.
rkh authored
179 # You'll need to require haml in your app
801163e @bmizerany closes #9779 Auto-require haml/erb/builder/sass
bmizerany authored
180 require 'haml'
181
df800b5 Docs are started
Blake Mizerany authored
182 get '/' do
183 haml :index
184 end
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
185
186 Renders <tt>./views/index.haml</tt>.
187
0321ada @dougireton In README docs, fix links to HAML and SASS Options pages.
dougireton authored
188 {Haml's options}[http://haml-lang.com/docs/yardoc/file.HAML_REFERENCE.html#options]
d359dc9 @kematzy Merge app-level haml/sass options with call options [#184]
kematzy authored
189 can be set globally through Sinatra's configurations,
190 see {Options and Configurations}[http://www.sinatrarb.com/configuration.html],
191 and overridden on an individual basis.
192
c37db5c @rkh minor adjustments and fixes for the readme examples
rkh authored
193 set :haml, :format => :html5 # default Haml format is :xhtml
d359dc9 @kematzy Merge app-level haml/sass options with call options [#184]
kematzy authored
194
195 get '/' do
c37db5c @rkh minor adjustments and fixes for the readme examples
rkh authored
196 haml :index, :format => :html4 # overridden
d359dc9 @kematzy Merge app-level haml/sass options with call options [#184]
kematzy authored
197 end
198
199
17cb177 @cypher README and CHANGES tweaks for 0.9.0 release (#63)
cypher authored
200 === Erb Templates
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
201
314a98f @rkh Remove uneccessary # from READMEs.
rkh authored
202 # You'll need to require erb in your app
801163e @bmizerany closes #9779 Auto-require haml/erb/builder/sass
bmizerany authored
203 require 'erb'
204
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
205 get '/' do
206 erb :index
207 end
208
9eb72a4 @rkh Explain how to replace ERB with Erubis.
rkh authored
209 Renders <tt>./views/index.erb</tt>.
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
210
9eb72a4 @rkh Explain how to replace ERB with Erubis.
rkh authored
211 === Erubis Templates
7c5d693 @sr Doc for erubis
sr authored
212
9fc3f1d @rkh README formatting adjustments
rkh authored
213 The <tt>erubis</tt> gem/library is required to render Erubis templates:
7c5d693 @sr Doc for erubis
sr authored
214
314a98f @rkh Remove uneccessary # from READMEs.
rkh authored
215 # You'll need to require erubis in your app
7c5d693 @sr Doc for erubis
sr authored
216 require 'erubis'
217
218 get '/' do
219 erubis :index
220 end
221
9eb72a4 @rkh Explain how to replace ERB with Erubis.
rkh authored
222 Renders <tt>./views/index.erubis</tt>.
223
224 It is also possible to replace Erb with Erubis:
225
226 require 'erubis'
227 Tilt.register :erb, Tilt[:erubis]
228
229 get '/' do
230 erb :index
231 end
232
233 Renders <tt>./views/index.erb</tt> with Erubis.
7c5d693 @sr Doc for erubis
sr authored
234
17cb177 @cypher README and CHANGES tweaks for 0.9.0 release (#63)
cypher authored
235 === Builder Templates
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
236
9fc3f1d @rkh README formatting adjustments
rkh authored
237 The <tt>builder</tt> gem/library is required to render builder templates:
df800b5 Docs are started
Blake Mizerany authored
238
314a98f @rkh Remove uneccessary # from READMEs.
rkh authored
239 # You'll need to require builder in your app
801163e @bmizerany closes #9779 Auto-require haml/erb/builder/sass
bmizerany authored
240 require 'builder'
241
17cb177 @cypher README and CHANGES tweaks for 0.9.0 release (#63)
cypher authored
242 get '/' do
243 builder :index
244 end
245
246 Renders <tt>./views/index.builder</tt>.
247
dd81da1 @rkh Add nokogiri helper method. Tilt supports Nokogiri for quite some tim…
rkh authored
248 === Nokogiri Templates
249
9fc3f1d @rkh README formatting adjustments
rkh authored
250 The <tt>nokogiri</tt> gem/library is required to render nokogiri templates:
dd81da1 @rkh Add nokogiri helper method. Tilt supports Nokogiri for quite some tim…
rkh authored
251
314a98f @rkh Remove uneccessary # from READMEs.
rkh authored
252 # You'll need to require nokogiri in your app
dd81da1 @rkh Add nokogiri helper method. Tilt supports Nokogiri for quite some tim…
rkh authored
253 require 'nokogiri'
254
255 get '/' do
256 nokogiri :index
257 end
258
259 Renders <tt>./views/index.nokogiri</tt>.
260
17cb177 @cypher README and CHANGES tweaks for 0.9.0 release (#63)
cypher authored
261 === Sass Templates
262
9fc3f1d @rkh README formatting adjustments
rkh authored
263 The <tt>haml</tt> or <tt>sass</tt> gem/library is required to render Sass templates:
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
264
314a98f @rkh Remove uneccessary # from READMEs.
rkh authored
265 # You'll need to require haml or sass in your app
801163e @bmizerany closes #9779 Auto-require haml/erb/builder/sass
bmizerany authored
266 require 'sass'
267
4144ac1 @nmeans Added Sass information to documentation.
nmeans authored
268 get '/stylesheet.css' do
269 sass :stylesheet
270 end
271
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
272 Renders <tt>./views/stylesheet.sass</tt>.
273
0321ada @dougireton In README docs, fix links to HAML and SASS Options pages.
dougireton authored
274 {Sass' options}[http://sass-lang.com/docs/yardoc/file.SASS_REFERENCE.html#options]
d359dc9 @kematzy Merge app-level haml/sass options with call options [#184]
kematzy authored
275 can be set globally through Sinatra's configurations,
276 see {Options and Configurations}[http://www.sinatrarb.com/configuration.html],
277 and overridden on an individual basis.
278
c37db5c @rkh minor adjustments and fixes for the readme examples
rkh authored
279 set :sass, :style => :compact # default Sass style is :nested
d359dc9 @kematzy Merge app-level haml/sass options with call options [#184]
kematzy authored
280
281 get '/stylesheet.css' do
b90d00c @sr Update sass example re. options
sr authored
282 sass :stylesheet, :style => :expanded # overridden
d359dc9 @kematzy Merge app-level haml/sass options with call options [#184]
kematzy authored
283 end
284
cf3c218 @pedromenezes Adding scss support through specific command
pedromenezes authored
285 === Scss Templates
286
9fc3f1d @rkh README formatting adjustments
rkh authored
287 The <tt>haml</tt> or <tt>sass</tt> gem/library is required to render Scss templates:
cf3c218 @pedromenezes Adding scss support through specific command
pedromenezes authored
288
314a98f @rkh Remove uneccessary # from READMEs.
rkh authored
289 # You'll need to require haml or sass in your app
cf3c218 @pedromenezes Adding scss support through specific command
pedromenezes authored
290 require 'sass'
291
292 get '/stylesheet.css' do
293 scss :stylesheet
294 end
295
296 Renders <tt>./views/stylesheet.scss</tt>.
297
298 {Scss' options}[http://sass-lang.com/docs/yardoc/file.SASS_REFERENCE.html#options]
299 can be set globally through Sinatra's configurations,
300 see {Options and Configurations}[http://www.sinatrarb.com/configuration.html],
301 and overridden on an individual basis.
302
c37db5c @rkh minor adjustments and fixes for the readme examples
rkh authored
303 set :scss, :style => :compact # default Scss style is :nested
cf3c218 @pedromenezes Adding scss support through specific command
pedromenezes authored
304
305 get '/stylesheet.css' do
306 scss :stylesheet, :style => :expanded # overridden
307 end
308
621bfcb @Ptico Added Less support
Ptico authored
309 === Less Templates
310
9fc3f1d @rkh README formatting adjustments
rkh authored
311 The <tt>less</tt> gem/library is required to render Less templates:
621bfcb @Ptico Added Less support
Ptico authored
312
314a98f @rkh Remove uneccessary # from READMEs.
rkh authored
313 # You'll need to require less in your app
621bfcb @Ptico Added Less support
Ptico authored
314 require 'less'
315
316 get '/stylesheet.css' do
317 less :stylesheet
318 end
319
320 Renders <tt>./views/stylesheet.less</tt>.
321
28a3a35 @rkh Add liquid helper method. Tilt supports liquid for quite some time no…
rkh authored
322 === Liquid Templates
323
9fc3f1d @rkh README formatting adjustments
rkh authored
324 The <tt>liquid</tt> gem/library is required to render Liquid templates:
28a3a35 @rkh Add liquid helper method. Tilt supports liquid for quite some time no…
rkh authored
325
314a98f @rkh Remove uneccessary # from READMEs.
rkh authored
326 # You'll need to require liquid in your app
28a3a35 @rkh Add liquid helper method. Tilt supports liquid for quite some time no…
rkh authored
327 require 'liquid'
328
329 get '/' do
330 liquid :index
331 end
332
333 Renders <tt>./views/index.liquid</tt>.
334
335 Since you cannot call Ruby methods (except for +yield+) from a Liquid
336 template, you almost always want to pass locals to it:
337
338 liquid :index, :locals => { :key => 'value' }
339
970169b @rkh Add markdown helper method. Tilt supports markdown for quite some tim…
rkh authored
340 === Markdown Templates
341
9fc3f1d @rkh README formatting adjustments
rkh authored
342 The <tt>rdiscount</tt> gem/library is required to render Markdown templates:
970169b @rkh Add markdown helper method. Tilt supports markdown for quite some tim…
rkh authored
343
314a98f @rkh Remove uneccessary # from READMEs.
rkh authored
344 # You'll need to require rdiscount in your app
970169b @rkh Add markdown helper method. Tilt supports markdown for quite some tim…
rkh authored
345 require "rdiscount"
346
347 get '/' do
348 markdown :index
349 end
350
351 Renders <tt>./views/index.markdown</tt> (+md+ and +mkd+ are also valid file
352 extensions).
353
a743c7d @rkh Add BlueCloth example to README.
rkh authored
354 It is not possible to call methods from markdown, nor to pass locals to it.
355 You therefore will usually use it in combination with another rendering
356 engine:
970169b @rkh Add markdown helper method. Tilt supports markdown for quite some tim…
rkh authored
357
358 erb :overview, :locals => { :text => markdown(:introduction) }
359
a743c7d @rkh Add BlueCloth example to README.
rkh authored
360 Note that you may also call the +markdown+ method from within other templates:
970169b @rkh Add markdown helper method. Tilt supports markdown for quite some tim…
rkh authored
361
362 %h1 Hello From Haml!
363 %p= markdown(:greetings)
364
a0f4717 @rkh Explain how to use :layout_engine in README.
rkh authored
365 Since you cannot call Ruby from Markdown, you cannot use layouts written in
366 Markdown. However, it is possible to use another rendering engine for the
367 template than for the layout by passing the `:layout_engine` option:
368
369 get '/' do
370 markdown :index, :layout_engine => :erb
371 end
372
373 This will render <tt>./views/index.md</tt> with <tt>./views/layout.erb</tt> as
374 layout.
375
376 Remember that you can set such rendering options globally:
377
378 set :markdown, :layout_engine => :haml, :layout => :post
379
380 get '/' do
381 markdown :index
382 end
383
384 This will render <tt>./views/index.md</tt> (and any other Markdown template)
385 with <tt>./views/post.haml</tt> as layout.
386
a743c7d @rkh Add BlueCloth example to README.
rkh authored
387 It is also possible to parse Markdown with BlueCloth rather than RDiscount:
388
389 require 'bluecloth'
390
391 Tilt.register 'markdown', BlueClothTemplate
392 Tilt.register 'mkd', BlueClothTemplate
393 Tilt.register 'md', BlueClothTemplate
394
395 get '/' do
396 markdown :index
397 end
398
399 Renders <tt>./views/index.md</tt> with BlueCloth.
400
b464e02 @rkh Add textile helper method. Tilt supports textile for quite some time …
rkh authored
401 === Textile Templates
402
9fc3f1d @rkh README formatting adjustments
rkh authored
403 The <tt>RedCloth</tt> gem/library is required to render Textile templates:
b464e02 @rkh Add textile helper method. Tilt supports textile for quite some time …
rkh authored
404
314a98f @rkh Remove uneccessary # from READMEs.
rkh authored
405 # You'll need to require redcloth in your app
b464e02 @rkh Add textile helper method. Tilt supports textile for quite some time …
rkh authored
406 require "redcloth"
407
408 get '/' do
409 textile :index
410 end
411
412 Renders <tt>./views/index.textile</tt>.
413
a743c7d @rkh Add BlueCloth example to README.
rkh authored
414 It is not possible to call methods from textile, nor to pass locals to it. You
415 therefore will usually use it in combination with another rendering engine:
b464e02 @rkh Add textile helper method. Tilt supports textile for quite some time …
rkh authored
416
417 erb :overview, :locals => { :text => textile(:introduction) }
418
9fc3f1d @rkh README formatting adjustments
rkh authored
419 Note that you may also call the +textile+ method from within other templates:
b464e02 @rkh Add textile helper method. Tilt supports textile for quite some time …
rkh authored
420
421 %h1 Hello From Haml!
422 %p= textile(:greetings)
423
a0f4717 @rkh Explain how to use :layout_engine in README.
rkh authored
424 Since you cannot call Ruby from Textile, you cannot use layouts written in
425 Textile. However, it is possible to use another rendering engine for the
426 template than for the layout by passing the `:layout_engine` option:
427
428 get '/' do
429 textile :index, :layout_engine => :erb
430 end
431
432 This will render <tt>./views/index.textile</tt> with
433 <tt>./views/layout.erb</tt> as layout.
434
435 Remember that you can set such rendering options globally:
436
437 set :textile, :layout_engine => :haml, :layout => :post
438
439 get '/' do
440 textile :index
441 end
442
443 This will render <tt>./views/index.textile</tt> (and any other Textile
444 template) with <tt>./views/post.haml</tt> as layout.
445
c248dba @rkh Add rdoc helper method. Tilt supports RDoc for quite some time now, b…
rkh authored
446 === RDoc Templates
447
9fc3f1d @rkh README formatting adjustments
rkh authored
448 The <tt>rdoc</tt> gem/library is required to render RDoc templates:
c248dba @rkh Add rdoc helper method. Tilt supports RDoc for quite some time now, b…
rkh authored
449
314a98f @rkh Remove uneccessary # from READMEs.
rkh authored
450 # You'll need to require rdoc in your app
c248dba @rkh Add rdoc helper method. Tilt supports RDoc for quite some time now, b…
rkh authored
451 require "rdoc"
452
453 get '/' do
454 rdoc :index
455 end
456
457 Renders <tt>./views/index.rdoc</tt>.
458
a743c7d @rkh Add BlueCloth example to README.
rkh authored
459 It is not possible to call methods from rdoc, nor to pass locals to it. You
460 therefore will usually use it in combination with another rendering engine:
c248dba @rkh Add rdoc helper method. Tilt supports RDoc for quite some time now, b…
rkh authored
461
462 erb :overview, :locals => { :text => rdoc(:introduction) }
463
9fc3f1d @rkh README formatting adjustments
rkh authored
464 Note that you may also call the +rdoc+ method from within other templates:
c248dba @rkh Add rdoc helper method. Tilt supports RDoc for quite some time now, b…
rkh authored
465
466 %h1 Hello From Haml!
467 %p= rdoc(:greetings)
468
a0f4717 @rkh Explain how to use :layout_engine in README.
rkh authored
469 Since you cannot call Ruby from RDoc, you cannot use layouts written in
470 RDoc. However, it is possible to use another rendering engine for the
471 template than for the layout by passing the `:layout_engine` option:
472
473 get '/' do
474 rdoc :index, :layout_engine => :erb
475 end
476
477 This will render <tt>./views/index.rdoc</tt> with <tt>./views/layout.erb</tt> as
478 layout.
479
480 Remember that you can set such rendering options globally:
481
482 set :rdoc, :layout_engine => :haml, :layout => :post
483
484 get '/' do
485 rdoc :index
486 end
487
488 This will render <tt>./views/index.rdoc</tt> (and any other RDoc template)
489 with <tt>./views/post.haml</tt> as layout.
490
7cb94f2 @rkh Add radius helper method. Tilt supports radius for quite some time no…
rkh authored
491 === Radius Templates
492
9fc3f1d @rkh README formatting adjustments
rkh authored
493 The <tt>radius</tt> gem/library is required to render Radius templates:
7cb94f2 @rkh Add radius helper method. Tilt supports radius for quite some time no…
rkh authored
494
314a98f @rkh Remove uneccessary # from READMEs.
rkh authored
495 # You'll need to require radius in your app
7cb94f2 @rkh Add radius helper method. Tilt supports radius for quite some time no…
rkh authored
496 require 'radius'
497
498 get '/' do
499 radius :index
500 end
501
502 Renders <tt>./views/index.radius</tt>.
503
504 Since you cannot call Ruby methods (except for +yield+) from a Radius
505 template, you almost always want to pass locals to it:
506
507 radius :index, :locals => { :key => 'value' }
508
8ce74b3 @rkh Add markaby helper method. Tilt supports Markaby for quite some time …
rkh authored
509 === Markaby Templates
510
9fc3f1d @rkh README formatting adjustments
rkh authored
511 The <tt>markaby</tt> gem/library is required to render Markaby templates:
8ce74b3 @rkh Add markaby helper method. Tilt supports Markaby for quite some time …
rkh authored
512
314a98f @rkh Remove uneccessary # from READMEs.
rkh authored
513 # You'll need to require markaby in your app
8ce74b3 @rkh Add markaby helper method. Tilt supports Markaby for quite some time …
rkh authored
514 require 'markaby'
515
516 get '/' do
517 markaby :index
518 end
519
520 Renders <tt>./views/index.mab</tt>.
521
ee2e6ad @rkh No need to point out inline Markaby require Tilt 1.2, since we alread…
rkh authored
522 You may also use inline Markaby:
0ff41a6 @rkh Add support for passing a block to the markaby method:
rkh authored
523
524 get '/' do
525 markaby { h1 "Welcome!" }
526 end
527
ca7fbe5 @rkh Add documentation for Slim templates.
rkh authored
528 === Slim Templates
529
37cef00 @rkh More README formatting.
rkh authored
530 The <tt>slim</tt> gem/library is required to render Slim templates:
ca7fbe5 @rkh Add documentation for Slim templates.
rkh authored
531
314a98f @rkh Remove uneccessary # from READMEs.
rkh authored
532 # You'll need to require slim in your app
ca7fbe5 @rkh Add documentation for Slim templates.
rkh authored
533 require 'slim'
534
535 get '/' do
536 slim :index
537 end
538
539 Renders <tt>./views/index.slim</tt>.
540
f58d015 @rkh Add coffee helper method. Tilt supports CoffeeScript again, but it wa…
rkh authored
541 === CoffeeScript Templates
542
de11b44 @rkh Update CoffeeScript section with requirements for ruby-coffee-script …
rkh authored
543 The <tt>coffee-script</tt> gem/library and at least <b>one</b> of the
544 following options to execute JavaScript:
545
546 * +node+ (from Node.js) in your path
547 * you must be running on OSX
548 * +therubyracer+ gem/library
549
550 See http://github.com/josh/ruby-coffee-script for an updated list of options.
551
552 Now you can render CoffeeScript templates:
f58d015 @rkh Add coffee helper method. Tilt supports CoffeeScript again, but it wa…
rkh authored
553
314a98f @rkh Remove uneccessary # from READMEs.
rkh authored
554 # You'll need to require coffee-script in your app
f58d015 @rkh Add coffee helper method. Tilt supports CoffeeScript again, but it wa…
rkh authored
555 require 'coffee-script'
556
557 get '/application.js' do
558 coffee :application
559 end
560
561 Renders <tt>./views/application.coffee</tt>.
562
705c93f @rkh Rename one of the two 'Inline Templates' sections to 'Embedded Templa…
rkh authored
563 === Embedded Templates
df800b5 Docs are started
Blake Mizerany authored
564
565 get '/' do
566 haml '%div.title Hello World'
567 end
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
568
705c93f @rkh Rename one of the two 'Inline Templates' sections to 'Embedded Templa…
rkh authored
569 Renders the embedded template string.
df800b5 Docs are started
Blake Mizerany authored
570
4298a77 @rtomayko Tweak README formatting; move community/contributing to website
rtomayko authored
571 === Accessing Variables in Templates
df800b5 Docs are started
Blake Mizerany authored
572
5018264 @rtomayko Tidy up README a bit; link to @sinatra on Twitter
rtomayko authored
573 Templates are evaluated within the same context as route handlers. Instance
574 variables set in route handlers are direcly accessible by templates:
df800b5 Docs are started
Blake Mizerany authored
575
576 get '/:id' do
577 @foo = Foo.find(params[:id])
95aca76 @bleything fix documentation of variable interpolation into templates
bleything authored
578 haml '%h1= @foo.name'
df800b5 Docs are started
Blake Mizerany authored
579 end
580
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
581 Or, specify an explicit Hash of local variables:
df800b5 Docs are started
Blake Mizerany authored
582
583 get '/:id' do
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
584 foo = Foo.find(params[:id])
95aca76 @bleything fix documentation of variable interpolation into templates
bleything authored
585 haml '%h1= foo.name', :locals => { :foo => foo }
df800b5 Docs are started
Blake Mizerany authored
586 end
587
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
588 This is typically used when rendering templates as partials from within
589 other templates.
590
3ef8eed @sr Deprecate use_in_file_templates!
sr authored
591 === Inline Templates
83cba9c @bmizerany updated README with helpful tidbits
bmizerany authored
592
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
593 Templates may be defined at the end of the source file:
83cba9c @bmizerany updated README with helpful tidbits
bmizerany authored
594
eec7d21 @bmizerany In-file-templates are automaticly loaded for you.
bmizerany authored
595 require 'sinatra'
596
83cba9c @bmizerany updated README with helpful tidbits
bmizerany authored
597 get '/' do
598 haml :index
599 end
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
600
83cba9c @bmizerany updated README with helpful tidbits
bmizerany authored
601 __END__
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
602
f71330e @bmizerany quick doc fix
bmizerany authored
603 @@ layout
17cb177 @cypher README and CHANGES tweaks for 0.9.0 release (#63)
cypher authored
604 %html
605 = yield
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
606
f71330e @bmizerany quick doc fix
bmizerany authored
607 @@ index
83cba9c @bmizerany updated README with helpful tidbits
bmizerany authored
608 %div.title Hello world!!!!!
609
6584711 @rkh Minor markup fix in README.
rkh authored
610 NOTE: Inline templates defined in the source file that requires sinatra are
ca624fd @rkh Fix the minor markup fix in README.
rkh authored
611 automatically loaded. Call <tt>enable :inline_templates</tt> explicitly if you
3ef8eed @sr Deprecate use_in_file_templates!
sr authored
612 have inline templates in other source files.
eec7d21 @bmizerany In-file-templates are automaticly loaded for you.
bmizerany authored
613
4298a77 @rtomayko Tweak README formatting; move community/contributing to website
rtomayko authored
614 === Named Templates
615
5018264 @rtomayko Tidy up README a bit; link to @sinatra on Twitter
rtomayko authored
616 Templates may also be defined using the top-level <tt>template</tt> method:
83cba9c @bmizerany updated README with helpful tidbits
bmizerany authored
617
618 template :layout do
17cb177 @cypher README and CHANGES tweaks for 0.9.0 release (#63)
cypher authored
619 "%html\n =yield\n"
83cba9c @bmizerany updated README with helpful tidbits
bmizerany authored
620 end
621
622 template :index do
623 '%div.title Hello World!'
624 end
625
626 get '/' do
627 haml :index
628 end
629
17cb177 @cypher README and CHANGES tweaks for 0.9.0 release (#63)
cypher authored
630 If a template named "layout" exists, it will be used each time a template
9420a9b @burningTyger added disable :layout by default
burningTyger authored
631 is rendered. You can individually disable layouts by passing <tt>:layout => false</tt>
632 or disable them by default via <tt>set :haml, :layout => false</tt>.
578bbab @djanowski Updating README for :layout => true.
djanowski authored
633
634 get '/' do
635 haml :index, :layout => !request.xhr?
636 end
637
d7aa6a3 @rkh Add 'Associating File Extensions' section to README.
rkh authored
638 === Associating File Extensions
639
640 To associate a file extension with a template engine, use
641 <tt>Tilt.register</tt>. For instance, if you like to use the file extension
642 +tt+ for Textile templates, you can do the following:
643
644 Tilt.register :tt, Tilt[:textile]
645
9269686 @rkh Add "Adding You Own Template Engine" section to README.
rkh authored
646 === Adding You Own Template Engine
647
648 First, register your engine with Tilt, then create a rendering method:
649
650 Tilt.register :myat, MyAwesomeTemplateEngine
651
652 helpers do
653 def myat(*args) render(:myat, *args) end
654 end
655
656 get '/' do
657 myat :index
658 end
659
660 Renders <tt>./views/index.myat</tt>. See https://github.com/rtomayko/tilt to
661 learn more about Tilt.
662
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
663 == Filters
df800b5 Docs are started
Blake Mizerany authored
664
c6d0614 @rkh Minor README improvements.
rkh authored
665 Before filters are evaluated before each request within the same context as
666 the routes will be and can modify the request and response. Instance variables
667 set in filters are accessible by routes and templates:
1776a80 Added Version and Docs
Blake Mizerany authored
668
df800b5 Docs are started
Blake Mizerany authored
669 before do
a734cf3 @rtomayko I knew I shoulda taken that left turn at Hoboken
rtomayko authored
670 @note = 'Hi!'
671 request.path_info = '/foo/bar/baz'
672 end
673
674 get '/foo/*' do
675 @note #=> 'Hi!'
676 params[:splat] #=> 'bar/baz'
df800b5 Docs are started
Blake Mizerany authored
677 end
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
678
c6d0614 @rkh Minor README improvements.
rkh authored
679 After filter are evaluated after each request within the same context and can
680 also modify the request and response. Instance variables set in before filters
681 and routes are accessible by after filters:
4e50ddb @jschementi Adds after filters
jschementi authored
682
683 after do
684 puts response.status
685 end
686
380c312 @rkh Document accessing response body in after filter. Fixes #168.
rkh authored
687 Note: Unless you use the `body` method rather than just returning a String from
688 the routes, the body will not yet be available in the after filter, since it is
689 generated later on.
690
c6d0614 @rkh Minor README improvements.
rkh authored
691 Filters optionally taking a pattern, causing them to be evaluated only if the
692 request path matches that pattern:
da047d3 @rkh add pattern matching to before/after filters.
rkh authored
693
694 before '/protected/*' do
695 authenticate!
696 end
697
698 after '/create/:slug' do |slug|
699 session[:last_slug] = slug
700 end
701
7a9101a @rkh Like routes, filters now also take conditions:
rkh authored
702 Like routes, filters also take conditions:
703
704 before :agent => /Songbird/ do
705 # ...
706 end
707
708 after '/blog/*', :host_name => 'example.com' do
709 # ...
710 end
711
08d5682 @rkh reorganizing helpers in readme
rkh authored
712 == Helpers
713
714 Use the top-level <tt>helpers</tt> method to define helper methods for use in
715 route handlers and templates:
716
717 helpers do
718 def bar(name)
719 "#{name}bar"
720 end
721 end
722
723 get '/:name' do
724 bar(params[:name])
725 end
726
727 === Halting
a734cf3 @rtomayko I knew I shoulda taken that left turn at Hoboken
rtomayko authored
728
4e50ddb @jschementi Adds after filters
jschementi authored
729 To immediately stop a request within a filter or route use:
df800b5 Docs are started
Blake Mizerany authored
730
17cb177 @cypher README and CHANGES tweaks for 0.9.0 release (#63)
cypher authored
731 halt
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
732
c6d0614 @rkh Minor README improvements.
rkh authored
733 You can also specify the status when halting:
fbbd822 @sr More 'halt' doc
sr authored
734
735 halt 410
736
c6d0614 @rkh Minor README improvements.
rkh authored
737 Or the body:
df800b5 Docs are started
Blake Mizerany authored
738
17cb177 @cypher README and CHANGES tweaks for 0.9.0 release (#63)
cypher authored
739 halt 'this will be the body'
df800b5 Docs are started
Blake Mizerany authored
740
c6d0614 @rkh Minor README improvements.
rkh authored
741 Or both:
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
742
17cb177 @cypher README and CHANGES tweaks for 0.9.0 release (#63)
cypher authored
743 halt 401, 'go away!'
df800b5 Docs are started
Blake Mizerany authored
744
c6d0614 @rkh Minor README improvements.
rkh authored
745 With headers:
fbbd822 @sr More 'halt' doc
sr authored
746
747 halt 402, {'Content-Type' => 'text/plain'}, 'revenge'
748
08d5682 @rkh reorganizing helpers in readme
rkh authored
749 === Passing
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
750
5018264 @rtomayko Tidy up README a bit; link to @sinatra on Twitter
rtomayko authored
751 A route can punt processing to the next matching route using <tt>pass</tt>:
df800b5 Docs are started
Blake Mizerany authored
752
17cb177 @cypher README and CHANGES tweaks for 0.9.0 release (#63)
cypher authored
753 get '/guess/:who' do
754 pass unless params[:who] == 'Frank'
6c9488e @sr Stick to single quote; kill a blank line
sr authored
755 'You got me!'
17cb177 @cypher README and CHANGES tweaks for 0.9.0 release (#63)
cypher authored
756 end
757
758 get '/guess/*' do
6c9488e @sr Stick to single quote; kill a blank line
sr authored
759 'You missed!'
17cb177 @cypher README and CHANGES tweaks for 0.9.0 release (#63)
cypher authored
760 end
761
762 The route block is immediately exited and control continues with the next
763 matching route. If no matching route is found, a 404 is returned.
df800b5 Docs are started
Blake Mizerany authored
764
2eae940 @rkh document redirect, fixes #162
rkh authored
765 === Setting Body and Status Code
9a22d7c @rkh Document body and status helper methods. Fixes #146.
rkh authored
766
767 It is possible and recommended to set the status code and response body with the
768 return value of the route block. However, in some scenarios you might want to
769 set the body at an arbritary point in the execution flow. You can do so with the
770 `body` helper method. If you do so, you can use that method from there on to
771 access the body:
772
c0e95f7 @rkh fix readme example indentation
rkh authored
773 get '/foo' do
774 body "bar"
775 end
776
777 after do
778 puts body
779 end
9a22d7c @rkh Document body and status helper methods. Fixes #146.
rkh authored
780
781 It is also possible to pass a block to body, that will be executed by the rack
782 handler (this can be used to implement streaming, see
783 [Return values](#Return%20values)).
784
785 Similar to the body, you can also set the status code:
786
787 get '/foo' do
788 status 418
789 halt "I'm a tea pot!"
790 end
791
ef54086 @rkh document url helper
rkh authored
792 === Generating URLs
793
794 For generating URLs you should use the `url` helper method, for instance, in
795 Haml:
796
797 %a{:href => url('/foo')} foo
798
799 It takes reverse proxies and Rack routers into account, if present.
800
801 This method is also aliased to `to` (see [below](#Browser%20Redirect) for an
802 example).
803
2eae940 @rkh document redirect, fixes #162
rkh authored
804 === Browser Redirect
805
806 You can trigger a browser redirect with the `redirect` helper method:
807
808 get '/foo' do
da9bfde @rkh use url helper for redirects in README
rkh authored
809 redirect to('/bar')
2eae940 @rkh document redirect, fixes #162
rkh authored
810 end
811
812 Any additional parameters are handled like arguments passed to `halt`:
813
da9bfde @rkh use url helper for redirects in README
rkh authored
814 redirect to('/bar'), 303
815 redirect 'http://google.com', 'wrong place, buddy'
2eae940 @rkh document redirect, fixes #162
rkh authored
816
fac44f7 @rkh document `redirect back`
rkh authored
817 You can also easily redirect back to the page the user came from with
818 `redirect back`:
819
820 get '/foo' do
821 "<a href='/bar'>do something</a>"
822 end
823
824 get '/bar' do
825 do_something
826 redirect back
827 end
828
2eae940 @rkh document redirect, fixes #162
rkh authored
829 To pass arguments with a redirect, either add them to the query:
830
da9bfde @rkh use url helper for redirects in README
rkh authored
831 redirect to('/bar?sum=42')
2eae940 @rkh document redirect, fixes #162
rkh authored
832
833 Or use a session:
834
835 enable :session
836
837 get '/foo' do
838 session[:secret] = 'foo'
da9bfde @rkh use url helper for redirects in README
rkh authored
839 redirect to('/bar')
2eae940 @rkh document redirect, fixes #162
rkh authored
840 end
841
842 get '/bar' do
843 session[:secret]
844 end
845
ec25544 @rkh document send_file, fixes #140
rkh authored
846 === Sending Files
847
848 For sending files, you can use the `send_file` helper method:
849
850 get '/' do
851 send_file 'foo.png'
852 end
853
854 It also take a couple of options:
855
856 send_file 'foo.png', :type => :jpg
857
858 The options are:
859
bd542e9 @rkh improve readme markup for send_file documentation
rkh authored
860 [filename]
861 file name in response, defaults to the real file name.
862
863 [last_modified]
864 value for Last-Modified header, defaults to the file's mtime.
865
866 [type]
867 content type to use, guessed from the file extension if missing.
868
869 [disposition]
870 used for Content-Disposition, possible values: +nil+ (default),
871 <tt>:attachement</tt> and <tt>:inline</tt>
872
873 [length]
874 Content-Length header, defaults to file size.
ec25544 @rkh document send_file, fixes #140
rkh authored
875
876 If supported by the Rack handler, other means than streaming from the Ruby
877 process will be used. If you use this helper method, Sinatra will automatically
878 handle range requests.
879
08d5682 @rkh reorganizing helpers in readme
rkh authored
880 === Accessing the Request Object
df0e534 @rkh Document request object. Fixes GH #60.
rkh authored
881
3297a61 Fix typo in README.
Lee Jarvis authored
882 The incoming request object can be accessed from request level (filter, routes, error handlers) through the `request` method:
df0e534 @rkh Document request object. Fixes GH #60.
rkh authored
883
884 # app running on http://example.com/example
885 get '/foo' do
886 request.body # request body sent by the client (see below)
887 request.scheme # "http"
888 request.script_name # "/example"
889 request.path_info # "/foo"
890 request.port # 80
891 request.request_method # "GET"
892 request.query_string # ""
893 request.content_length # length of request.body
894 request.media_type # media type of request.body
895 request.host # "example.com"
896 request.get? # true (similar methods for other verbs)
897 request.form_data? # false
898 request["SOME_HEADER"] # value of SOME_HEADER header
899 request.referer # the referer of the client or '/'
900 request.user_agent # user agent (used by :agent condition)
901 request.cookies # hash of browser cookies
902 request.xhr? # is this an ajax request?
903 request.url # "http://example.com/example/foo"
904 request.path # "/example/foo"
905 request.ip # client IP address
906 request.secure? # false
df7cc20 @nouse fix a minor spell mistake
nouse authored
907 request.env # raw env hash handed in by Rack
df0e534 @rkh Document request object. Fixes GH #60.
rkh authored
908 end
909
1fd52d1 @rkh Fix markup
rkh authored
910 Some options, like <tt>script_name</tt> or <tt>path_info</tt> can also be
911 written:
df0e534 @rkh Document request object. Fixes GH #60.
rkh authored
912
913 before { request.path_info = "/" }
914
915 get "/" do
916 "all requests end up here"
917 end
918
919 The <tt>request.body</tt> is an IO or StringIO object:
920
921 post "/api" do
922 request.body.rewind # in case someone already read it
923 data = JSON.parse request.body.read
924 "Hello #{data['name']}!"
925 end
926
13fc79d @rtomayko Remove support for source file reloading [#166]
rtomayko authored
927 == Configuration
1776a80 Added Version and Docs
Blake Mizerany authored
928
17cb177 @cypher README and CHANGES tweaks for 0.9.0 release (#63)
cypher authored
929 Run once, at startup, in any environment:
1776a80 Added Version and Docs
Blake Mizerany authored
930
931 configure do
6136da5 @rkh better documentation on how to use configure
rkh authored
932 # setting one option
933 set :option, 'value'
934
935 # setting multiple options
936 set :a => 1, :b => 2
937
938 # same as `set :option, true`
939 enable :option
940
941 # same as `set :option, false`
942 disable :option
943
944 # you can also have dynamic settings with blocks
945 set(:css_dir) { File.join(views, 'css') }
1776a80 Added Version and Docs
Blake Mizerany authored
946 end
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
947
17cb177 @cypher README and CHANGES tweaks for 0.9.0 release (#63)
cypher authored
948 Run only when the environment (RACK_ENV environment variable) is set to
13fc79d @rtomayko Remove support for source file reloading [#166]
rtomayko authored
949 <tt>:production</tt>:
1776a80 Added Version and Docs
Blake Mizerany authored
950
951 configure :production do
e75f4b3 @rtomayko misc README formatting tweaks
rtomayko authored
952 ...
1776a80 Added Version and Docs
Blake Mizerany authored
953 end
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
954
13fc79d @rtomayko Remove support for source file reloading [#166]
rtomayko authored
955 Run when the environment is set to either <tt>:production</tt> or
956 <tt>:test</tt>:
1776a80 Added Version and Docs
Blake Mizerany authored
957
958 configure :production, :test do
e75f4b3 @rtomayko misc README formatting tweaks
rtomayko authored
959 ...
1776a80 Added Version and Docs
Blake Mizerany authored
960 end
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
961
6136da5 @rkh better documentation on how to use configure
rkh authored
962 You can access those options via <tt>settings</tt>:
963
964 configure do
965 set :foo, 'bar'
966 end
967
968 get '/' do
969 settings.foo? # => true
970 settings.foo # => 'bar'
971 ...
972 end
973
3297472 @rkh document available settings
rkh authored
974 === Available Settings
975
976 [absolute_redirects] If disabled, Sinatra will allow relative redirects,
977 however, Sinatra will no longer conform with RFC 2616
978 (HTTP 1.1), which only allows absolute redirects.
979
980 Enable if your app is running behind a reverse proxy that
981 has not been set up properly. Note that the +url+ helper
982 will still produce absolute URLs, unless you pass in
983 +false+ as second parameter.
984
985 Disabled per default.
986
987 [add_charsets] mime types the <tt>content_type</tt> helper will
988 automatically add the charset info to.
989
990 You should add to it rather than overriding this option:
991
992 settings.add_charsets << "application/foobar"
993
994 [app_file] main application file, used to detect project root,
995 views and public folder and inline templates
996
997 [bind] IP address to bind to (default: 0.0.0.0).
998 Only used for built-in server.
999
1000 [default_encoding] encoding to assume if unknown
1001 (defaults to <tt>"utf-8"</tt>)
1002
1003 [dump_errors] display errors in the log
1004
1005 [environment] current environment, defaults to <tt>ENV['RACK_ENV']</tt>,
1006 or <tt>"development"</tt> if not available
1007
1008 [logging] use the logger
1009
1010 [lock] Places a lock around every request, only running
1011 processing on request per Ruby process concurrently.
1012
1013 Enabled if your app is not thread-safe.
1014 Disabled per default.
1015
1016 [method_override] use <tt>_method</tt> magic to allow put/delete forms in
1017 browsers that don't support it
1018
1019 [port] Port to listen on. Only used for built-in server.
1020
1021 [prefixed_redirects] Whether or not to insert <tt>request.script_name</tt> into
1022 redirects if no absolute path is given. That way
1023 <tt>redirect '/foo'</tt> would behave like
1024 <tt>redirect to('/foo')</tt>. Disabled per default.
1025
1026 [public] folder public files are server from
1027
1028 [reload_templates] whether or not to reload templates between requests.
1029 enabled in development mode and on Ruby 1.8.6 (to
1030 compensate a bug in Ruby causing a memory leak)
1031
1032 [root] project root folder
1033
1034 [raise_errors] raise exceptions (will stop application)
1035
1036 [run] if enabled, Sinatra will handle starting the webserver,
1037 do not enable if using rackup or other means.
1038
1039 [running] is the built-in server running now?
1040 do not change this setting!
1041
1042 [server] server or list of servers to use for built-in server.
1043 defaults to ['thin', 'mongrel', 'webrick'], order indicates
1044 priority.
1045
1046 [sessions] enable cookie based sessions
1047
1048 [show_exceptions] show a stacktrace in the browser
1049
1050 [static] Whether Sinatra should handle serving static files.
1051 Disable when using a Server able to do this on its own.
1052 Disabling will boost performance.
1053 Enabled per default.
1054
1055 [views] views folder
1056
83a1683 @rkh Use same capitalization for all headings.
rkh authored
1057 == Error Handling
1776a80 Added Version and Docs
Blake Mizerany authored
1058
17cb177 @cypher README and CHANGES tweaks for 0.9.0 release (#63)
cypher authored
1059 Error handlers run within the same context as routes and before filters, which
c6d0614 @rkh Minor README improvements.
rkh authored
1060 means you get all the goodies it has to offer, like <tt>haml</tt>,
1061 <tt>erb</tt>, <tt>halt</tt>, etc.
1776a80 Added Version and Docs
Blake Mizerany authored
1062
e75f4b3 @rtomayko misc README formatting tweaks
rtomayko authored
1063 === Not Found
1776a80 Added Version and Docs
Blake Mizerany authored
1064
17cb177 @cypher README and CHANGES tweaks for 0.9.0 release (#63)
cypher authored
1065 When a <tt>Sinatra::NotFound</tt> exception is raised, or the response's status
1066 code is 404, the <tt>not_found</tt> handler is invoked:
1776a80 Added Version and Docs
Blake Mizerany authored
1067
1068 not_found do
c6d0614 @rkh Minor README improvements.
rkh authored
1069 'This is nowhere to be found.'
1776a80 Added Version and Docs
Blake Mizerany authored
1070 end
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
1071
e75f4b3 @rtomayko misc README formatting tweaks
rtomayko authored
1072 === Error
83cba9c @bmizerany updated README with helpful tidbits
bmizerany authored
1073
17cb177 @cypher README and CHANGES tweaks for 0.9.0 release (#63)
cypher authored
1074 The +error+ handler is invoked any time an exception is raised from a route
63fd773 @sr Small doc fix re. after filter
sr authored
1075 block or a filter. The exception object can be obtained from the
4298a77 @rtomayko Tweak README formatting; move community/contributing to website
rtomayko authored
1076 <tt>sinatra.error</tt> Rack variable:
83cba9c @bmizerany updated README with helpful tidbits
bmizerany authored
1077
1776a80 Added Version and Docs
Blake Mizerany authored
1078 error do
17cb177 @cypher README and CHANGES tweaks for 0.9.0 release (#63)
cypher authored
1079 'Sorry there was a nasty error - ' + env['sinatra.error'].name
83cba9c @bmizerany updated README with helpful tidbits
bmizerany authored
1080 end
1081
e75f4b3 @rtomayko misc README formatting tweaks
rtomayko authored
1082 Custom errors:
83cba9c @bmizerany updated README with helpful tidbits
bmizerany authored
1083
1084 error MyCustomError do
e7e0e55 @rtomayko Minor docfixes in README.rdoc
rtomayko authored
1085 'So what happened was...' + request.env['sinatra.error'].message
1776a80 Added Version and Docs
Blake Mizerany authored
1086 end
83cba9c @bmizerany updated README with helpful tidbits
bmizerany authored
1087
e75f4b3 @rtomayko misc README formatting tweaks
rtomayko authored
1088 Then, if this happens:
83cba9c @bmizerany updated README with helpful tidbits
bmizerany authored
1089
1090 get '/' do
1091 raise MyCustomError, 'something bad'
1092 end
1093
e75f4b3 @rtomayko misc README formatting tweaks
rtomayko authored
1094 You get this:
83cba9c @bmizerany updated README with helpful tidbits
bmizerany authored
1095
1096 So what happened was... something bad
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
1097
59e797e @sr Doc for error(500) { }
sr authored
1098 Alternatively, you can install error handler for a status code:
1099
1100 error 403 do
1101 'Access forbidden'
1102 end
1103
1104 get '/secret' do
1105 403
1106 end
1107
1108 Or a range:
1109
1110 error 400..510 do
1111 'Boom'
1112 end
1113
4298a77 @rtomayko Tweak README formatting; move community/contributing to website
rtomayko authored
1114 Sinatra installs special <tt>not_found</tt> and <tt>error</tt> handlers when
1115 running under the development environment.
83cba9c @bmizerany updated README with helpful tidbits
bmizerany authored
1116
83a1683 @rkh Use same capitalization for all headings.
rkh authored
1117 == Mime Types
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
1118
17cb177 @cypher README and CHANGES tweaks for 0.9.0 release (#63)
cypher authored
1119 When using <tt>send_file</tt> or static files you may have mime types Sinatra
6d8b333 @sr Update README re. mime_type
sr authored
1120 doesn't understand. Use +mime_type+ to register them by file extension:
83cba9c @bmizerany updated README with helpful tidbits
bmizerany authored
1121
6d8b333 @sr Update README re. mime_type
sr authored
1122 mime_type :foo, 'text/foo'
1776a80 Added Version and Docs
Blake Mizerany authored
1123
cb8fcb6 @sr Doc for content_type :foo
sr authored
1124 You can also use it with the +content_type+ helper:
1125
1126 content_type :foo
1127
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
1128 == Rack Middleware
bda21f1 @rtomayko add doc on using Rack middleware to README
rtomayko authored
1129
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
1130 Sinatra rides on Rack[http://rack.rubyforge.org/], a minimal standard
1131 interface for Ruby web frameworks. One of Rack's most interesting capabilities
1132 for application developers is support for "middleware" -- components that sit
1133 between the server and your application monitoring and/or manipulating the
1134 HTTP request/response to provide various types of common functionality.
bda21f1 @rtomayko add doc on using Rack middleware to README
rtomayko authored
1135
e75f4b3 @rtomayko misc README formatting tweaks
rtomayko authored
1136 Sinatra makes building Rack middleware pipelines a cinch via a top-level
1137 +use+ method:
bda21f1 @rtomayko add doc on using Rack middleware to README
rtomayko authored
1138
1139 require 'sinatra'
1140 require 'my_custom_middleware'
1141
1142 use Rack::Lint
1143 use MyCustomMiddleware
1144
1145 get '/hello' do
1146 'Hello World'
1147 end
1148
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
1149 The semantics of +use+ are identical to those defined for the
1150 Rack::Builder[http://rack.rubyforge.org/doc/classes/Rack/Builder.html] DSL
1151 (most frequently used from rackup files). For example, the +use+ method
1152 accepts multiple/variable args as well as blocks:
bda21f1 @rtomayko add doc on using Rack middleware to README
rtomayko authored
1153
1154 use Rack::Auth::Basic do |username, password|
1155 username == 'admin' && password == 'secret'
1156 end
1157
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
1158 Rack is distributed with a variety of standard middleware for logging,
1159 debugging, URL routing, authentication, and session handling. Sinatra uses
1160 many of of these components automatically based on configuration so you
1161 typically don't have to +use+ them explicitly.
bda21f1 @rtomayko add doc on using Rack middleware to README
rtomayko authored
1162
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
1163 == Testing
1776a80 Added Version and Docs
Blake Mizerany authored
1164
c831278 @rtomayko Recommend Rack::Test in README / note Sinatra::Test deprecation
rtomayko authored
1165 Sinatra tests can be written using any Rack-based testing library
1166 or framework. {Rack::Test}[http://gitrdoc.com/brynary/rack-test] is
1167 recommended:
c00a25e @rtomayko Test framework refactoring
rtomayko authored
1168
7cfe04a @jcrosby Fix for test/unit and test/spec docs
jcrosby authored
1169 require 'my_sinatra_app'
c3f167f @xentek MOD: docs for testing forgot to require test/unit
xentek authored
1170 require 'test/unit'
c831278 @rtomayko Recommend Rack::Test in README / note Sinatra::Test deprecation
rtomayko authored
1171 require 'rack/test'
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
1172
1776a80 Added Version and Docs
Blake Mizerany authored
1173 class MyAppTest < Test::Unit::TestCase
c831278 @rtomayko Recommend Rack::Test in README / note Sinatra::Test deprecation
rtomayko authored
1174 include Rack::Test::Methods
1175
1176 def app
1177 Sinatra::Application
1178 end
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
1179
2f377e2 @rtomayko Trim down Testing section in the README; link to doc site instead
rtomayko authored
1180 def test_my_default
c00a25e @rtomayko Test framework refactoring
rtomayko authored
1181 get '/'
c831278 @rtomayko Recommend Rack::Test in README / note Sinatra::Test deprecation
rtomayko authored
1182 assert_equal 'Hello World!', last_response.body
1776a80 Added Version and Docs
Blake Mizerany authored
1183 end
10c90d5 @sr document testing with rspec
sr authored
1184
2f377e2 @rtomayko Trim down Testing section in the README; link to doc site instead
rtomayko authored
1185 def test_with_params
c831278 @rtomayko Recommend Rack::Test in README / note Sinatra::Test deprecation
rtomayko authored
1186 get '/meet', :name => 'Frank'
1187 assert_equal 'Hello Frank!', last_response.body
10c90d5 @sr document testing with rspec
sr authored
1188 end
1189
2f377e2 @rtomayko Trim down Testing section in the README; link to doc site instead
rtomayko authored
1190 def test_with_rack_env
c831278 @rtomayko Recommend Rack::Test in README / note Sinatra::Test deprecation
rtomayko authored
1191 get '/', {}, 'HTTP_USER_AGENT' => 'Songbird'
1192 assert_equal "You're using Songbird!", last_response.body
1fb5b99 @dylanegan Bacon support
dylanegan authored
1193 end
1194 end
1195
c831278 @rtomayko Recommend Rack::Test in README / note Sinatra::Test deprecation
rtomayko authored
1196 NOTE: The built-in Sinatra::Test module and Sinatra::TestHarness class
1197 are deprecated as of the 0.9.2 release.
1776a80 Added Version and Docs
Blake Mizerany authored
1198
5360333 @sr Add a note about Sinatra::Base to the README
sr authored
1199 == Sinatra::Base - Middleware, Libraries, and Modular Apps
1200
1201 Defining your app at the top-level works well for micro-apps but has
69791f7 @rkh Minor README adjustments.
rkh authored
1202 considerable drawbacks when building reusable components such as Rack
5360333 @sr Add a note about Sinatra::Base to the README
sr authored
1203 middleware, Rails metal, simple libraries with a server component, or
1204 even Sinatra extensions. The top-level DSL pollutes the Object namespace
1205 and assumes a micro-app style configuration (e.g., a single application
1206 file, ./public and ./views directories, logging, exception detail page,
1207 etc.). That's where Sinatra::Base comes into play:
1208
1209 require 'sinatra/base'
1210
1211 class MyApp < Sinatra::Base
1212 set :sessions, true
1213 set :foo, 'bar'
1214
1215 get '/' do
1216 'Hello world!'
1217 end
1218 end
1219
1220 The methods available to Sinatra::Base subclasses are exactly as those
1221 available via the top-level DSL. Most top-level apps can be converted to
1222 Sinatra::Base components with two modifications:
1223
1224 * Your file should require +sinatra/base+ instead of +sinatra+;
1225 otherwise, all of Sinatra's DSL methods are imported into the main
1226 namespace.
1227 * Put your app's routes, error handlers, filters, and options in a subclass
1228 of Sinatra::Base.
1229
c4b9fdc @rkh Yet another markup fix for the README.
rkh authored
1230 <tt>Sinatra::Base</tt> is a blank slate. Most options are disabled by default,
5360333 @sr Add a note about Sinatra::Base to the README
sr authored
1231 including the built-in server. See {Options and Configuration}[http://sinatra.github.com/configuration.html]
1232 for details on available options and their behavior.
1233
0152335 @rkh document modular vs. classic style, fixes #138
rkh authored
1234 === Modular vs. Classic Style
1235
1236 Contrary to common believes, there is nothing wrong with classic style. If it
1237 suits your application, you do not have to switch to a modular application.
1238
1239 There are only two downsides compared to modulare style:
1240
1241 * You may only have one Sinatra application per Ruby process - if you plan to
1242 use more, switch to modular style.
1243
1244 * Classic style pollutes Object with delegator methods - if you plan to ship
1245 your application in a library/gem, switch to modular style.
1246
1247 There is no reason you cannot mix modular and classic style.
1248
1249 If switching from one style to the other, you should be aware of slight
1250 differences in the setting:
1251
1252 Setting Classic Modular
1253
1254 app_file file loading sinatra nil
1255 run $0 == app_file false
1256 logging true false
1257 method_override true false
1258 inline_templates true false
1259
1260
83a1683 @rkh Use same capitalization for all headings.
rkh authored
1261 === Serving a Modular Application
344955a @rkh explain using run! vs config.ru in readme
rkh authored
1262
1263 There are two common options for starting a modular app, activly starting with
1264 <tt>run!</tt>:
1265
1266 # my_app.rb
1267 require 'sinatra/base'
1268
1269 class MyApp < Sinatra::Base
1270 # ... app code here ...
1271
1272 # start the server if ruby file executed directly
1273 run! if app_file == $0
1274 end
1275
1276 Start with:
1277
1278 ruby my_app.rb
1279
1280 Or with a <tt>config.ru</tt>, which allows using any Rack handler:
1281
1282 # config.ru
1283 require 'my_app'
1284 run MyApp
1285
1286 Run:
1287
1288 rackup -p 4567
1289
83a1683 @rkh Use same capitalization for all headings.
rkh authored
1290 === Using a Classic Style Application with a config.ru
344955a @rkh explain using run! vs config.ru in readme
rkh authored
1291
1292 Write your app file:
1293
1294 # app.rb
1295 require 'sinatra'
1296
1297 get '/' do
1298 'Hello world!'
1299 end
1300
1301 And a corresponding <tt>config.ru</tt>:
1302
1303 require 'app'
1304 run Sinatra::Application
1305
1306 === When to use a config.ru?
1307
1308 Good signs you probably want to use a <tt>config.ru</tt>:
1309
1310 * You want to deploy with a different Rack handler (Passenger, Unicorn,
1311 Heroku, ...).
1312 * You want to use more than one subclass of <tt>Sinatra::Base</tt>.
1313 * You want to use Sinatra only for middleware, but not as endpoint.
1314
1315 <b>There is no need to switch to a <tt>config.ru</tt> only because you
1316 switched to modular style, and you don't have to use modular style for running
1317 with a <tt>config.ru</tt>.</b>
1318
69791f7 @rkh Minor README adjustments.
rkh authored
1319 === Using Sinatra as Middleware
5e8d501 @rkh Added "Using Sinatra as middleware" section, fixes GH #19.
rkh authored
1320
1321 Not only is Sinatra able to use other Rack middleware, any Sinatra application
1322 can in turn be added in front of any Rack endpoint as middleware itself. This
1323 endpoint could be another Sinatra application, or any other Rack-based
1324 application (Rails/Ramaze/Camping/...).
1325
1326 require 'sinatra/base'
1327
1328 class LoginScreen < Sinatra::Base
e6887fe @andrewhampton Fix typo in middleware example.
andrewhampton authored
1329 enable :sessions
5e8d501 @rkh Added "Using Sinatra as middleware" section, fixes GH #19.
rkh authored
1330
1331 get('/login') { haml :login }
1332
1333 post('/login') do
1334 if params[:name] = 'admin' and params[:password] = 'admin'
1335 session['user_name'] = params[:name]
1336 else
1337 redirect '/login'
1338 end
1339 end
1340 end
1341
1342 class MyApp < Sinatra::Base
1343 # middleware will run before filters
1344 use LoginScreen
1345
1346 before do
1347 unless session['user_name']
1348 halt "Access denied, please <a href='/login'>login</a>."
1349 end
1350 end
1351
1352 get('/') { "Hello #{session['user_name']}." }
1353 end
1354
3f21c3f @rkh Document different scopes/bindings.
rkh authored
1355 == Scopes and Binding
1356
6233ce4 @rkh Proof-reading Scopes section
rkh authored
1357 The scope you are currently in determines what methods and variables are
1358 available.
3f21c3f @rkh Document different scopes/bindings.
rkh authored
1359
1360 === Application/Class Scope
1361
1362 Every Sinatra application corresponds to a subclass of Sinatra::Base. If you
1363 are using the top level DSL (<tt>require 'sinatra'</tt>), then this class is
1364 Sinatra::Application, otherwise it is the subclass you created explicitly. At
1365 class level you have methods like `get` or `before`, but you cannot access the
1366 `request` object or the `session`, as there only is a single application class
1367 for all requests.
1368
1369 Options created via `set` are methods at class level:
1370
796d62a @kryzhovnik README.* fixed typos
kryzhovnik authored
1371 class MyApp < Sinatra::Base
3f21c3f @rkh Document different scopes/bindings.
rkh authored
1372 # Hey, I'm in the application scope!
1373 set :foo, 42
1374 foo # => 42
1375
1376 get '/foo' do
1377 # Hey, I'm no longer in the application scope!
1378 end
1379 end
1380
6233ce4 @rkh Proof-reading Scopes section
rkh authored
1381 You have the application scope binding inside:
3f21c3f @rkh Document different scopes/bindings.
rkh authored
1382
1383 * Your application class body
1384 * Methods defined by extensions
1385 * The block passed to `helpers`
1386 * Procs/blocks used as value for `set`
1387
1388 You can reach the scope object (the class) like this:
1389
6233ce4 @rkh Proof-reading Scopes section
rkh authored
1390 * Via the object passed to configure blocks (<tt>configure { |c| ... }</tt>)
3f21c3f @rkh Document different scopes/bindings.
rkh authored
1391 * `settings` from within request scope
1392
1393 === Request/Instance Scope
1394
6233ce4 @rkh Proof-reading Scopes section
rkh authored
1395 For every incoming request, a new instance of your application class is
1396 created and all handler blocks run in that scope. From within this scope you
1397 can access the `request` and `session` object or call rendering methods like
1398 `erb` or `haml`. You can access the application scope from within the request
1399 scope via the `settings` helper:
3f21c3f @rkh Document different scopes/bindings.
rkh authored
1400
796d62a @kryzhovnik README.* fixed typos
kryzhovnik authored
1401 class MyApp < Sinatra::Base
3f21c3f @rkh Document different scopes/bindings.
rkh authored
1402 # Hey, I'm in the application scope!
1403 get '/define_route/:name' do
1404 # Request scope for '/define_route/:name'
1405 @value = 42
1406
1407 settings.get("/#{params[:name]}") do
1408 # Request scope for "/#{params[:name]}"
1409 @value # => nil (not the same request)
1410 end
1411
1412 "Route defined!"
1413 end
1414 end
1415
6233ce4 @rkh Proof-reading Scopes section
rkh authored
1416 You have the request scope binding inside:
3f21c3f @rkh Document different scopes/bindings.
rkh authored
1417
ba1fd4c @jammur Updated README.rdoc to reflect added OPTIONS request type.
jammur authored
1418 * get/head/post/put/delete/options blocks
3f21c3f @rkh Document different scopes/bindings.
rkh authored
1419 * before/after filters
1420 * helper methods
1421 * templates/views
1422
1423 === Delegation Scope
1424
1425 The delegation scope just forwards methods to the class scope. However, it
6233ce4 @rkh Proof-reading Scopes section
rkh authored
1426 does not behave 100% like the class scope, as you do not have the class'
1427 binding: Only methods explicitly marked for delegation are available and you
1428 do not share variables/state with the class scope (read: you have a different
1429 `self`). You can explicitly add method delegations by calling
1430 <tt>Sinatra::Delegator.delegate :method_name</tt>.
3f21c3f @rkh Document different scopes/bindings.
rkh authored
1431
6233ce4 @rkh Proof-reading Scopes section
rkh authored
1432 You have the delegate scope binding inside:
3f21c3f @rkh Document different scopes/bindings.
rkh authored
1433
1434 * The top level binding, if you did <tt>require "sinatra"</tt>
6233ce4 @rkh Proof-reading Scopes section
rkh authored
1435 * An object extended with the `Sinatra::Delegator` mixin
3f21c3f @rkh Document different scopes/bindings.
rkh authored
1436
2e2e595 @rkh Remove Sinatra::Delegator sidebar (now covered by Scopes), keep "Have…
rkh authored
1437 Have a look at the code for yourself: here's the
1438 {Sinatra::Delegator mixin}[http://github.com/sinatra/sinatra/blob/ceac46f0bc129a6e994a06100aa854f606fe5992/lib/sinatra/base.rb#L1128]
69791f7 @rkh Minor README adjustments.
rkh authored
1439 being {included into the main namespace}[http://github.com/sinatra/sinatra/blob/ceac46f0bc129a6e994a06100aa854f606fe5992/lib/sinatra/main.rb#L28].
2e2e595 @rkh Remove Sinatra::Delegator sidebar (now covered by Scopes), keep "Have…
rkh authored
1440
83a1683 @rkh Use same capitalization for all headings.
rkh authored
1441 == Command Line
1776a80 Added Version and Docs
Blake Mizerany authored
1442
e75f4b3 @rtomayko misc README formatting tweaks
rtomayko authored
1443 Sinatra applications can be run directly:
f44fb6a @rtomayko grammar/formatting pass over README
rtomayko authored
1444
4d61607 @sr update README/CHANGES re. -o
sr authored
1445 ruby myapp.rb [-h] [-x] [-e ENVIRONMENT] [-p PORT] [-o HOST] [-s HANDLER]
1776a80 Added Version and Docs
Blake Mizerany authored
1446
1447 Options are:
1448
1449 -h # help
1450 -p # set the port (default is 4567)
4d61607 @sr update README/CHANGES re. -o
sr authored
1451 -o # set the host (default is 0.0.0.0)
1776a80 Added Version and Docs
Blake Mizerany authored
1452 -e # set the environment (default is development)
f29486b @karmi Note "-s" (server) command line option in README
karmi authored
1453 -s # specify rack server/handler (default is thin)
e7e0e55 @rtomayko Minor docfixes in README.rdoc
rtomayko authored
1454 -x # turn on the mutex lock (default is off)
1776a80 Added Version and Docs
Blake Mizerany authored
1455
4298a77 @rtomayko Tweak README formatting; move community/contributing to website
rtomayko authored
1456 == The Bleeding Edge
a44e2ad @rkh Update Bleeding Edge Section in README.
rkh authored
1457 If you would like to use Sinatra's latest bleeding code, feel free to run your
1458 application against the master branch, it should be rather stable.
1459
1460 We also push out prerelease gems from time to time, so you can do a
1461
1462 gem install sinatra --pre
1463
1464 To get some of the latest features.
1465
accc850 @rkh Recommend Bundler in Bleeding Edge documentation.
rkh authored
1466 === With Bundler
1467 If you want to run your application with the latest Sinatra, using
1468 {Bundler}[http://gembundler.com/] is the recommend way.
6326809 @cypher Add a subsection about tools needed for Sinatra to the Contributing s…
cypher authored
1469
accc850 @rkh Recommend Bundler in Bleeding Edge documentation.
rkh authored
1470 First, install bundler, if you haven't:
1471
1472 gem install bundler
1473
1474 Then, in you project directory, create a +Gemfile+:
1475
1476 source :rubygems
1477 gem 'sinatra', :git => "git://github.com/sinatra/sinatra.git"
1478
1479 # other dependencies
1480 gem 'haml' # for instance, if you use haml
1481 gem 'activerecord', '~> 3.0' # maybe you also need ActiveRecord 3.x
1482
1483 Note that you will have to list all your applications dependencies in there.
1484 Sinatra's direct dependencies (Rack and Tilt) will however be automatically
1485 fetched and added by Bundler.
1486
1487 Now you can run your app like this:
1488
1489 bundle exec ruby myapp.rb
1490
1491 === Roll Your Own
a44e2ad @rkh Update Bleeding Edge Section in README.
rkh authored
1492 Create a local clone and run your app with the <tt>sinatra/lib</tt> directory
1493 on the <tt>LOAD_PATH</tt>:
6326809 @cypher Add a subsection about tools needed for Sinatra to the Contributing s…
cypher authored
1494
4298a77 @rtomayko Tweak README formatting; move community/contributing to website
rtomayko authored
1495 cd myapp
ba92616 @bmizerany Updated README to point to github.com/sinatra/sinatra.git
bmizerany authored
1496 git clone git://github.com/sinatra/sinatra.git
4298a77 @rtomayko Tweak README formatting; move community/contributing to website
rtomayko authored
1497 ruby -Isinatra/lib myapp.rb
480fbfa @rtomayko minor formatting tweaks to cypher's README updates
rtomayko authored
1498
4298a77 @rtomayko Tweak README formatting; move community/contributing to website
rtomayko authored
1499 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
1500
317045c @rkh make paths in example consistent
rkh authored
1501 cd myapp/sinatra
4298a77 @rtomayko Tweak README formatting; move community/contributing to website
rtomayko authored
1502 git pull
e6c5471 @cypher Add a community section with info about the mailing list and irc channel
cypher authored
1503
a44e2ad @rkh Update Bleeding Edge Section in README.
rkh authored
1504 === Install Globally
1505
1506 You can build the gem on your own:
1507
1508 git clone git://github.com/sinatra/sinatra.git
1509 cd sinatra
1510 rake sinatra.gemspec
1511 rake install
1512
1513 If you install gems as root, the last step should be
1514
1515 sudo rake install
1516
83a1683 @rkh Use same capitalization for all headings.
rkh authored
1517 == Further Reading
e6c5471 @cypher Add a community section with info about the mailing list and irc channel
cypher authored
1518
754f116 @rtomayko README: better links to project website and mailing list
rtomayko authored
1519 * {Project Website}[http://www.sinatrarb.com/] - Additional documentation,
4298a77 @rtomayko Tweak README formatting; move community/contributing to website
rtomayko authored
1520 news, and links to other resources.
754f116 @rtomayko README: better links to project website and mailing list
rtomayko authored
1521 * {Contributing}[http://www.sinatrarb.com/contributing] - Find a bug? Need
4298a77 @rtomayko Tweak README formatting; move community/contributing to website
rtomayko authored
1522 help? Have a patch?
60ac449 @sr lighthouse => github issue
sr authored
1523 * {Issue tracker}[http://github.com/sinatra/sinatra/issues]
5018264 @rtomayko Tidy up README a bit; link to @sinatra on Twitter
rtomayko authored
1524 * {Twitter}[http://twitter.com/sinatra]
754f116 @rtomayko README: better links to project website and mailing list
rtomayko authored
1525 * {Mailing List}[http://groups.google.com/group/sinatrarb/topics]
4298a77 @rtomayko Tweak README formatting; move community/contributing to website
rtomayko authored
1526 * {IRC: #sinatra}[irc://chat.freenode.net/#sinatra] on http://freenode.net
Something went wrong with that request. Please try again.