forked from sinatra/sinatra.github.com
-
Notifications
You must be signed in to change notification settings - Fork 0
/
book.html
1008 lines (673 loc) · 37.6 KB
/
book.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<div class='maruku_toc'><ul style='list-style: none;'><li><a href='#table_of_contents'>Table of Contents</a></li><li><a href='#introduction'>Introduction</a><ul style='list-style: none;'><li><a href='#what_is_sinatra'>What is Sinatra?</a></li><li><a href='#installation'>Installation</a><ul style='list-style: none;'><li><a href='#dependencies'>Dependencies</a></li><li><a href='#living_on_the_edge'>Living on the Edge</a></li></ul></li><li><a href='#hello_world_application'>Hello World Application</a></li><li><a href='#real_world_applications_in_sinatra'>Real World Applications in Sinatra</a><ul style='list-style: none;'><li><a href='#github_services'>Github Services</a></li><li><a href='#git_wiki'>Git Wiki</a></li><li><a href='#integrity'>Integrity</a></li><li><a href='#seinfeld_calendar'>Seinfeld Calendar</a></li></ul></li><li><a href='#about_this_book'>About this book</a></li></ul></li><li><a href='#routes'>Routes</a><ul style='list-style: none;'><li><a href='#http_methods'>HTTP methods</a></li><li><a href='#basic'>Basic</a></li><li><a href='#options'>Options</a></li><li><a href='#splats'>Splats</a></li><li><a href='#user_agent'>User agent</a></li><li><a href='#other_methods'>Other methods</a></li><li><a href='#the_put_and_delete_methods'>The PUT and DELETE methods</a></li><li><a href='#how_routes_are_looked_up'>How routes are looked up</a></li><li><a href='#splitting_into_multiple_files'>Splitting into multiple files</a></li></ul></li><li><a href='#handlers'>Handlers</a><ul style='list-style: none;'><li><a href='#structure'>Structure</a></li><li><a href='#redirect'>Redirect</a></li><li><a href='#sessions'>Sessions</a><ul style='list-style: none;'><li><a href='#default_cookie_based_sessions'>Default Cookie Based Sessions</a></li><li><a href='#memory_based_sessions'>Memory Based Sessions</a></li><li><a href='#memcached_based_sessions'>Memcached Based Sessions</a></li><li><a href='#file_based_sessions'>File Based Sessions</a></li><li><a href='#database_based_sessions'>Database Based Sessions</a></li></ul></li><li><a href='#cookies'>Cookies</a></li><li><a href='#status'>Status</a></li><li><a href='#authentication'>Authentication</a></li></ul></li><li><a href='#filters'>Filters</a><ul style='list-style: none;'><li><a href='#before_do'>before do…</a></li><li><a href='#handling_of_rails_like_nested_params'>Handling of Rails like nested params</a></li></ul></li><li><a href='#views'>Views</a><ul style='list-style: none;'><li><a href='#template_languages'>Template Languages</a><ul style='list-style: none;'><li><a href='#haml'>Haml</a></li><li><a href='#sass'>Sass</a></li><li><a href='#erb'>Erb</a></li><li><a href='#builder'>Builder</a><ul style='list-style: none;'><li><a href='#atom_feed'>Atom Feed</a></li><li><a href='#rss_feed'>RSS Feed</a></li></ul></li></ul></li><li><a href='#layouts'>Layouts</a></li><li><a href='#avoiding_a_layout'>Avoiding a layout</a></li><li><a href='#in_file_views'>In File Views</a></li><li><a href='#partials'>Partials</a></li></ul></li><li><a href='#models'>Models</a><ul style='list-style: none;'><li><a href='#datamapper'>Datamapper</a></li><li><a href='#sequel'>Sequel</a></li><li><a href='#activerecord'>ActiveRecord</a></li></ul></li><li><a href='#helpers'>Helpers</a><ul style='list-style: none;'><li><a href='#the_basics'>The basics</a></li><li><a href='#implemention_of_rails_style_partials'>Implemention of rails style partials</a></li></ul></li><li><a href='#rack_middleware'>Rack Middleware</a></li><li><a href='#error_handling'>Error Handling</a><ul style='list-style: none;'><li><a href='#not_found'>not_found</a></li><li><a href='#error'>error</a></li><li><a href='#additional_information'>Additional Information</a></li></ul></li><li><a href='#configuration'>Configuration</a><ul style='list-style: none;'><li><a href='#use_sinatras_set_option'>Use Sinatra’s “set” option</a></li><li><a href='#external_config_file_via_the_configure_block'>External config file via the configure block</a></li><li><a href='#application_module__config_area'>Application module / config area</a></li></ul></li><li><a href='#deployment'>Deployment</a><ul style='list-style: none;'><li><a href='#heroku'>Heroku</a></li><li><a href='#deployment_lighttpd'>Lighttpd Proxied to Thin</a></li><li><a href='#deployment_passenger'>Passenger (mod rails)</a></li><li><a href='#deployment_fastcgi'>FastCGI (Sinatra <= 0.3)</a></li></ul></li><li><a href='#contributing'>Contributing</a><ul style='list-style: none;'><li><a href='#how_can_i_clone_the_sinatra_repository'>How can I clone the Sinatra repository?</a></li><li><a href='#how_to_create_a_patch'>How to create a patch?</a></li><li><a href='#how_to_get_that_patch_into_the_official_sinatra'>How to get that patch into the official Sinatra?</a></li></ul></li></ul></div><hr />
<h1 id='introduction'>Introduction</h1>
<h2 id='what_is_sinatra'>What is Sinatra?</h2>
<p>Sinatra is a Domain Specific Language (DSL) for quickly creating web-applications in Ruby.</p>
<p>It keeps a minimal feature set, leaving the developer to use the tools that best suit them and their application.</p>
<p>It doesn’t assume much about your application, apart from that:</p>
<ul>
<li>it will be written in Ruby programming language</li>
<li>it will have URLs</li>
</ul>
<p>In Sinatra, you can write short <em>ad hoc</em> applications or mature, larger application with the same easiness. (See section “Real World Applications” later in this book.)</p>
<p>You can use the power of various Rubygems and other libraries for Ruby available.</p>
<p>Sinatra really shines when used for experiments and application mock-ups or for creating a quick interface for your code.</p>
<p>It isn’t a <em>typical</em> Model-View-Controller framework, but ties specific URL directly to relevant Ruby code and returns it’s output in response. It does enable you, however, to write clean, properly organized applications: separating <em>views</em> from application code, for instance.</p>
<h2 id='installation'>Installation</h2>
<p>The simplest way to obtain Sinatra is through Rubygems</p>
<pre><code>$ sudo gem install sinatra</code></pre>
<h3 id='dependencies'>Dependencies</h3>
<p>Sinatra depends on the <em>Rack</em> gem (http://rack.rubyforge.org).</p>
<p>For optimal experience, you should also install the <em>Haml</em> (http://haml.hamptoncatlin.com) and <em>Builder</em> gem (http://builder.rubyforge.org), which simplifies working with views.</p>
<pre><code>$ sudo gem install builder haml</code></pre>
<h3 id='living_on_the_edge'>Living on the Edge</h3>
<p>The <em>edge</em> version of Sinatra lives in it’s Git repository, available at <strong>http://github.com/sinatra/sinatra/tree/master</strong>.</p>
<p>You can use the <em>edge</em> version to try new functionality or to contribute to the framework. You need to have Git version control software installed (http://www.git-scm.com). Then follow these steps:</p>
<ol>
<li>cd where/you/keep/your/projects</li>
<li>git clone git://github.com/sinatra/sinatra.git</li>
<li>cd sinatra</li>
<li>cd your_project</li>
<li>ln -s ../sinatra</li>
</ol>
<p>Then add this to your application:</p>
<pre><code>$:.unshift File.dirname(__FILE__) + '/sinatra/lib'
require 'sinatra'</code></pre>
<p>You can check the version you are running by adding this route</p>
<pre><code>get '/about' do
"I'm running on Version " + Sinatra::VERSION
end</code></pre>
<p>and loading <code>http://localhost:4567/about</code> in your browser.</p>
<h2 id='hello_world_application'>Hello World Application</h2>
<p>Sinatra is installed and you’re done eating cake, how about making your first application?</p>
<pre><code># hello_world.rb
require 'rubygems'
require 'sinatra'
get '/' do
"Hello world, it's #{Time.now} at the server!"
end</code></pre>
<p>Run this application by <code>$ ruby hello_world.rb</code> and load <code>http://localhost:4567</code> in your browser.</p>
<p>As you can see, Sinatra doesn’t force you to setup much infrastructure: a request to some URL (<em>root</em> URL in this case) evaluates some Ruby code and returns some text in response.</p>
<h2 id='real_world_applications_in_sinatra'>Real World Applications in Sinatra</h2>
<h3 id='github_services'>Github Services</h3>
<p>Git hosting provider Github uses Sinatra for post-receive hooks, calling user specified services/URLs, whenever someone pushes to her repository:</p>
<ul>
<li>http://github.com/blog/53-github-services-ipo</li>
<li>http://github.com/guides/post-receive-hooks</li>
<li>http://github.com/pjhyett/github-services</li>
</ul>
<h3 id='git_wiki'>Git Wiki</h3>
<p>Git Wiki is minimal Wiki engine powered by Sinatra and Git. See also various forks with additional functionality.</p>
<ul>
<li>http://github.com/sr/git-wiki</li>
<li>http://github.com/sr/git-wiki/network</li>
</ul>
<h3 id='integrity'>Integrity</h3>
<p>Integrity is small and clean <em>continuous integration</em> service using Sinatra, watching for failing builds of your codebase and notifying you by various channels.</p>
<ul>
<li>http://www.integrityapp.com/</li>
<li>http://github.com/foca/integrity</li>
</ul>
<h3 id='seinfeld_calendar'>Seinfeld Calendar</h3>
<p>Seinfeld Calendar is a fun application tracking your contributions to open-source projects, displaying your “streaks”, ie. continuous commits to Github repositories.</p>
<ul>
<li>http://www.calendaraboutnothing.com</li>
<li>http://github.com/entp/seinfeld</li>
</ul>
<h2 id='about_this_book'>About this book</h2>
<p>This book will assume you have a basic knowledge of the Ruby scripting language and a working Ruby interpreter.</p>
<p>For more information about the Ruby language visit the following links:</p>
<ul>
<li>http://www.ruby-lang.org</li>
<li>http://www.ruby-lang.org/en/documentation/ruby-from-other-languages/</li>
<li>http://www.ruby-doc.org</li>
<li>http://www.ruby-doc.org/core-1.8.7/index.html</li>
<li>http://www.ruby-doc.org/docs/ProgrammingRuby/</li>
</ul>
<hr />
<h1 id='routes'>Routes</h1>
<h2 id='http_methods'>HTTP methods</h2>
<p>Sinatra’s routes are designed to respond to the HTTP request methods.</p>
<ul>
<li>GET</li>
<li>POST</li>
<li>PUT</li>
<li>DELETE</li>
</ul>
<h2 id='basic'>Basic</h2>
<p>Simple</p>
<pre><code>get '/hi' do
...
end</code></pre>
<p>With params</p>
<pre><code>get '/:name' do
# matches /sinatra and the like and sets params[:name]
end</code></pre>
<h2 id='options'>Options</h2>
<h2 id='splats'>Splats</h2>
<pre><code>get '/say/*/to/*' do
# matches /say/hello/to/world
params["splat"] # => ["hello", "world"]
end
get '/download/*.*' do
# matches /download/path/to/file.xml
params["splat"] # => ["path/to/file", "xml"]
end</code></pre>
<h2 id='user_agent'>User agent</h2>
<pre><code>get '/foo', :agent => /Songbird (\d\.\d)[\d\/]*?/ do
"You're using Songbird version #{params[:agent][0]}"
end
get '/foo' do
# matches non-songbird browsers
end</code></pre>
<h2 id='other_methods'>Other methods</h2>
<p>Other methods are requested exactly the same as “get” routes. You simply use the <code>post</code>, <code>put</code>, or <code>delete</code> functions to define the route, rather then the <code>get</code> one. To access POSTed parameters, use <code>params[:xxx]</code> where xxx is the name of the form element that was posted.</p>
<pre><code>post '/foo' do
"You just asked for foo, with post param bar equal to #{params[:bar]}"
end</code></pre>
<h2 id='the_put_and_delete_methods'>The PUT and DELETE methods</h2>
<p>Since browsers don’t natively support the PUT and DELETE methods, a hacky workaround has been adopted by the web community. Simply add a hidden element with the name “_method” and the value equal to the HTTP method you want to use. The form itself is sent as a POST, but Sinatra will interpret it as the desired method. For example:</p>
<pre><code><form method="post" action="/destroy_it">
<input name="_method" value="delete" />
<div><button type="submit">Destroy it</button></div>
</form></code></pre>
<p>When you want to use PUT or DELETE from a client that does support them (like Curl, or ActiveResource), just go ahead and use them as you normally would, and ignore the <code>_method</code> advice above. That is only for hacking in support for browsers.</p>
<h2 id='how_routes_are_looked_up'>How routes are looked up</h2>
<p>Each time you add a new route to your application, it gets compiled down into a regular expression that will match it. That is stored in an array along with the handler block attached to that route.</p>
<p>When a new request comes in, each regex is run in turn, until one matches. Then the the handler (the code block) attached to that route gets executed.</p>
<h2 id='splitting_into_multiple_files'>Splitting into multiple files</h2>
<p>Because Sinatra clears out your routes and reloads your application on every request in development mode, you can’t use require to load files containing your routes because these will only be loaded when the application starts (and reloaded even on the first request!) Instead, use <a href='http://www.ruby-doc.org/core/classes/Kernel.html#M005966' title='Ruby RDoc: load'>load</a>:</p>
<pre><code># application.rb
require 'rubygems'
require 'sinatra'
get '/' do
"Hello world!"
end
load 'more_routes.rb'</code></pre>
<p>and</p>
<pre><code># more_routes.rb
get '/foo' do
"Bar? How unimaginative."
end</code></pre>
<hr />
<h1 id='handlers'>Handlers</h1>
<h2 id='structure'>Structure</h2>
<p>Handler is the generic term that Sinatra uses for the “controllers”. A handler is the initial point of entry for new HTTP requests into your application.</p>
<p>To find more about the routes, head to the Routes section (right above this one)</p>
<h2 id='redirect'>Redirect</h2>
<p>The redirect helper is a shortcut to a common http response code (302).</p>
<p>Basic usage is easy:</p>
<pre><code>redirect '/'
redirect '/posts/1'
redirect 'http://www.google.com'</code></pre>
<p>The redirect actually sends back a Location header to the browser, and the browser makes a followup request to the location indicated. Since the browser makes that followup request, you can redirect to any page, in your application, or another site entirely.</p>
<p>The flow of requests during a redirect is: Browser → Server (redirect to ’/’) → Browser (request ’/’) → Server (result for ’/’)</p>
<p>To force Sinatra to send a different response code, it’s very simple:</p>
<pre><code>redirect '/', 303 # forces the 303 return code
redirect '/', 307 # forces the 307 return code</code></pre>
<h2 id='sessions'>Sessions</h2>
<h3 id='default_cookie_based_sessions'>Default Cookie Based Sessions</h3>
<p>Sinatra ships with basic support for cookie based sessions. To enable it, in a configure block, or at the top of your application, you just need to enable the option.</p>
<pre><code>enable :sessions
get '/' do
session["counter"] ||= 0
session["counter"] += 1
"You've hit this page #{session["counter"]} time(s)"
end</code></pre>
<p>The downside to this session approach is that all the data is stored in the cookie. Since cookies have a fairly hard limit of 4 kilobytes, you can’t store much data. The other issue is that cookies are not tamper proof. The user can change any data in their session. But… it is easy, and it doesn’t have the scaling problems that memory or database backed sessions run into.</p>
<h3 id='memory_based_sessions'>Memory Based Sessions</h3>
<h3 id='memcached_based_sessions'>Memcached Based Sessions</h3>
<h3 id='file_based_sessions'>File Based Sessions</h3>
<h3 id='database_based_sessions'>Database Based Sessions</h3>
<h2 id='cookies'>Cookies</h2>
<p>Cookies are a fairly simple thing to use in Sinatra, but they have a few quirks.</p>
<p>Lets first look at the simple use case:</p>
<pre><code>require 'rubygems'
require 'sinatra'
get '/' do
# Get the string representation
cookie = request.cookies["thing"]
# Set a default
cookie ||= 0
# Convert to an integer
cookie = cookie.to_i
# Do something with the value
cookie += 1
# Reset the cookie
set_cookie("thing", cookie)
# Render something
"Thing is now: #{cookie}"
end</code></pre>
<p>Setting a path, expiration date, or domain gets a little more complicated - see the source code for set_cookie if you want to dig deeper.</p>
<pre><code>set_cookie("thing", :domain => myDomain,
:path => myPath,
:expires => Date.new)</code></pre>
<p>That’s the easy stuff with cookies - It can also serialize Array objects, separating them with ampersands (&), but when they come back, it doesn’t deserialize or split them in any way, it hands you the raw, encoded string for your parsing pleasure.</p>
<h2 id='status'>Status</h2>
<p>If you want to set your own status response instead of the normal 200 (Success), you can use the <code>status</code>-helper to set the code, and then still render normally:</p>
<pre><code>get '/' do
status 404
"Not found"
end</code></pre>
<p>Alternatively you can use <code>throw :halt, [404, "Not found"]</code> to immediately stop any further actions and return the specified status code and string to the client. <code>throw</code> supports more options in this regard, see the appropriate section for more info.</p>
<h2 id='authentication'>Authentication</h2>
<hr />
<h1 id='filters'>Filters</h1>
<h2 id='before_do'>before do…</h2>
<p>These are run in Sinatra::EventContext</p>
<pre><code>before do
# .. this code will run before each event ..
end</code></pre>
<h2 id='handling_of_rails_like_nested_params'>Handling of Rails like nested params</h2>
<p>If you want to use a form with parameters like this (aka. Rails’ nested params):</p>
<pre><code><form>
<input ... name="post[title]" />
<input ... name="post[body]" />
<input ... name="post[author]" />
</form></code></pre>
<p>You have convert parameters to a hash. You can easily do this with a before filter:</p>
<pre><code>before do
new_params = {}
params.each_pair do |full_key, value|
this_param = new_params
split_keys = full_key.split(/\]\[|\]|\[/)
split_keys.each_index do |index|
break if split_keys.length == index + 1
this_param[split_keys[index]] ||= {}
this_param = this_param[split_keys[index]]
end
this_param[split_keys.last] = value
end
request.params.replace new_params
end</code></pre>
<p>Then parameters became:</p>
<pre><code>{"post"=>{ "title"=>"", "body"=>"", "author"=>"" }}</code></pre>
<hr />
<h1 id='views'>Views</h1>
<p>All file-based views are looked up in:</p>
<pre><code>root
| - views/</code></pre>
<h2 id='template_languages'>Template Languages</h2>
<h3 id='haml'>Haml</h3>
<pre><code>get '/' do
haml :index
end</code></pre>
<p>This will render ./views/index.haml</p>
<h3 id='sass'>Sass</h3>
<pre><code>get '/' do
sass :styles
end</code></pre>
<p>This will render ./views/styles.sass</p>
<h3 id='erb'>Erb</h3>
<pre><code>get '/' do
erb :index
end</code></pre>
<p>This will render ./views/index.erb</p>
<h3 id='builder'>Builder</h3>
<pre><code>get '/' do
builder :index
end</code></pre>
<p>This will render ./views/index.builder</p>
<pre><code>get '/' do
builder do |xml|
xml.node do
xml.subnode "Inner text"
end
end
end</code></pre>
<p>This will render the xml inline, directly from the handler.</p>
<h4 id='atom_feed'>Atom Feed</h4>
<h4 id='rss_feed'>RSS Feed</h4>
<p>Assume that your site url is http://liftoff.msfc.nasa.gov/.</p>
<pre><code>get '/rss.xml' do
builder do |xml|
xml.instruct! :xml, :version => '1.0'
xml.rss :version => "2.0" do
xml.channel do
xml.title "Liftoff News"
xml.description "Liftoff to Space Exploration."
xml.link "http://liftoff.msfc.nasa.gov/"
@posts.each do |post|
xml.item do
xml.title post.title
xml.link "http://liftoff.msfc.nasa.gov/posts/#{post.id}"
xml.description post.body
xml.pubDate Time.parse(post.created_at.to_s).rfc822()
xml.guid "http://liftoff.msfc.nasa.gov/posts/#{post.id}"
end
end
end
end
end
end</code></pre>
<p>This will render the rss inline, directly from the handler.</p>
<h2 id='layouts'>Layouts</h2>
<p>Layouts are simple in Sinatra. Put a file in your views directory named “layout.erb”, “layout.haml”, or “layout.builder”. When you render a page, the appropriate layout will be grabbed (of the same filetype), and used.</p>
<p>The layout itself should call <code>yield</code> at the point you want the content to be included.</p>
<p>An example haml layout file could look something like this:</p>
<pre><code>%html
%head
%title SINATRA BOOK
%body
#container
= yield</code></pre>
<h2 id='avoiding_a_layout'>Avoiding a layout</h2>
<dl>
<dt>Sometimes you don’t want the layout rendered. In your render method just pass</dt>
<dd>
<p>layout => false, and you’re good.</p>
<p>get ’/’ do haml :index, :layout => false end</p>
</dd>
</dl>
<h2 id='in_file_views'>In File Views</h2>
<p>This one is cool:</p>
<pre><code>get '/' do
haml :index
end
use_in_file_templates!
__END__
@@ layout
X
= yield
X
@@ index
%div.title Hello world!!!!!</code></pre>
<p>Try it!</p>
<h2 id='partials'>Partials</h2>
<hr />
<h1 id='models'>Models</h1>
<h2 id='datamapper'>Datamapper</h2>
<h2 id='sequel'>Sequel</h2>
<h2 id='activerecord'>ActiveRecord</h2>
<p>First require ActiveRecord gem in your app, then give your database connection settings:</p>
<pre><code>require 'rubygems'
require 'sinatra'
require 'activerecord'
ActiveRecord::Base.establish_connection(
:adapter => 'sqlite3',
:dbfile => 'sinatra_application.sqlite3.db'
)</code></pre>
<p>Now you can create and use ActiveRecord models just like in Rails (the example assumes you already have a ‘posts’ table in your database):</p>
<pre><code>class Post < ActiveRecord::Base
end
get '/' do
@posts = Post.all()
erb :index
end</code></pre>
<p>This will render ./views/index.html:</p>
<pre><code><% for post in @posts %>
<h1><% post.title %></h1>
<% end %></code></pre>
<hr />
<h1 id='helpers'>Helpers</h1>
<h2 id='the_basics'>The basics</h2>
<p>It is ill-advised to create helpers on the root level of your application. They muddy the global namespace, and don’t have easy access to the request, response, session or cookie variables.</p>
<p>Instead, use the handy helpers method to install methods on <code>Sinatra::EventContext</code> for use inside events and templates.</p>
<p>Example:</p>
<pre><code>helpers do
def bar(name)
"#{name}bar"
end
end
get '/:name' do
bar(params[:name])
end</code></pre>
<h2 id='implemention_of_rails_style_partials'>Implemention of rails style partials</h2>
<p>Using partials in your views is a great way to keep them clean. Since Sinatra takes the hands off approach to framework design, you’ll have to implement a partial handler yourself.</p>
<p>Here is a really basic version:</p>
<pre><code># Usage: partial :foo
helpers do
def partial(page, options={})
haml page, options.merge!(:layout => false)
end
end</code></pre>
<p>A more advanced version that would handle passing local options, and looping over a hash would look like:</p>
<pre><code># Render the page once:
# Usage: partial :foo
#
# foo will be rendered once for each element in the array, passing in a local variable named "foo"
# Usage: partial :foo, :collection => @my_foos
helpers do
def partial(template, *args)
options = args.extract_options!
options.merge!(:layout => false)
if collection = options.delete(:collection) then
collection.inject([]) do |buffer, member|
buffer << haml(template, options.merge(
:layout => false,
:locals => {template.to_sym => member}
)
)
end.join("\n")
else
haml(template, options)
end
end
end</code></pre>
<hr />
<h1 id='rack_middleware'>Rack Middleware</h1>
<p>Sinatra rides on <a href='http://rack.rubyforge.org/'>Rack</a>, a minimal standard interface for Ruby web frameworks. One of Rack’s most interesting capabilities for application developers is support for “middleware” – components that sit between the server and your application monitoring and/or manipulating the HTTP request/response to provide various types of common functionality.</p>
<p>Sinatra makes building Rack middleware pipelines a cinch via a top-level <code>use</code> method:</p>
<pre><code>require 'sinatra'
require 'my_custom_middleware'
use Rack::Lint
use MyCustomMiddleware
get '/hello' do
'Hello World'
end</code></pre>
<p>The semantics of “use” are identical to those defined for the <a href='http://rack.rubyforge.org/doc/classes/Rack/Builder.html'>Rack::Builder</a> DSL (most frequently used from rackup files). For example, the use method accepts multiple/variable args as well as blocks:</p>
<pre><code>use Rack::Auth::Basic do |username, password|
username == 'admin' && password == 'secret'
end</code></pre>
<p>Rack is distributed with a variety of standard middleware for logging, debugging, URL routing, authentication, and session handling. Sinatra uses many of of these components automatically based on configuration so you typically don’t have to use them explicitly.</p>
<hr />
<h1 id='error_handling'>Error Handling</h1>
<h2 id='not_found'>not_found</h2>
<p>Remember: These are run inside the Sinatra::EventContext which means you get all the goodies is has to offer (i.e. haml, erb, :halt, etc.)</p>
<p>Whenever NotFound is raised this will be called</p>
<pre><code>not_found do
'This is nowhere to be found'
end</code></pre>
<h2 id='error'>error</h2>
<p>By default error will catch Sinatra::ServerError</p>
<p>Sinatra will pass you the error via the ‘sinatra.error’ in request.env</p>
<pre><code>error do
'Sorry there was a nasty error - ' + request.env['sinatra.error'].name
end</code></pre>
<p>Custom error mapping:</p>
<pre><code>error MyCustomError do
'So what happened was...' + request.env['sinatra.error'].message
end</code></pre>
<p>then if this happens:</p>
<pre><code>get '/' do
raise MyCustomError, 'something bad'
end</code></pre>
<p>you gets this:</p>
<pre><code>So what happened was... something bad</code></pre>
<h2 id='additional_information'>Additional Information</h2>
<p>Because Sinatra give you a default not_found and error do :production that are secure. If you want to customize only for :production but want to keep the friendly helper screens for :development then do this:</p>
<pre><code>configure :production do
not_found do
"We're so sorry, but we don't what this is"
end
error do
"Something really nasty happened. We're on it!"
end
end</code></pre>
<hr />
<h1 id='configuration'>Configuration</h1>
<h2 id='use_sinatras_set_option'>Use Sinatra’s “set” option</h2>
<p>Configure blocks are not executed in the event context, and don’t have access to the same instance variables. To store a piece of information that you want to access in your routes, use <code>set</code>.</p>
<pre><code>configure :development do
set :dbname, 'devdb'
end
configure :production do
set :dbname, 'productiondb'
end</code></pre>
<p>…</p>
<pre><code>get '/whatdb' do
'We are using the database named ' + options.dbname
end</code></pre>
<h2 id='external_config_file_via_the_configure_block'>External config file via the configure block</h2>
<h2 id='application_module__config_area'>Application module / config area</h2>
<hr />
<h1 id='deployment'>Deployment</h1>
<h2 id='heroku'>Heroku</h2>
<p>This is the easiest configuration + deployment option. <a href='http://www.heroku.com'>Heroku</a> has full support for Sinatra applications. Deploying to Heroku is simply a matter of pushing to a remote git repository.</p>
<p>Steps to deploy to Heroku:</p>
<ul>
<li>Create an <a href='http://heroku.com/signup'>account</a> if you don’t have one</li>
<li><code>sudo gem install heroku</code></li>
<li>Make a config.ru in the root-directory</li>
<li>Create the app on heroku</li>
<li>Push to it</li>
</ul>
<ol>
<li>
<p>An example config.ru file (Heroku sets <code>RACK_ENV</code> to production for you)</p>
<pre><code>require "myapp"
run Sinatra::Application</code></pre>
</li>
<li>
<p>Create the app and push to it</p>
<pre><code>From the root-directory of the application
$ heroku create <app-name> # This will add heroku as a remote
$ git push heroku master</code></pre>
</li>
</ol>
<p>For more details see <a href='http://github.com/sinatra/heroku-sinatra-app'>this</a></p>
<h2 id='deployment_lighttpd'>Lighttpd Proxied to Thin</h2>
<p>This will cover how to deploy Sinatra to a load balanced reverse proxy setup using Lighttpd and Thin.</p>
<ol>
<li>
<p>Install Lighttpd and Thin</p>
<pre><code># Figure out lighttpd yourself, it should be handled by your
# linux distro's package manager
# For thin:
gem install thin</code></pre>
</li>
<li>
<p>Create your rackup file – the <code>require 'app'</code> line should require the actual Sinatra app you have written.</p>
<pre><code>## This is not needed for Thin > 1.0.0
ENV['RACK_ENV'] = "production"
require 'app'
run Sinatra::Application</code></pre>
</li>
<li>
<p>Setup a config.yml - change the /path/to/my/app path to reflect reality.</p>
<pre><code>---
environment: production
chdir: /path/to/my/app
address: 127.0.0.1
user: root
group: root
port: 4567
pid: /path/to/my/app/thin.pid
rackup: /path/to/my/app/config.ru
log: /path/to/my/app/thin.log
max_conns: 1024
timeout: 30
max_persistent_conns: 512
daemonize: true</code></pre>
</li>
<li>
<p>Setup lighttpd.conf - change mydomain to reflect reality. Also make sure the first port here matches up with the port setting in config.yml.</p>
<pre><code>$HTTP["host"] =~ "(www\.)?mydomain\.com" {
proxy.balance = "fair"
proxy.server = ("/" =>
(
( "host" => "127.0.0.1", "port" => 4567 ),
( "host" => "127.0.0.1", "port" => 4568 )
)
)
}</code></pre>
</li>
<li>
<p>Start thin and your application. I have a rake script so I can just call “rake start” rather than typing this in.</p>
<pre><code>thin -s 2 -C config.yml -R config.ru start</code></pre>
</li>
</ol>
<p>You’re done! Go to mydomain.com/ and see the result! Everything should be setup now, check it out at the domain you setup in your lighttpd.conf file.</p>
<p><em>Variation</em> - nginx via proxy - The same approach to proxying can be applied to the nginx web server</p>
<pre><code>upstream www_mydomain_com {
server 127.0.0.1:5000;
server 127.0.0.1:5001;
}
server {
listen www.mydomain.com:80
server_name www.mydomain.com live;
access_log /path/to/logfile.log
location / {
proxy_pass http://www_mydomain_com;
}
}</code></pre>
<p><em>Variation</em> - More Thin instances - To add more thin instances, change the <code>-s 2</code> parameter on the thin start command to be how ever many servers you want. Then be sure lighttpd proxies to all of them by adding more lines to the proxy statements. Then restart lighttpd and everything should come up as expected.</p>
<h2 id='deployment_passenger'>Passenger (mod rails)</h2>
<p>Hate deployment via FastCGI? You’re not alone. But guess what, Passenger supports Rack; and this book tells you how to get it all going.</p>
<p>You can find additional documentation at the Passenger Github repository.</p>
<ol>
<li>
<p>Setting up the account in the Dreamhost interface</p>
<pre><code>Domains -> Manage Domains -> Edit (web hosting column)
Enable 'Ruby on Rails Passenger (mod_rails)'
Add the public directory to the web directory box. So if you were using 'rails.com', it would change to 'rails.com/public'
Save your changes</code></pre>
</li>
<li>
<p>Creating the directory structure</p>
<pre><code>domain.com/
domain.com/tmp
domain.com/public
# a vendored version of sinatra - not necessary if you use the gem
domain.com/sinatra</code></pre>
</li>
<li>
<p>Creating the “Rackup file” (rack configuration file) <code>config.ru</code> – the <code>require 'app'</code> line should require the actual Sinatra app you have written.</p>
<pre><code>## Passenger should set RACK_ENV for Sinatra
require 'app'
run Sinatra::Application</code></pre>
</li>
<li>
<p>A very simple Sinatra application</p>
<pre><code># this is test.rb referred to above
get '/' do
"Worked on dreamhost"
end
get '/foo/:bar' do
"You asked for foo/#{params[:bar]}"
end</code></pre>
</li>
</ol>
<p>And that’s all there is to it! Once it’s all setup, point your browser at your domain, and you should see a ‘Worked on Dreamhost’ page. To restart the application after making changes, you need to run <code>touch tmp/restart.txt</code>.</p>
<p>Please note that currently passenger 2.0.3 has a bug where it can cause Sinatra to not find the view directory. In that case, add <code>:views => '/path/to/views/'</code> to the Sinatra options in your Rackup file.</p>
<h2 id='deployment_fastcgi'>FastCGI (Sinatra <= 0.3)</h2>
<p>The standard method for deployment is to use Thin or Mongrel, and have a reverse proxy (lighttpd, nginx, or even Apache) point to your bundle of servers.</p>
<p>But that isn’t always possible. Cheaper shared hosting (like Dreamhost) won’t let you run Thin or Mongrel, or setup reverse proxies (at least on the default shared plan).</p>
<p>Luckily, Rack supports various connectors, including CGI and FastCGI. Unluckily for us, FastCGI doesn’t quite work with the current Sinatra release.</p>
<p>To get a simple ‘hello world’ Sinatra application up and running on Dreamhost involves pulling down the current Sinatra code, and hacking at it a bit. Don’t worry though, it only requires commenting out a few lines, and tweaking another.</p>
<p>Steps to deploy via FastCGI:</p>
<ul>
<li>.htaccess</li>
<li>dispatch.fcgi</li>
<li>Tweaked sinatra.rb</li>
</ul>
<ol>
<li>
<p>.htaccess RewriteEngine on</p>
<pre><code>AddHandler fastcgi-script .fcgi
Options +FollowSymLinks +ExecCGI
RewriteRule ^(.*)$ dispatch.fcgi [QSA,L]</code></pre>
</li>
<li>
<p>dispatch.fcgi</p>
<pre><code>#!/usr/bin/ruby
require 'rubygems'
require 'sinatra/lib/sinatra'
fastcgi_log = File.open("fastcgi.log", "a")
STDOUT.reopen fastcgi_log
STDERR.reopen fastcgi_log
STDOUT.sync = true
set :logging, false
set :server, "FastCGI"
module Rack
class Request
def path_info
@env["REDIRECT_URL"].to_s
end
def path_info=(s)
@env["REDIRECT_URL"] = s.to_s
end
end
end
load 'app.rb'</code></pre>
</li>
<li>
<p>sinatra.rb - Replace this function with the new version here (commenting out the <code>puts</code> lines)</p>
<pre><code>def run
begin
#puts "== Sinatra has taken the stage on port #{port} for #{env} with backup by #{server.name}"
require 'pp'
server.run(application) do |server|
trap(:INT) do
server.stop
#puts "\n== Sinatra has ended his set (crowd applauds)"
end
end
rescue Errno::EADDRINUSE => e
#puts "== Someone is already performing on port #{port}!"
end
end</code></pre>
</li>
</ol>
<hr />
<h1 id='contributing'>Contributing</h1>
<h2 id='how_can_i_clone_the_sinatra_repository'>How can I clone the Sinatra repository?</h2>
<p>First of all, you’ll need the <a href='http://git.or.cz'>Git</a> version control system. <a href='http://git.or.cz'>Git</a> is available for all major platforms:</p>
<ul>
<li><a href='http://code.google.com/p/msysgit/'>Windows</a></li>
<li><a href='http://code.google.com/p/git-osx-installer/'>Mac OS X</a></li>
<li>Linux and BSD users can usually acquire <a href='http://git.or.cz'>Git</a> through their Package Management System, e.g. <code>apt-get install git-core</code> on Debian systems.</li>
</ul>