sinatra 1.3.6 → 1.4.0.a

Sign up to get free protection for your applications and to get access to all the features.

Potentially problematic release.


This version of sinatra might be problematic. Click here for more details.

Files changed (71) hide show
  1. data/CHANGES +96 -22
  2. data/Gemfile +11 -3
  3. data/README.de.md +2590 -0
  4. data/README.es.rdoc +66 -38
  5. data/README.fr.md +2630 -0
  6. data/README.hu.rdoc +3 -2
  7. data/README.jp.rdoc +16 -3
  8. data/README.ko.rdoc +11 -5
  9. data/README.md +2699 -0
  10. data/README.pt-br.rdoc +152 -21
  11. data/README.pt-pt.rdoc +3 -2
  12. data/README.ru.md +2724 -0
  13. data/README.zh.rdoc +3 -3
  14. data/Rakefile +3 -4
  15. data/examples/chat.rb +3 -3
  16. data/lib/sinatra/base.rb +433 -247
  17. data/lib/sinatra/main.rb +4 -2
  18. data/lib/sinatra/showexceptions.rb +6 -1
  19. data/lib/sinatra/version.rb +1 -1
  20. data/test/base_test.rb +21 -9
  21. data/test/builder_test.rb +15 -19
  22. data/test/coffee_test.rb +4 -6
  23. data/test/compile_test.rb +154 -0
  24. data/test/contest.rb +4 -6
  25. data/test/creole_test.rb +5 -5
  26. data/test/delegator_test.rb +1 -3
  27. data/test/erb_test.rb +32 -20
  28. data/test/extensions_test.rb +1 -3
  29. data/test/filter_test.rb +65 -56
  30. data/test/haml_test.rb +34 -26
  31. data/test/helpers_test.rb +331 -221
  32. data/test/integration_helper.rb +8 -0
  33. data/test/integration_test.rb +3 -1
  34. data/test/less_test.rb +10 -8
  35. data/test/liquid_test.rb +22 -4
  36. data/test/mapped_error_test.rb +122 -96
  37. data/test/markaby_test.rb +5 -5
  38. data/test/markdown_test.rb +5 -5
  39. data/test/middleware_test.rb +3 -3
  40. data/test/nokogiri_test.rb +4 -6
  41. data/test/rabl_test.rb +89 -0
  42. data/test/radius_test.rb +4 -4
  43. data/test/rdoc_test.rb +7 -7
  44. data/test/readme_test.rb +14 -30
  45. data/test/request_test.rb +15 -0
  46. data/test/response_test.rb +3 -4
  47. data/test/result_test.rb +11 -33
  48. data/test/route_added_hook_test.rb +10 -10
  49. data/test/routing_test.rb +123 -1
  50. data/test/sass_test.rb +26 -26
  51. data/test/scss_test.rb +16 -16
  52. data/test/server_test.rb +2 -2
  53. data/test/settings_test.rb +48 -4
  54. data/test/sinatra_test.rb +2 -7
  55. data/test/slim_test.rb +37 -23
  56. data/test/static_test.rb +56 -15
  57. data/test/streaming_test.rb +11 -2
  58. data/test/templates_test.rb +117 -45
  59. data/test/textile_test.rb +9 -9
  60. data/test/views/hello.rabl +2 -0
  61. data/test/views/hello.wlang +1 -0
  62. data/test/views/hello.yajl +1 -0
  63. data/test/views/layout2.rabl +3 -0
  64. data/test/views/layout2.wlang +2 -0
  65. data/test/wlang_test.rb +87 -0
  66. data/test/yajl_test.rb +86 -0
  67. metadata +27 -17
  68. data/README.de.rdoc +0 -2097
  69. data/README.fr.rdoc +0 -2036
  70. data/README.rdoc +0 -2017
  71. data/README.ru.rdoc +0 -1785
data/CHANGES CHANGED
@@ -1,12 +1,101 @@
1
- = 1.3.6 (backport release) / 2013-03-15
1
+ = 1.4.0 / Not Yet Released
2
2
 
3
- Backported from 1.4.0:
3
+ * Add support for Yajl templates. (Jamie Hodge)
4
4
 
5
- * Take views option into account for template caching. (Konstantin Haase)
5
+ * Add support for Rabl templates. (Jesse Cooke)
6
6
 
7
- * Improve documentation (Konstantin Haase)
7
+ * Add support for Wlang templates. (Bernard Lambeau)
8
8
 
9
- * No longer override `define_singleton_method`. (Konstantin Haase)
9
+ * You can now pass a block to ERb, Haml, Slim, Liquid and Wlang templates,
10
+ which will be used when calling `yield` in the template. (Alexey Muranov)
11
+
12
+ * When running in classic mode, no longer include Sinatra::Delegator in Object,
13
+ instead extend the main object only. (Konstantin Haase)
14
+
15
+ * Improved route parsing: "/:name.?:format?" with "/foo.png" now matches to
16
+ {name: "foo", format: "png"} instead of {name: "foo.png"}. (Florian Hanke)
17
+
18
+ * Add :status option support to send_file. (Konstantin Haase)
19
+
20
+ * The `provides` condition now respects an earlier set content type.
21
+ (Konstantin Haase)
22
+
23
+ * Exception#code is only used when :use_code is enabled. Moreover, it will
24
+ be ignored if the value is not between 400 and 599. You should use
25
+ Exception#http_status instead. (Konstantin Haase)
26
+
27
+ * Status, headers and body will be set correctly in an after filter when using
28
+ halt in a before filter or route. (Konstantin Haase)
29
+
30
+ * Sinatra::Base.new now returns a Sinatra::Wrapper instance, exposing
31
+ #settings and #helpers, yet going through the middleware stack on #call.
32
+ It also implements a nice #inspect, so it plays nice with Rails' `rake
33
+ routes`. (Konstantin Haase)
34
+
35
+ * In addition to WebRick, Thin and Mongrel, Sinatra will now automatically pick
36
+ up Puma, Trinidad, ControlTower or Net::HTTP::Server when installed. The
37
+ logic for picking the server has been improved and now depends on the Ruby
38
+ implementation used. (Mark Rada, Konstantin Haase)
39
+
40
+ * "Sinatra doesn't know this ditty" pages now show the app class when running
41
+ a modular application. This helps detecting where the response came from when
42
+ combining multiple modular apps. (Konstantin Haase)
43
+
44
+ * When port is not set explicitly, use $PORT env variable if set and only
45
+ default to 4567 if not. Plays nice with foreman. (Konstantin Haase)
46
+
47
+ * Allow setting layout on a per engine basis. (Zachary Scott, Konstantin Haase)
48
+
49
+ * You can now use `register` directly in a classic app. (Konstantin Haase)
50
+
51
+ * `redirect` now accepts URI or Addressable::URI instances. (Nicolas
52
+ Sanguinetti)
53
+
54
+ * Have Content-Disposition header also include file name for `inline`, not
55
+ just for `attachment`. (Konstantin Haase)
56
+
57
+ * Better compatibility to Rack 1.5. (James Tucker, Konstantin Haase)
58
+
59
+ * Make route parsing regex more robust. (Zoltan Dezso, Konstantin Haase)
60
+
61
+ * Improve Accept header parsing, expose parameters. (Pieter van de Bruggen)
62
+
63
+ * Add `layout_options` render option. Allows you, amongst other things, to
64
+ render a layout from a different folder. (Konstantin Haase)
65
+
66
+ * Explicitly setting `layout` to `nil` is treated like setting it to `false`.
67
+ (richo)
68
+
69
+ * Properly escape attributes in Content-Type header. (Pieter van de Bruggen)
70
+
71
+ * Default to only serving localhost in development mode. (Postmodern)
72
+
73
+ * Setting status code to 404 in error handler no longer triggers not_found
74
+ handler. (Konstantin Haase)
75
+
76
+ * The `protection` option now takes a `session` key for force
77
+ disabling/enabling session based protections. (Konstantin Haase)
78
+
79
+ * Add `x_cascade` option to disable `X-Cascade` header on missing route.
80
+ (Konstantin Haase)
81
+
82
+ * Improve documentation. (Kashyap, Stanislav Chistenko, Zachary Scott,
83
+ Anthony Accomazzo, Peter Suschlik, Rachel Mehl, ymmtmsys, Anurag Priyam,
84
+ burningTyger, Tony Miller, akicho8, Vasily Polovnyov, Markus Prinz,
85
+ Alexey Muranov, Konstantin Haase)
86
+
87
+ * Convert documentation to Markdown. (Kashyap, Robin Dupret, burningTyger,
88
+ Vasily Polovnyov)
89
+
90
+ * Don't set not_found content type to HTML in development mode with custom
91
+ not_found handler. (Konstantin Haase)
92
+
93
+ * Fix mixed indentation for private methods. (Robin Dupret)
94
+
95
+ * Recalculate Content-Length even if hard coded if body is reset. Relevant
96
+ mostly for error handlers. (Nathan Esquenazi, Konstantin Haase)
97
+
98
+ * Take views option into account for template caching. (Konstantin Haase)
10
99
 
11
100
  = 1.3.5 / 2013-02-25
12
101
 
@@ -14,6 +103,8 @@ Backported from 1.4.0:
14
103
 
15
104
  * Improve documentation (Konstantin Haase)
16
105
 
106
+ * No longer override `define_singleton_method`. (Konstantin Haase)
107
+
17
108
  = 1.3.4 / 2013-01-26
18
109
 
19
110
  * Improve documentation. (Kashyap, Stanislav Chistenko, Konstantin Haase,
@@ -58,9 +149,6 @@ Backported from 1.4.0:
58
149
  * When protecting against CSRF attacks, drop the session instead of refusing
59
150
  the request. (Konstantin Haase)
60
151
 
61
- * Status, headers and body will be set correctly in an after filter when using
62
- halt in a before filter or route. (Konstantin Haase)
63
-
64
152
  = 1.3.2 / 2011-12-30
65
153
 
66
154
  * Don't automatically add `Rack::CommonLogger` if `Rack::Server` is adding it,
@@ -223,20 +311,6 @@ Backported from 1.4.0:
223
311
  * Fix handling of broken query params when displaying exceptions. (Luke
224
312
  Jahnke)
225
313
 
226
- = 1.2.9 (backports release) / 2013-03-15
227
-
228
- IMPORTANT: THIS IS THE LAST 1.2.x RELEASE, PLEASE UPGRADE.
229
-
230
- * Display EOL warning when loading Sinatra. (Konstantin Haase)
231
-
232
- * Improve documentation. (Anurag Priyam, Konstantin Haase)
233
-
234
- * Do not modify the load path. (Konstantin Haase)
235
-
236
- * Display deprecation warning if RUBY_IGNORE_CALLERS is used. (Konstantin Haase)
237
-
238
- * Add backports library so we can still run on Ruby 1.8.6. (Konstantin Haase)
239
-
240
314
  = 1.2.8 (backports release) / 2011-12-30
241
315
 
242
316
  Backported from 1.3.2:
data/Gemfile CHANGED
@@ -7,7 +7,7 @@
7
7
  # If you have issues with a gem: `bundle install --without-coffee-script`.
8
8
 
9
9
  RUBY_ENGINE = 'ruby' unless defined? RUBY_ENGINE
10
- source 'https://rubygems.org/' unless ENV['QUICK']
10
+ source :rubygems unless ENV['QUICK']
11
11
  gemspec
12
12
 
13
13
  gem 'rake'
@@ -32,20 +32,23 @@ gem 'haml', '>= 3.0'
32
32
  gem 'sass' if RUBY_VERSION < "2.0"
33
33
  gem 'builder'
34
34
  gem 'erubis'
35
- gem 'liquid' unless RUBY_ENGINE == 'rbx' and RUBY_VERSION > '1.9'
36
35
  gem 'slim', '~> 1.0'
37
36
  gem 'temple', '!= 0.3.3'
38
37
  gem 'coffee-script', '>= 2.0'
39
- gem 'rdoc', RUBY_VERSION < '1.9' ? '~> 3.12' : '>= 4.0'
38
+ gem 'rdoc', '~> 3.12'
40
39
  gem 'kramdown'
41
40
  gem 'maruku'
42
41
  gem 'creole'
43
42
  gem 'markaby'
44
43
  gem 'radius'
44
+ gem 'rabl' unless RUBY_ENGINE =~ /jruby|maglev/
45
+ gem 'wlang', '>= 2.0.1' unless RUBY_ENGINE =~ /jruby|rbx/
46
+ gem 'liquid' unless RUBY_ENGINE == 'rbx' and RUBY_VERSION > '1.9'
45
47
 
46
48
  if RUBY_ENGINE == 'jruby'
47
49
  gem 'nokogiri', '!= 1.5.0'
48
50
  gem 'jruby-openssl'
51
+ gem 'trinidad'
49
52
  else
50
53
  gem 'yajl-ruby'
51
54
  gem 'nokogiri'
@@ -54,6 +57,8 @@ end
54
57
 
55
58
  if RUBY_ENGINE == "ruby" and RUBY_VERSION > '1.9'
56
59
  gem 'less', '~> 2.0'
60
+ else
61
+ gem 'less', '~> 1.0'
57
62
  end
58
63
 
59
64
  if RUBY_ENGINE != 'jruby' or not ENV['TRAVIS']
@@ -64,11 +69,14 @@ if RUBY_ENGINE != 'jruby' or not ENV['TRAVIS']
64
69
  gem 'mongrel'
65
70
  end
66
71
  gem 'RedCloth' unless RUBY_ENGINE == "macruby"
72
+ gem 'puma'
67
73
 
68
74
  ## bluecloth is broken
69
75
  #gem 'bluecloth'
70
76
  end
71
77
 
78
+ gem 'net-http-server'
79
+
72
80
  platforms :ruby_18, :jruby do
73
81
  gem 'json' unless RUBY_VERSION > '1.9' # is there a jruby but 1.8 only selector?
74
82
  end
@@ -0,0 +1,2590 @@
1
+ # Sinatra
2
+
3
+ *Wichtig: Dieses Dokument ist eine Übersetzung aus dem Englischen und unter
4
+ Umständen nicht auf dem aktuellen Stand.*
5
+
6
+ Sinatra ist eine
7
+ [DSL](http://de.wikipedia.org/wiki/Domänenspezifische_Sprache), die das
8
+ schnelle Erstellen von Webanwendungen in Ruby mit minimalem Aufwand
9
+ ermöglicht:
10
+
11
+ ```ruby
12
+ # myapp.rb
13
+ require 'sinatra'
14
+ get '/' do
15
+ 'Hallo Welt!'
16
+ end
17
+ ```
18
+
19
+ Einfach via `rubygems` installieren und starten:
20
+
21
+ ```ruby
22
+ gem install sinatra
23
+ ruby myapp.rb
24
+ ```
25
+
26
+ Die Seite kann nun unter http://localhost:4567 betrachtet werden.
27
+
28
+ Es wird empfohlen, den Thin-Server via `gem install thin` zu installieren, den
29
+ Sinatra dann, soweit vorhanden, automatisch verwendet.
30
+
31
+ ## Routen
32
+
33
+ In Sinatra wird eine Route durch eine HTTP-Methode und ein URL-Muster definiert.
34
+ Jeder dieser Routen wird ein Ruby-Block zugeordnet:
35
+
36
+ ```ruby
37
+ get '/' do
38
+ .. zeige etwas ..
39
+ end
40
+
41
+ post '/' do
42
+ .. erstelle etwas ..
43
+ end
44
+
45
+ put '/' do
46
+ .. update etwas ..
47
+ end
48
+
49
+ delete '/' do
50
+ .. entferne etwas ..
51
+ end
52
+
53
+ options '/' do
54
+ .. zeige, was wir können ..
55
+ end
56
+ ```
57
+
58
+ Die Routen werden in der Reihenfolge durchlaufen, in der sie definiert wurden.
59
+ Das erste Routen-Muster, das mit dem Request übereinstimmt, wird ausgeführt.
60
+
61
+ Die Muster der Routen können benannte Parameter beinhalten, die über den
62
+ `params`-Hash zugänglich gemacht werden:
63
+
64
+ ```ruby
65
+ get '/hallo/:name' do
66
+ # passt auf "GET /hallo/foo" und "GET /hallo/bar"
67
+ # params[:name] ist 'foo' oder 'bar'
68
+ "Hallo #{params[:name]}!"
69
+ end
70
+ ```
71
+
72
+ Man kann auf diese auch mit Block-Parametern zugreifen:
73
+
74
+ ```ruby
75
+ get '/hallo/:name' do |n|
76
+ "Hallo #{n}!"
77
+ end
78
+ ```
79
+
80
+ Routen-Muster können auch mit Splat- oder Wildcard-Parametern über das
81
+ `params[:splat]`-Array angesprochen werden:
82
+
83
+ ```ruby
84
+ get '/sag/*/zu/*' do
85
+ # passt auf /sag/hallo/zu/welt
86
+ params[:splat] # => ["hallo", "welt"]
87
+ end
88
+
89
+ get '/download/*.*' do
90
+ # passt auf /download/pfad/zu/datei.xml
91
+ params[:splat] # => ["pfad/zu/datei", "xml"]
92
+ end
93
+ ```
94
+
95
+ Oder mit Block-Parametern:
96
+
97
+ ```ruby
98
+ get '/download/*.*' do |pfad, endung|
99
+ [pfad, endung] # => ["Pfad/zu/Datei", "xml"]
100
+ end
101
+ ```
102
+
103
+ Routen mit regulären Ausdrücken sind auch möglich:
104
+
105
+ ```ruby
106
+ get %r{/hallo/([\w]+)} do
107
+ "Hallo, #{params[:captures].first}!"
108
+ end
109
+
110
+ Und auch hier können Block-Parameter genutzt werden:
111
+
112
+ ```ruby
113
+ get %r{/hallo/([\w]+)} do |c|
114
+ "Hallo, #{c}!"
115
+ end
116
+ ```
117
+
118
+ Routen-Muster können auch mit optionalen Parametern ausgestattet werden:
119
+
120
+ ```ruby
121
+ get '/posts.?:format?' do
122
+ # passt auf "GET /posts" sowie jegliche Erweiterung
123
+ # wie "GET /posts.json", "GET /posts.xml" etc.
124
+ end
125
+ ```
126
+
127
+ Anmerkung: Solange man den sog. Path Traversal Attack-Schutz nicht deaktiviert
128
+ (siehe weiter unten), kann es sein, dass der Request-Pfad noch vor dem
129
+ Abgleich mit den Routen modifiziert wird.
130
+
131
+ ### Bedingungen
132
+
133
+ An Routen können eine Vielzahl von Bedingungen angehängt werden, die erfüllt
134
+ sein müssen, damit der Block ausgeführt wird. Möglich wäre etwa eine
135
+ Einschränkung des User-Agents:
136
+
137
+ ```ruby
138
+ get '/foo', :agent => /Songbird (\d\.\d)[\d\/]*?/ do
139
+ "Du verwendest Songbird Version #{params[:agent][0]}"
140
+ end
141
+
142
+ get '/foo' do
143
+ # passt auf andere Browser
144
+ end
145
+ ```
146
+
147
+ Andere mitgelieferte Bedingungen sind `host_name` und `provides`:
148
+
149
+ ```ruby
150
+ get '/', :host_name => /^admin\./ do
151
+ "Adminbereich, Zugriff verweigert!"
152
+ end
153
+
154
+ get '/', :provides => 'html' do
155
+ haml :index
156
+ end
157
+
158
+ get '/', :provides => ['rss', 'atom', 'xml'] do
159
+ builder :feed
160
+ end
161
+ ```
162
+
163
+ Es können auch andere Bedingungen relativ einfach hinzugefügt werden:
164
+
165
+ ```ruby
166
+ set(:probability) { |value| condition { rand <= value } }
167
+
168
+ get '/auto_gewinnen', :probability => 0.1 do
169
+ "Du hast gewonnen!"
170
+ end
171
+
172
+ get '/auto_gewinnen' do
173
+ "Tut mir leid, verloren."
174
+ end
175
+ ```
176
+
177
+ Bei Bedingungen, die mehrere Werte annehmen können, sollte ein Splat verwendet
178
+ werden:
179
+
180
+ ```ruby
181
+ set(:auth) do |*roles| # <- hier kommt der Splat ins Spiel
182
+ condition do
183
+ unless logged_in? && roles.any? {|role| current_user.in_role? role }
184
+ redirect "/login/", 303
185
+ end
186
+ end
187
+ end
188
+
189
+ get "/mein/account/", :auth => [:user, :admin] do
190
+ "Mein Account"
191
+ end
192
+
193
+ get "/nur/admin/", :auth => :admin do
194
+ "Nur Admins dürfen hier rein!"
195
+ end
196
+ ```
197
+
198
+ ### Rückgabewerte
199
+
200
+ Durch den Rückgabewert eines Routen-Blocks wird mindestens der Response-Body
201
+ festgelegt, der an den HTTP-Client, bzw. die nächste Rack-Middleware,
202
+ weitergegeben wird. Im Normalfall handelt es sich hierbei, wie in den
203
+ vorangehenden Beispielen zu sehen war, um einen String. Es werden allerdings
204
+ auch andere Werte akzeptiert.
205
+
206
+ Es kann jedes gültige Objekt zurückgegeben werden, bei dem es sich entweder um
207
+ einen Rack-Rückgabewert, einen Rack-Body oder einen HTTP-Status-Code handelt:
208
+
209
+ * Ein Array mit drei Elementen: `[Status (Fixnum), Headers (Hash),
210
+ Response-Body (antwortet auf #each)]`.
211
+ * Ein Array mit zwei Elementen: `[Status (Fixnum), Response-Body (antwortet
212
+ auf #each)]`.
213
+ * Ein Objekt, das auf `#each` antwortet und den an diese Methode übergebenen
214
+ Block nur mit Strings als Übergabewerte aufruft.
215
+ * Ein Fixnum, das den Status-Code festlegt.
216
+
217
+
218
+ Damit lässt sich relativ einfach Streaming implementieren:
219
+
220
+ ```ruby
221
+ class Stream
222
+ def each
223
+ 100.times { |i| yield "#{i}\n" }
224
+ end
225
+ end
226
+
227
+ get('/') { Stream.new }
228
+ ```
229
+
230
+ Ebenso kann die `stream`-Helfer-Methode (s.u.) verwendet werden, die Streaming
231
+ direkt in die Route integriert.
232
+
233
+ ### Eigene Routen-Muster
234
+
235
+ Wie oben schon beschrieben, ist Sinatra von Haus aus mit Unterstützung für
236
+ String-Muster und Reguläre Ausdrücke zum Abgleichen von Routen ausgestattet.
237
+ Das muss aber noch nicht alles sein, es können ohne großen Aufwand eigene
238
+ Routen-Muster erstellt werden:
239
+
240
+ ```ruby
241
+ class AllButPattern
242
+ Match = Struct.new(:captures)
243
+
244
+ def initialize(except)
245
+ @except = except
246
+ @captures = Match.new([])
247
+ end
248
+
249
+ def match(str)
250
+ @captures unless @except === str
251
+ end
252
+ end
253
+
254
+ def all_but(pattern)
255
+ AllButPattern.new(pattern)
256
+ end
257
+
258
+ get all_but("/index") do
259
+ # ...
260
+ end
261
+ ```
262
+
263
+ Beachte, dass das obige Beispiel etwas übertrieben wirkt. Es geht auch einfacher:
264
+
265
+ ```ruby
266
+ get // do
267
+ pass if request.path_info == "/index"
268
+ # ...
269
+ end
270
+ ```
271
+
272
+ Oder unter Verwendung eines negativen look ahead:
273
+
274
+ ```ruby
275
+ get %r{^(?!/index$)} do
276
+ # ...
277
+ end
278
+ ```
279
+ ## Statische Dateien
280
+
281
+ Statische Dateien werden aus dem `./public`-Ordner ausgeliefert. Es ist möglich,
282
+ einen anderen Ort zu definieren, indem man die `:public_folder`-Option setzt:
283
+
284
+ ```ruby
285
+ set :public_folder, File.dirname(__FILE__) + '/static'
286
+ ```
287
+
288
+ Zu beachten ist, dass der Ordnername public nicht Teil der URL ist. Die Datei
289
+ `./public/css/style.css` ist unter `http://example.com/css/style.css` zu finden.
290
+
291
+ Um den `Cache-Control`-Header mit Informationen zu versorgen, verwendet man
292
+ die `:static_cache_control`-Einstellung (s.u.).
293
+
294
+ ## Views/Templates
295
+
296
+ Alle Templatesprachen verwenden ihre eigene Renderingmethode, die jeweils
297
+ einen String zurückgibt:
298
+
299
+ ```ruby
300
+ get '/' do
301
+ erb :index
302
+ end
303
+ ```
304
+
305
+ Dieses Beispiel rendert `views/index.erb`.
306
+
307
+ Anstelle eines Templatenamens kann man auch direkt die Templatesprache verwenden:
308
+
309
+ ```ruby
310
+ get '/' do
311
+ code = "<%= Time.now %>"
312
+ erb code
313
+ end
314
+ ```
315
+
316
+ Templates nehmen ein zweite Argument an, den Options-Hash:
317
+
318
+ ```ruby
319
+ get '/' do
320
+ erb :index, :layout => :post
321
+ end
322
+ ```
323
+
324
+ Dieses Beispiel rendert `views/index.erb` eingebettet in `views/post.erb`
325
+ (Voreinstellung ist `views/layout.erb`, sofern es vorhanden ist.)
326
+
327
+ Optionen, die Sinatra nicht versteht, werden an das Template weitergereicht:
328
+
329
+ ```ruby
330
+ get '/' do
331
+ haml :index, :format => :html5
332
+ end
333
+ ```
334
+
335
+ Für alle Templates können auch generelle Einstellungen festgelegt werden:
336
+
337
+ ```ruby
338
+ set :haml, :format => :html5
339
+
340
+ get '/' do
341
+ haml :index
342
+ end
343
+ ```
344
+
345
+ Optionen, die an die Rendermethode weitergegeben werden, überschreiben die
346
+ Einstellungen, die mit `set` festgelegt wurden.
347
+
348
+ Einstellungen:
349
+
350
+ <dl>
351
+ <dt>locals</dt>
352
+ <dd>Liste von lokalen Variablen, die and das Dokument weitergegeben werden.
353
+ Praktisch für Partials. Beispiel:
354
+ <tt>erb "<%= foo %>", :locals => {:foo => "bar"}</tt></dd>
355
+
356
+ <dt>default_encoding</dt>
357
+ <dd>Gibt die Stringkodierung an, die verwendet werden soll. Voreingestellt
358
+ auf <tt>settings.default_encoding</tt>.</dd>
359
+
360
+ <dt>views</dt>
361
+ <dd>Ordner, aus dem die Templates heraus geladen werden. Voreingestellt auf
362
+ <tt>settings.views</tt>.</dd>
363
+
364
+ <dt>layout</dt>
365
+ <dd>Legt fest, ob ein Layouttemplate verwendet werden soll oder nicht
366
+ (<tt>true</tt> oder<tt>false</tt>). Ist es ein Symbol, dass legt es fest,
367
+ welches Template als Layout verwendet wird. Beispiel:
368
+ <tt><tt>erb :index, :layout => !request.xhr?</tt></tt></dd>
369
+
370
+ <dt>content_type</dt>
371
+ <dd>Content-Type den das Template ausgibt. Voreinstellung hängt von der
372
+ Templatesprache ab.</dd>
373
+
374
+ <dt>scope</dt>
375
+ <dd>Scope, in dem das Template gerendert wird. Liegt standardmäßig innerhalb
376
+ der App-Instanz. Wird Scope geändert, sind Instanzvariablen und
377
+ Helfermethoden nicht verfügbar.</dd>
378
+
379
+ <dt>layout_engine</dt>
380
+ <dd>Legt fest, welcher Renderer für das Layout verantwortlich ist. Hilfreich
381
+ für Sprachen, die sonst keine Templates unterstützen. Voreingestellt auf
382
+ den Renderer, der für das Template verwendet wird. Beispiel:
383
+ <tt>set :rdoc, :layout_engine => :erb</tt></dd>
384
+ </dl>
385
+
386
+
387
+ Sinatra geht davon aus, dass die Templates sich im `./views` Verzeichnis
388
+ befinden. Es kann jedoch ein anderer Ordner festgelegt werden:
389
+
390
+ ```ruby
391
+ set :views, settings.root + '/templates'
392
+ ```
393
+
394
+ Es ist zu beachten, dass immer mit Symbolen auf Templates verwiesen werden muss,
395
+ auch dann, wenn sie sich in einem Unterordner befinden:
396
+
397
+ ```ruby
398
+ haml :'unterverzeichnis/template'
399
+ ```
400
+
401
+ Rendering-Methoden rendern jeden String direkt.
402
+
403
+ ### Verfügbare Templatesprachen
404
+
405
+ Einige Sprachen haben mehrere Implementierungen. Um festzulegen, welche
406
+ verwendet wird (und dann auch Thread-sicher ist), verwendet man am besten zu
407
+ Beginn ein 'require':
408
+
409
+ ```ruby
410
+ require 'rdiscount' # oder require 'bluecloth'
411
+ get('/') { markdown :index }
412
+ ```
413
+
414
+ ### Haml Templates
415
+
416
+ <table>
417
+ <tr>
418
+ <td>Abhängigkeit</td>
419
+ <td><a href="http://haml.info/">haml</a></td>
420
+ </tr>
421
+ <tr>
422
+ <td>Dateierweiterung</td>
423
+ <td><tt>.haml</tt></td>
424
+ </tr>
425
+ <tr>
426
+ <td>Beispiel</td>
427
+ <td><tt>haml :index, :format => :html5</tt></td>
428
+ </tr>
429
+ </table>
430
+
431
+
432
+ ### Erb Templates
433
+
434
+ <table>
435
+ <tr>
436
+ <td>Abhängigkeit</td>
437
+ <td><a href="http://www.kuwata-lab.com/erubis/">erubis</a> oder erb
438
+ (Standardbibliothek von Ruby)</td>
439
+ </tr>
440
+ <tr>
441
+ <td>Dateierweiterungen</td>
442
+ <td><tt>.erb</tt>, <tt>.rhtml</tt> oder <tt>.erubis</tt> (nur Erubis)</td>
443
+ </tr>
444
+ <tr>
445
+ <td>Beispiel</td>
446
+ <td><tt>erb :index</tt></td>
447
+ </tr>
448
+ </table>
449
+
450
+
451
+ ### Builder Templates
452
+
453
+ <table>
454
+ <tr>
455
+ <td>Abhängigkeit</td>
456
+ <td><a href="http://builder.rubyforge.org/">builder</a></td>
457
+ </tr>
458
+ <tr>
459
+ <td>Dateierweiterung</td>
460
+ <td><tt>.builder</tt></td>
461
+ </tr>
462
+ <tr>
463
+ <td>Beispiel</td>
464
+ <td><tt>builder { |xml| xml.em "Hallo" }</tt></td>
465
+ </tr>
466
+ </table>
467
+
468
+ Nimmt ebenso einen Block für Inline-Templates entgegen (siehe Beispiel).
469
+
470
+ ### Nokogiri Templates
471
+
472
+ <table>
473
+ <tr>
474
+ <td>Abhängigkeit</td>
475
+ <td><a href="http://nokogiri.org/">nokogiri</a></td>
476
+ </tr>
477
+ <tr>
478
+ <td>Dateierweiterung</td>
479
+ <td><tt>.nokogiri</tt></td>
480
+ </tr>
481
+ <tr>
482
+ <td>Beispiel</td>
483
+ <td><tt>nokogiri { |xml| xml.em "Hallo" }</tt></td>
484
+ </tr>
485
+ </table>
486
+
487
+ Nimmt ebenso einen Block für Inline-Templates entgegen (siehe Beispiel).
488
+
489
+ ### Sass Templates
490
+
491
+ <table>
492
+ <tr>
493
+ <td>Abhängigkeit</td>
494
+ <td><a href="http://sass-lang.com/">sass</a></td>
495
+ </tr>
496
+ <tr>
497
+ <td>Dateierweiterung</td>
498
+ <td><tt>.sass</tt></td>
499
+ </tr>
500
+ <tr>
501
+ <td>Beispiel</td>
502
+ <td><tt>sass :stylesheet, :style => :expanded</tt></td>
503
+ </tr>
504
+ </table>
505
+
506
+
507
+ ### SCSS Templates
508
+
509
+ <table>
510
+ <tr>
511
+ <td>Abhängigkeit</td>
512
+ <td><a href="http://sass-lang.com/">sass</a></td>
513
+ </tr>
514
+ <tr>
515
+ <td>Dateierweiterung</td>
516
+ <td><tt>.scss</tt></td>
517
+ </tr>
518
+ <tr>
519
+ <td>Beispiel</td>
520
+ <td><tt>scss :stylesheet, :style => :expanded</tt></td>
521
+ </tr>
522
+ </table>
523
+
524
+
525
+ ### Less Templates
526
+
527
+ <table>
528
+ <tr>
529
+ <td>Abhängigkeit</td>
530
+ <td><a href="http://www.lesscss.org/">less</a></td>
531
+ </tr>
532
+ <tr>
533
+ <td>Dateierweiterung</td>
534
+ <td><tt>.less</tt></td>
535
+ </tr>
536
+ <tr>
537
+ <td>Beispiel</td>
538
+ <td><tt>less :stylesheet</tt></td>
539
+ </tr>
540
+ </table>
541
+
542
+
543
+ ### Liquid Templates
544
+
545
+ <table>
546
+ <tr>
547
+ <td>Abhängigkeit</td>
548
+ <td><a href="http://www.liquidmarkup.org/">liquid</a></td>
549
+ </tr>
550
+ <tr>
551
+ <td>Dateierweiterung</td>
552
+ <td><tt>.liquid</tt></td>
553
+ </tr>
554
+ <tr>
555
+ <td>Beispiel</td>
556
+ <td><tt>liquid :index, :locals => { :key => 'Wert' }</tt></td>
557
+ </tr>
558
+ </table>
559
+
560
+ Da man aus dem Liquid-Template heraus keine Ruby-Methoden aufrufen kann
561
+ (ausgenommen `yield`), wird man üblicherweise locals verwenden wollen, mit
562
+ denen man Variablen weitergibt.
563
+
564
+ ### Markdown Templates
565
+
566
+ <table>
567
+ <tr>
568
+ <td>Abhängigkeit</td>
569
+ <td>Eine der folgenden Bibliotheken:
570
+ <a href="https://github.com/rtomayko/rdiscount" title="RDiscount">RDiscount</a>,
571
+ <a href="https://github.com/vmg/redcarpet" title="RedCarpet">RedCarpet</a>,
572
+ <a href="http://deveiate.org/projects/BlueCloth" title="BlueCloth">BlueCloth</a>,
573
+ <a href="http://kramdown.rubyforge.org/" title="kramdown">kramdown</a> oder
574
+ <a href="http://maruku.rubyforge.org/" title="maruku">maruku</a>
575
+ </td>
576
+ </tr>
577
+ <tr>
578
+ <td>Dateierweiterungen</td>
579
+ <td><tt>.markdown</tt>, <tt>.mkd</tt> und <tt>.md</tt></td>
580
+ </tr>
581
+ <tr>
582
+ <td>Beispiel</td>
583
+ <td><tt>markdown :index, :layout_engine => :erb</tt></td>
584
+ </tr>
585
+ </table>
586
+
587
+ Da man aus den Markdown-Templates heraus keine Ruby-Methoden aufrufen und auch
588
+ keine locals verwenden kann, wird man Markdown üblicherweise in Kombination
589
+ mit anderen Renderern verwenden wollen:
590
+
591
+ ```ruby
592
+ erb :overview, :locals => { :text => markdown(:einfuehrung) }
593
+ ```
594
+
595
+ Beachte, dass man die `markdown`-Methode auch aus anderen Templates heraus
596
+ aufrufen kann:
597
+
598
+ ```ruby
599
+ %h1 Gruß von Haml!
600
+ %p= markdown(:Grüße)
601
+ ```
602
+
603
+ Da man Ruby nicht von Markdown heraus aufrufen kann, können auch Layouts nicht
604
+ in Markdown geschrieben werden. Es ist aber möglich, einen Renderer für die
605
+ Templates zu verwenden und einen anderen für das Layout, indem die
606
+ `:layout_engine`-Option verwendet wird.
607
+
608
+ ### Textile Templates
609
+
610
+ <table>
611
+ <tr>
612
+ <td>Abhängigkeit</td>
613
+ <td><a href="http://redcloth.org/">RedCloth</a></td>
614
+ </tr>
615
+ <tr>
616
+ <td>Dateierweiterung</td>
617
+ <td><tt>.textile</tt></td>
618
+ </tr>
619
+ <tr>
620
+ <td>Beispiel</td>
621
+ <td><tt>textile :index, :layout_engine => :erb</tt></td>
622
+ </tr>
623
+ </table>
624
+
625
+ Da man aus dem Textile-Template heraus keine Ruby-Methoden aufrufen und auch
626
+ keine locals verwenden kann, wird man Textile üblicherweise in Kombination mit
627
+ anderen Renderern verwenden wollen:
628
+
629
+ ```ruby
630
+ erb :overview, :locals => { :text => textile(:einfuehrung) }
631
+ ```
632
+
633
+ Beachte, dass man die `textile`-Methode auch aus anderen Templates heraus
634
+ aufrufen kann:
635
+
636
+ ```ruby
637
+ %h1 Gruß von Haml!
638
+ %p= textile(:Grüße)
639
+ ```
640
+
641
+ Da man Ruby nicht von Textile heraus aufrufen kann, können auch Layouts nicht
642
+ in Textile geschrieben werden. Es ist aber möglich, einen Renderer für die
643
+ Templates zu verwenden und einen anderen für das Layout, indem die
644
+ `:layout_engine`-Option verwendet wird.
645
+
646
+ ### RDoc Templates
647
+
648
+ <table>
649
+ <tr>
650
+ <td>Abhängigkeit</td>
651
+ <td><a href="http://rdoc.rubyforge.org/">rdoc</a></td>
652
+ </tr>
653
+ <tr>
654
+ <td>Dateierweiterung</td>
655
+ <td><tt>.rdoc</tt></td>
656
+ </tr>
657
+ <tr>
658
+ <td>Beispiel</td>
659
+ <td><tt>textile :README, :layout_engine => :erb</tt></td>
660
+ </tr>
661
+ </table>
662
+
663
+ Da man aus dem RDoc-Template heraus keine Ruby-Methoden aufrufen und auch
664
+ keine locals verwenden kann, wird man RDoc üblicherweise in Kombination mit
665
+ anderen Renderern verwenden wollen:
666
+
667
+ ```ruby
668
+ erb :overview, :locals => { :text => rdoc(:einfuehrung) }
669
+ ```
670
+
671
+ Beachte, dass man die `rdoc`-Methode auch aus anderen Templates heraus
672
+ aufrufen kann:
673
+
674
+ ```ruby
675
+ %h1 Gruß von Haml!
676
+ %p= rdoc(:Grüße)
677
+ ```
678
+
679
+ Da man Ruby nicht von RDoc heraus aufrufen kann, können auch Layouts nicht in
680
+ RDoc geschrieben werden. Es ist aber möglich, einen Renderer für die Templates
681
+ zu verwenden und einen anderen für das Layout, indem die
682
+ `:layout_engine`-Option verwendet wird.
683
+
684
+ ### Radius Templates
685
+
686
+ <table>
687
+ <tr>
688
+ <td>Abhängigkeit</td>
689
+ <td><a href="http://radius.rubyforge.org/">radius</a></td>
690
+ </tr>
691
+ <tr>
692
+ <td>Dateierweiterung</td>
693
+ <td><tt>.radius</tt></td>
694
+ </tr>
695
+ <tr>
696
+ <td>Beispiel</td>
697
+ <td><tt>radius :index, :locals => { :key => 'Wert' }</tt></td>
698
+ </tr>
699
+ </table>
700
+
701
+ Da man aus dem Radius-Template heraus keine Ruby-Methoden aufrufen kann, wird
702
+ man üblicherweise locals verwenden wollen, mit denen man Variablen weitergibt.
703
+
704
+ ### Markaby Templates
705
+
706
+ <table>
707
+ <tr>
708
+ <td>Abhängigkeit</td>
709
+ <td><a href="http://markaby.github.com/">markaby</a></td>
710
+ </tr>
711
+ <tr>
712
+ <td>Dateierweiterung</td>
713
+ <td><tt>.mab</tt></td>
714
+ </tr>
715
+ <tr>
716
+ <td>Beispiel</td>
717
+ <td><tt>markaby { h1 "Willkommen!" }</tt></td>
718
+ </tr>
719
+ </table>
720
+
721
+ Nimmt ebenso einen Block für Inline-Templates entgegen (siehe Beispiel).
722
+
723
+ ### RABL Templates
724
+
725
+ <table>
726
+ <tr>
727
+ <td>Abhängigkeit</td>
728
+ <td><a href="https://github.com/nesquena/rabl">rabl</a></td>
729
+ </tr>
730
+ <tr>
731
+ <td>Dateierweiterung</td>
732
+ <td><tt>.rabl</tt></td>
733
+ </tr>
734
+ <tr>
735
+ <td>Beispiel</td>
736
+ <td><tt>rabl :index</tt></td>
737
+ </tr>
738
+ </table>
739
+
740
+ ### Slim Templates
741
+
742
+ <table>
743
+ <tr>
744
+ <td>Abhängigkeit</td>
745
+ <td><a href="http://slim-lang.com/">slim</a></td>
746
+ </tr>
747
+ <tr>
748
+ <td>Dateierweiterung</td>
749
+ <td><tt>.slim</tt></td>
750
+ </tr>
751
+ <tr>
752
+ <td>Beispiel</td>
753
+ <td><tt>slim :index</tt></td>
754
+ </tr>
755
+ </table>
756
+
757
+ ### Creole Templates
758
+
759
+ <table>
760
+ <tr>
761
+ <td>Abhängigkeit</td>
762
+ <td><a href="https://github.com/minad/creole">creole</a></td>
763
+ </tr>
764
+ <tr>
765
+ <td>Dateierweiterung</td>
766
+ <td><tt>.creole</tt></td>
767
+ </tr>
768
+ <tr>
769
+ <td>Beispiel</td>
770
+ <td><tt>creole :wiki, :layout_engine => :erb</tt></td>
771
+ </tr>
772
+ </table>
773
+
774
+ Da man aus dem Creole-Template heraus keine Ruby-Methoden aufrufen und auch
775
+ keine locals verwenden kann, wird man Creole üblicherweise in Kombination mit
776
+ anderen Renderern verwenden wollen:
777
+
778
+ ```ruby
779
+ erb :overview, :locals => { :text => creole(:einfuehrung) }
780
+ ```
781
+
782
+ Beachte, dass man die `creole`-Methode auch aus anderen Templates heraus
783
+ aufrufen kann:
784
+
785
+ ```ruby
786
+ %h1 Gruß von Haml!
787
+ %p= creole(:Grüße)
788
+ ```
789
+
790
+ Da man Ruby nicht von Creole heraus aufrufen kann, können auch Layouts nicht in
791
+ Creole geschrieben werden. Es ist aber möglich, einen Renderer für die Templates
792
+ zu verwenden und einen anderen für das Layout, indem die `:layout_engine`-Option
793
+ verwendet wird.
794
+
795
+ ### CoffeeScript Templates
796
+
797
+ <table>
798
+ <tr>
799
+ <td>Abhängigkeit</td>
800
+ <td><a href="https://github.com/josh/ruby-coffee-script">coffee-script</a> und eine <a href="https://github.com/sstephenson/execjs/blob/master/README.md#readme">Möglichkeit JavaScript auszuführen</a>.</td>
801
+ <tr>
802
+ <td>Dateierweiterung</td>
803
+ <td><tt>.coffee</tt></td>
804
+ </tr>
805
+ <tr>
806
+ <td>Beispiel</td>
807
+ <td><tt>coffee :index</tt></td>
808
+ </tr>
809
+ </table>
810
+
811
+ ### WLang Templates
812
+
813
+ <table>
814
+ <tr>
815
+ <td>Abhängigkeit</td>
816
+ <td><a href="https://github.com/blambeau/wlang/">wlang</a></td>
817
+ </tr>
818
+ <tr>
819
+ <td>Dateierweiterung</td>
820
+ <td><tt>.wlang</tt></td>
821
+ </tr>
822
+ <tr>
823
+ <td>Beispiel</td>
824
+ <td><tt>wlang :index, :locals => { :key => 'value' }</tt></td>
825
+ </tr>
826
+ </table>
827
+
828
+ Ruby-Methoden in wlang aufzurufen entspricht nicht den idiomatischen Vorgaben
829
+ von wlang, es bietet sich deshalb an, `:locals` zu verwenden. Layouts, die
830
+ wlang und `yield` verwenden, werden aber trotzdem unterstützt.
831
+
832
+ ### Eingebettete Templates
833
+
834
+ ```ruby
835
+ get '/' do
836
+ haml '%div.title Hallo Welt'
837
+ end
838
+ ```
839
+
840
+ Rendert den eingebetteten Template-String.
841
+
842
+ ### Auf Variablen in Templates zugreifen
843
+
844
+ Templates werden in demselben Kontext ausgeführt wie Routen. Instanzvariablen
845
+ in Routen sind auch direkt im Template verfügbar:
846
+
847
+ ```ruby
848
+ get '/:id' do
849
+ @foo = Foo.find(params[:id])
850
+ haml '%h1= @foo.name'
851
+ end
852
+ ```
853
+
854
+ Oder durch einen expliziten Hash von lokalen Variablen:
855
+
856
+ ```ruby
857
+ get '/:id' do
858
+ foo = Foo.find(params[:id])
859
+ haml '%h1= bar.name', :locals => { :bar => foo }
860
+ end
861
+ ```
862
+
863
+ Dies wird typischerweise bei Verwendung von Subtemplates (partials) in anderen
864
+ Templates eingesetzt.
865
+
866
+ ### Inline-Templates
867
+
868
+ Templates können auch am Ende der Datei definiert werden:
869
+
870
+ ```ruby
871
+ require 'sinatra'
872
+
873
+ get '/' do
874
+ haml :index
875
+ end
876
+
877
+ __END__
878
+
879
+ @@ layout
880
+ %html
881
+ = yield
882
+
883
+ @@ index
884
+ %div.title Hallo Welt!!!!!
885
+ ```
886
+
887
+ Anmerkung: Inline-Templates, die in der Datei definiert sind, die `require
888
+ 'sinatra'` aufruft, werden automatisch geladen. Um andere Inline-Templates in
889
+ anderen Dateien aufzurufen, muss explizit `enable :inline_templates` verwendet
890
+ werden.
891
+
892
+ ### Benannte Templates
893
+
894
+ Templates können auch mit der Top-Level `template`-Methode definiert werden:
895
+
896
+ ```ruby
897
+ template :layout do
898
+ "%html\n =yield\n"
899
+ end
900
+
901
+ template :index do
902
+ '%div.title Hallo Welt!'
903
+ end
904
+
905
+ get '/' do
906
+ haml :index
907
+ end
908
+ ```
909
+
910
+ Wenn ein Template mit dem Namen "layout" existiert, wird es bei jedem Aufruf
911
+ verwendet. Durch `:layout => false` kann das Ausführen verhindert werden:
912
+
913
+ ```ruby
914
+ get '/' do
915
+ haml :index, :layout => request.xhr?
916
+ end
917
+ ```
918
+
919
+ ### Dateiendungen zuordnen
920
+
921
+ Um eine Dateiendung einer Template-Engine zuzuordnen, kann `Tilt.register`
922
+ genutzt werden. Wenn etwa die Dateiendung `tt` für Textile-Templates genutzt
923
+ werden soll, lässt sich dies wie folgt bewerkstelligen:
924
+
925
+ ```ruby
926
+ Tilt.register :tt, Tilt[:textile]
927
+ ```
928
+
929
+ ### Eine eigene Template-Engine hinzufügen
930
+
931
+ Zu allererst muss die Engine bei Tilt registriert und danach eine
932
+ Rendering-Methode erstellt werden:
933
+
934
+ ```ruby
935
+ Tilt.register :mtt, MeineTolleTemplateEngine
936
+
937
+ helpers do
938
+ def mtt(*args) render(:mtt, *args) end
939
+ end
940
+
941
+ get '/' do
942
+ mtt :index
943
+ end
944
+ ```
945
+
946
+ Dieser Code rendert `./views/application.mtt`. Siehe
947
+ [github.com/rtomayko/tilt](https://github.com/rtomayko/tilt), um mehr über
948
+ Tilt zu erfahren.
949
+
950
+ ## Filter
951
+
952
+ Before-Filter werden vor jedem Request in demselben Kontext, wie danach die
953
+ Routen, ausgeführt. So können etwa Request und Antwort geändert werden.
954
+ Gesetzte Instanzvariablen in Filtern können in Routen und Templates verwendet
955
+ werden:
956
+
957
+ ```ruby
958
+ before do
959
+ @note = 'Hi!'
960
+ request.path_info = '/foo/bar/baz'
961
+ end
962
+
963
+ get '/foo/*' do
964
+ @note #=> 'Hi!'
965
+ params[:splat] #=> 'bar/baz'
966
+ end
967
+ ```
968
+
969
+ After-Filter werden nach jedem Request in demselben Kontext ausgeführt und
970
+ können ebenfalls Request und Antwort ändern. In Before-Filtern gesetzte
971
+ Instanzvariablen können in After-Filtern verwendet werden:
972
+
973
+ ```ruby
974
+ after do
975
+ puts response.status
976
+ end
977
+ ```
978
+
979
+ Filter können optional auch mit einem Muster ausgestattet werden, welches auf
980
+ den Request-Pfad passen muss, damit der Filter ausgeführt wird:
981
+
982
+ ```ruby
983
+ before '/protected/*' do
984
+ authenticate!
985
+ end
986
+
987
+ after '/create/:slug' do |slug|
988
+ session[:last_slug] = slug
989
+ end
990
+ ```
991
+
992
+ Ähnlich wie Routen können Filter auch mit weiteren Bedingungen eingeschränkt
993
+ werden:
994
+
995
+ ```ruby
996
+ before :agent => /Songbird/ do
997
+ # ...
998
+ end
999
+
1000
+ after '/blog/*', :host_name => 'example.com' do
1001
+ # ...
1002
+ end
1003
+ ```
1004
+
1005
+ ## Helfer
1006
+
1007
+ Durch die Top-Level `helpers`-Methode werden sogenannte Helfer-Methoden
1008
+ definiert, die in Routen und Templates verwendet werden können:
1009
+
1010
+ ```ruby
1011
+ helpers do
1012
+ def bar(name)
1013
+ "#{name}bar"
1014
+ end
1015
+ end
1016
+
1017
+ get '/:name' do
1018
+ bar(params[:name])
1019
+ end
1020
+ ```
1021
+
1022
+ ### Sessions verwenden
1023
+ Sessions werden verwendet, um Zustände zwischen den Requests zu speichern. Sind
1024
+ sie aktiviert, kann ein Session-Hash je Benutzer-Session verwendet werden:
1025
+
1026
+ ```ruby
1027
+ enable :sessions
1028
+
1029
+ get '/' do
1030
+ "value = " << session[:value].inspect
1031
+ end
1032
+
1033
+ get '/:value' do
1034
+ session[:value] = params[:value]
1035
+ end
1036
+ ```
1037
+
1038
+ Beachte, dass `enable :sessions` alle Daten in einem Cookie speichert. Unter
1039
+ Umständen kann dies negative Effekte haben, z.B. verursachen viele Daten
1040
+ höheren, teilweise überflüssigen Traffic. Um das zu vermeiden, kann eine Rack-
1041
+ Session-Middleware verwendet werden. Dabei wird auf `enable :sessions`
1042
+ verzichtet und die Middleware wie üblich im Programm eingebunden:
1043
+
1044
+ ```ruby
1045
+ use Rack::Session::Pool, :expire_after => 2592000
1046
+
1047
+ get '/' do
1048
+ "value = " << session[:value].inspect
1049
+ end
1050
+
1051
+ get '/:value' do
1052
+ session[:value] = params[:value]
1053
+ end
1054
+ ```
1055
+
1056
+ Um die Sicherheit zu erhöhen, werden Cookies, die Session-Daten führen, mit
1057
+ einem sogenannten Session-Secret signiert. Da sich dieses Geheimwort bei jedem
1058
+ Neustart der Applikation automatisch ändert, ist es sinnvoll, ein eigenes zu
1059
+ wählen, damit sich alle Instanzen der Applikation dasselbe Session-Secret
1060
+ teilen:
1061
+
1062
+ ```ruby
1063
+ set :session_secret, 'super secret'
1064
+ ```
1065
+
1066
+ Zur weiteren Konfiguration kann man einen Hash mit Optionen in den `sessions`
1067
+ Einstellungen ablegen.
1068
+
1069
+ ```ruby
1070
+ set :sessions, :domain => 'foo.com'
1071
+ ```
1072
+
1073
+ ## Anhalten
1074
+
1075
+ Zum sofortigen Stoppen eines Request in einem Filter oder einer Route:
1076
+
1077
+ ```ruby
1078
+ halt
1079
+ ```
1080
+
1081
+ Der Status kann beim Stoppen auch angegeben werden:
1082
+
1083
+ ```ruby
1084
+ halt 410
1085
+ ```
1086
+
1087
+ Oder auch den Response-Body:
1088
+
1089
+ ```ruby
1090
+ halt 'Hier steht der Body'
1091
+ ```
1092
+
1093
+ Oder beides:
1094
+
1095
+ ```ruby
1096
+ halt 401, 'verschwinde!'
1097
+ ```
1098
+
1099
+ Sogar mit Headern:
1100
+
1101
+ ```ruby
1102
+ halt 402, {'Content-Type' => 'text/plain'}, 'Rache'
1103
+ ```
1104
+
1105
+ Natürlich ist es auch möglich, ein Template mit `halt` zu verwenden:
1106
+
1107
+ ```ruby
1108
+ halt erb(:error)
1109
+ ```
1110
+
1111
+ ## Weiterspringen
1112
+
1113
+ Eine Route kann mittels `pass` zu der nächsten passenden Route springen:
1114
+
1115
+ ```ruby
1116
+ get '/raten/:wer' do
1117
+ pass unless params[:wer] == 'Frank'
1118
+ 'Du hast mich!'
1119
+ end
1120
+
1121
+ get '/raten/*' do
1122
+ 'Du hast mich nicht!'
1123
+ end
1124
+ ```
1125
+
1126
+ Der Block wird sofort verlassen und es wird nach der nächsten treffenden Route
1127
+ gesucht. Ein 404-Fehler wird zurückgegeben, wenn kein treffendes Routen-Muster
1128
+ gefunden wird.
1129
+
1130
+ ### Eine andere Route ansteuern
1131
+
1132
+ Manchmal entspricht `pass` nicht den Anforderungen, wenn das Ergebnis einer
1133
+ anderen Route gefordert wird. Um das zu erreichen, lässt sich `call` nutzen:
1134
+
1135
+ ```ruby
1136
+ get '/foo' do
1137
+ status, headers, body = call env.merge("PATH_INFO" => '/bar')
1138
+ [status, headers, body.map(&:upcase)]
1139
+ end
1140
+
1141
+ get '/bar' do
1142
+ "bar"
1143
+ end
1144
+ ```
1145
+
1146
+ Beachte, dass in dem oben angegeben Beispiel die Performance erheblich erhöht
1147
+ werden kann, wenn `"bar"` in eine Helfer-Methode umgewandelt wird, auf die
1148
+ `/foo` und `/bar` zugreifen können.
1149
+
1150
+ Wenn der Request innerhalb derselben Applikations-Instanz aufgerufen und keine
1151
+ Kopie der Instanz erzeugt werden soll, kann `call!` anstelle von `call`
1152
+ verwendet werden.
1153
+
1154
+ Die Rack-Spezifikationen enthalten weitere Informationen zu `call`.
1155
+
1156
+ ### Body, Status-Code und Header setzen
1157
+
1158
+ Es ist möglich und empfohlen, den Status-Code sowie den Response-Body mit
1159
+ einem Returnwert in der Route zu setzen. In manchen Situationen kann es jedoch
1160
+ sein, dass der Body an irgendeiner anderen Stelle während der Ausführung
1161
+ gesetzt wird. Das lässt sich mit der Helfer-Methode `body` bewerkstelligen.
1162
+ Wird `body` verwendet, lässt sich der Body jederzeit über diese Methode
1163
+ aufrufen:
1164
+
1165
+ ```ruby
1166
+ get '/foo' do
1167
+ body "bar"
1168
+ end
1169
+
1170
+ after do
1171
+ puts body
1172
+ end
1173
+ ```
1174
+
1175
+ Ebenso ist es möglich, einen Block an `body` weiterzureichen, der dann vom
1176
+ Rack-Handler ausgeführt wird (lässt sich z.B. zur Umsetzung von Streaming
1177
+ einsetzen, siehe auch "Rückgabewerte").
1178
+
1179
+ Vergleichbar mit `body` lassen sich auch Status-Code und Header setzen:
1180
+
1181
+ ```ruby
1182
+ get '/foo' do
1183
+ status 418
1184
+ headers \
1185
+ "Allow" => "BREW, POST, GET, PROPFIND, WHEN",
1186
+ "Refresh" => "Refresh: 20; http://www.ietf.org/rfc/rfc2324.txt"
1187
+ halt "Ich bin ein Teekesselchen"
1188
+ end
1189
+ ```
1190
+
1191
+ Genau wie bei `body` liest ein Aufrufen von `headers` oder `status` ohne
1192
+ Argumente den aktuellen Wert aus.
1193
+
1194
+ ### Response-Streams
1195
+
1196
+ In manchen Situationen sollen Daten bereits an den Client zurückgeschickt
1197
+ werden, bevor ein vollständiger Response bereit steht. Manchmal will man die
1198
+ Verbindung auch erst dann beenden und Daten so lange an den Client
1199
+ zurückschicken, bis er die Verbindung abbricht. Für diese Fälle gibt es die
1200
+ `stream`-Helfer-Methode, die es einem erspart eigene Lösungen zu schreiben:
1201
+
1202
+ ```ruby
1203
+ get '/' do
1204
+ stream do |out|
1205
+ out << "Das ist ja mal wieder fanta -\n"
1206
+ sleep 0.5
1207
+ out << " (bitte warten…) \n"
1208
+ sleep 1
1209
+ out << "- stisch!\n"
1210
+ end
1211
+ end
1212
+ ```
1213
+
1214
+ Damit lassen sich Streaming-APIs realisieren, sog.
1215
+ [Server Sent Events](http://dev.w3.org/html5/eventsource/) die als Basis für
1216
+ [WebSockets](http://en.wikipedia.org/wiki/WebSocket) dienen. Ebenso können sie
1217
+ verwendet werden, um den Durchsatz zu erhöhen, wenn ein Teil der Daten von
1218
+ langsamen Ressourcen abhängig ist.
1219
+
1220
+ Es ist zu beachten, dass das Verhalten beim Streaming, insbesondere die Anzahl
1221
+ nebenläufiger Anfragen, stark davon abhängt, welcher Webserver für die
1222
+ Applikation verwendet wird. Einige Server, z.B. WEBRick, unterstützen
1223
+ Streaming nicht oder nur teilweise. Sollte der Server Streaming nicht
1224
+ unterstützen, wird ein vollständiger Response-Body zurückgeschickt, sobald der
1225
+ an `stream` weitergegebene Block abgearbeitet ist. Mit Shotgun funktioniert
1226
+ Streaming z.B. überhaupt nicht.
1227
+
1228
+ Ist der optionale Parameter `keep_open` aktiviert, wird beim gestreamten Objekt
1229
+ `close` nicht aufgerufen und es ist einem überlassen dies an einem beliebigen
1230
+ späteren Zeitpunkt nachholen. Die Funktion ist jedoch nur bei Event-gesteuerten
1231
+ Serven wie Thin oder Rainbows möglich, andere Server werden trotzdem den Stream
1232
+ beenden:
1233
+
1234
+ ```ruby
1235
+ set :server, :thin
1236
+ connections = []
1237
+
1238
+ get '/' do
1239
+ # Den Stream offen halten
1240
+ stream(:keep_open) { |out| connections << out }
1241
+ end
1242
+
1243
+ post '/' do
1244
+ # In alle offenen Streams schreiben
1245
+ connections.each { |out| out << params[:message] << "\n" }
1246
+ "Nachricht verschickt"
1247
+ end
1248
+ ```
1249
+
1250
+ ### Logger
1251
+
1252
+ Im Geltungsbereich eines Request stellt die `logger` Helfer-Methode eine `Logger`
1253
+ Instanz zur Verfügung:
1254
+
1255
+ ```ruby
1256
+ get '/' do
1257
+ logger.info "es passiert gerade etwas"
1258
+ # ...
1259
+ end
1260
+ ```
1261
+
1262
+ Der Logger übernimmt dabei automatisch alle im Rack-Handler eingestellten
1263
+ Log-Vorgaben. Ist Loggen ausgeschaltet, gibt die Methode ein Leerobjekt zurück.
1264
+ In den Routen und Filtern muss man sich also nicht weiter darum kümmern.
1265
+
1266
+ Beachte, dass das Loggen standardmäßig nur für `Sinatra::Application`
1267
+ voreingestellt ist. Wird über `Sinatra::Base` vererbt, muss es erst aktiviert
1268
+ werden:
1269
+
1270
+ ```ruby
1271
+ class MyApp < Sinatra::Base
1272
+ configure :production, :development do
1273
+ enable :logging
1274
+ end
1275
+ end
1276
+ ```
1277
+
1278
+ Damit auch keine Middleware das Logging aktivieren kann, muss die `logging`
1279
+ Einstellung auf `nil` gesetzt werden. Das heißt aber auch, dass `logger` in
1280
+ diesem Fall `nil` zurückgeben wird. Üblicherweise wird das eingesetzt, wenn ein
1281
+ eigener Logger eingerichtet werden soll. Sinatra wird dann verwenden, was in
1282
+ `env['rack.logger']` eingetragen ist.
1283
+
1284
+ ## Mime-Types
1285
+
1286
+ Wenn `send_file` oder statische Dateien verwendet werden, kann es vorkommen,
1287
+ dass Sinatra den Mime-Typ nicht kennt. Registriert wird dieser mit `mime_type`
1288
+ per Dateiendung:
1289
+
1290
+ ```ruby
1291
+ configure do
1292
+ mime_type :foo, 'text/foo'
1293
+ end
1294
+ ```
1295
+
1296
+ Es kann aber auch der `content_type`-Helfer verwendet werden:
1297
+
1298
+ ```ruby
1299
+ get '/' do
1300
+ content_type :foo
1301
+ "foo foo foo"
1302
+ end
1303
+ ```
1304
+
1305
+ ### URLs generieren
1306
+
1307
+ Zum Generieren von URLs sollte die `url`-Helfer-Methode genutzen werden, so z.B.
1308
+ beim Einsatz von Haml:
1309
+
1310
+ ```ruby
1311
+ %a{:href => url('/foo')} foo
1312
+ ```
1313
+
1314
+ Soweit vorhanden, wird Rücksicht auf Proxys und Rack-Router genommen.
1315
+
1316
+ Diese Methode ist ebenso über das Alias `to` zu erreichen (siehe Beispiel unten).
1317
+
1318
+ ### Browser-Umleitung
1319
+
1320
+ Eine Browser-Umleitung kann mithilfe der `redirect`-Helfer-Methode erreicht
1321
+ werden:
1322
+
1323
+ ```ruby
1324
+ get '/foo' do
1325
+ redirect to('/bar')
1326
+ end
1327
+ ```
1328
+
1329
+ Weitere Parameter werden wie Argumente der `halt`-Methode behandelt:
1330
+
1331
+ ```ruby
1332
+ redirect to('/bar'), 303
1333
+ redirect 'http://google.com', 'Hier bist du falsch'
1334
+ ```
1335
+
1336
+ Ebenso leicht lässt sich ein Schritt zurück mit dem Alias `redirect back`
1337
+ erreichen:
1338
+
1339
+ ```ruby
1340
+ get '/foo' do
1341
+ "<a href='/bar'>mach was</a>"
1342
+ end
1343
+
1344
+ get '/bar' do
1345
+ mach_was
1346
+ redirect back
1347
+ end
1348
+ ```
1349
+
1350
+ Um Argumente an ein Redirect weiterzugeben, können sie entweder dem Query
1351
+ übergeben:
1352
+
1353
+ ```ruby
1354
+ redirect to('/bar?summe=42')
1355
+ ```
1356
+
1357
+ oder eine Session verwendet werden:
1358
+
1359
+ ```ruby
1360
+ enable :sessions
1361
+
1362
+ get '/foo' do
1363
+ session[:secret] = 'foo'
1364
+ redirect to('/bar')
1365
+ end
1366
+
1367
+ get '/bar' do
1368
+ session[:secret]
1369
+ end
1370
+ ```
1371
+
1372
+ ### Cache einsetzen
1373
+
1374
+ Ein sinnvolles Einstellen von Header-Daten ist die Grundlage für ein
1375
+ ordentliches HTTP-Caching.
1376
+
1377
+ Der Cache-Control-Header lässt sich ganz einfach einstellen:
1378
+
1379
+ ```ruby
1380
+ get '/' do
1381
+ cache_control :public
1382
+ "schon gecached!"
1383
+ end
1384
+ ```
1385
+
1386
+ Profitipp: Caching im before-Filter aktivieren
1387
+
1388
+ ```ruby
1389
+ before do
1390
+ cache_control :public, :must_revalidate, :max_age => 60
1391
+ end
1392
+ ```
1393
+
1394
+ Bei Verwendung der `expires`-Helfermethode zum Setzen des gleichnamigen Headers,
1395
+ wird `Cache-Control` automatisch eigestellt:
1396
+
1397
+ ```ruby
1398
+ before do
1399
+ expires 500, :public, :must_revalidate
1400
+ end
1401
+ ```
1402
+
1403
+ Um alles richtig zu machen, sollten auch `etag` oder `last_modified` verwendet
1404
+ werden. Es wird empfohlen, dass diese Helfer aufgerufen werden **bevor** die
1405
+ eigentliche Arbeit anfängt, da sie sofort eine Antwort senden, wenn der Client
1406
+ eine aktuelle Version im Cache vorhält:
1407
+
1408
+ ```ruby
1409
+ get '/article/:id' do
1410
+ @article = Article.find params[:id]
1411
+ last_modified @article.updated_at
1412
+ etag @article.sha1
1413
+ erb :article
1414
+ end
1415
+ ```
1416
+
1417
+ ebenso ist es möglich einen
1418
+ [schwachen ETag](http://de.wikipedia.org/wiki/HTTP_ETag) zu verwenden:
1419
+
1420
+ ```ruby
1421
+ etag @article.sha1, :weak
1422
+ ```
1423
+
1424
+ Diese Helfer führen nicht das eigentliche Caching aus, sondern geben die dafür
1425
+ notwendigen Informationen an den Cache weiter. Für schnelle Reverse-Proxy
1426
+ Cache-Lösungen bietet sich z.B.
1427
+ [rack-cache](https://github.com/rtomayko/rack-cache) an:
1428
+
1429
+ ```ruby
1430
+ require "rack/cache"
1431
+ require "sinatra"
1432
+
1433
+ use Rack::Cache
1434
+
1435
+ get '/' do
1436
+ cache_control :public, :max_age => 36000
1437
+ sleep 5
1438
+ "hello"
1439
+ end
1440
+ ```
1441
+
1442
+ Um den `Cache-Control`-Header mit Informationen zu versorgen, verwendet man die
1443
+ `:static_cache_control`-Einstellung (s.u.).
1444
+
1445
+ Nach RFC 2616 sollte sich die Anwendung anders verhalten, wenn ein If-Match oder
1446
+ ein If-None_match Header auf `*` gesetzt wird in Abhängigkeit davon, ob die
1447
+ Resource bereits existiert. Sinatra geht davon aus, dass Ressourcen bei sicheren
1448
+ Anfragen (z.B. bei get oder Idempotenten Anfragen wie put) bereits existieren,
1449
+ wobei anderen Ressourcen (besipielsweise bei post), als neue Ressourcen
1450
+ behandelt werden. Dieses Verhalten lässt sich mit der `:new_resource` Option
1451
+ ändern:
1452
+
1453
+ ```ruby
1454
+ get '/create' do
1455
+ etag '', :new_resource => true
1456
+ Article.create
1457
+ erb :new_article
1458
+ end
1459
+ ```
1460
+
1461
+ Soll das schwache ETag trotzdem verwendet werden, verwendet man die `:kind`
1462
+ Option:
1463
+
1464
+ ```ruby
1465
+ etag '', :new_resource => true, :kind => :weak
1466
+ ```
1467
+
1468
+ ### Dateien versenden
1469
+
1470
+ Zum Versenden von Dateien kann die `send_file`-Helfer-Methode verwendet werden:
1471
+
1472
+ ```ruby
1473
+ get '/' do
1474
+ send_file 'foo.png'
1475
+ end
1476
+ ```
1477
+
1478
+ Für `send_file` stehen einige Hash-Optionen zur Verfügung:
1479
+
1480
+ ```ruby
1481
+ send_file 'foo.png', :type => :jpg
1482
+ ```
1483
+
1484
+ <dl>
1485
+ <dt>filename</dt>
1486
+ <dd>Dateiname als Response. Standardwert ist der eigentliche Dateiname.</dd>
1487
+
1488
+ <dt>last_modified</dt>
1489
+ <dd>Wert für den Last-Modified-Header, Standardwert ist <tt>mtime</tt> der
1490
+ Datei.</dd>
1491
+
1492
+ <dt>type</dt>
1493
+ <dd>Content-Type, der verwendet werden soll. Wird, wenn nicht angegeben, von
1494
+ der Dateiendung abgeleitet.</dd>
1495
+
1496
+ <dt>disposition</dt>
1497
+ <dd>Verwendet für Content-Disposition. Mögliche Werte sind: <tt>nil</tt>
1498
+ (Standard), <tt>:attachment</tt> und <tt>:inline</tt>.</dd>
1499
+
1500
+ <dt>length</dt>
1501
+ <dd>Content-Length-Header. Standardwert ist die Dateigröße.</dd>
1502
+ </dl>
1503
+
1504
+ Soweit vom Rack-Handler unterstützt, werden neben der Übertragung über den
1505
+ Ruby-Prozess auch andere Möglichkeiten genutzt. Bei Verwendung der
1506
+ `send_file`-Helfer-Methode kümmert sich Sinatra selbstständig um die
1507
+ Range-Requests.
1508
+
1509
+ ## Das Request-Objekt
1510
+
1511
+ Auf das `request`-Objekt der eigehenden Anfrage kann vom Anfrage-Scope aus
1512
+ zugegriffen werden:
1513
+
1514
+ ```ruby
1515
+ # App läuft unter http://example.com/example
1516
+ get '/foo' do
1517
+ t = %w[text/css text/html application/javascript]
1518
+ request.accept # ['text/html', '*/*']
1519
+ request.accept? 'text/xml' # true
1520
+ request.preferred_type(t) # 'text/html'
1521
+ request.body # Request-Body des Client (siehe unten)
1522
+ request.scheme # "http"
1523
+ request.script_name # "/example"
1524
+ request.path_info # "/foo"
1525
+ request.port # 80
1526
+ request.request_method # "GET"
1527
+ request.query_string # ""
1528
+ request.content_length # Länge des request.body
1529
+ request.media_type # Medientypus von request.body
1530
+ request.host # "example.com"
1531
+ request.get? # true (ähnliche Methoden für andere Verben)
1532
+ request.form_data? # false
1533
+ request["IRGENDEIN_HEADER"] # Wert von IRGENDEIN_HEADER header
1534
+ request.referrer # Der Referrer des Clients oder '/'
1535
+ request.user_agent # User-Agent (verwendet in der :agent Bedingung)
1536
+ request.cookies # Hash des Browser-Cookies
1537
+ request.xhr? # Ist das hier ein Ajax-Request?
1538
+ request.url # "http://example.com/example/foo"
1539
+ request.path # "/example/foo"
1540
+ request.ip # IP-Adresse des Clients
1541
+ request.secure? # false (true wenn SSL)
1542
+ request.forwarded? # true (Wenn es hinter einem Reverse-Proxy verwendet wird)
1543
+ request.env # vollständiger env-Hash von Rack übergeben
1544
+ end
1545
+ ```
1546
+
1547
+ Manche Optionen, wie etwa `script_name` oder `path_info`, sind auch
1548
+ schreibbar:
1549
+
1550
+ ```ruby
1551
+ before { request.path_info = "/" }
1552
+
1553
+ get "/" do
1554
+ "Alle Anfragen kommen hier an!"
1555
+ end
1556
+ ```
1557
+
1558
+ Der `request.body` ist ein IO- oder StringIO-Objekt:
1559
+
1560
+ ```ruby
1561
+ post "/api" do
1562
+ request.body.rewind # falls schon jemand davon gelesen hat
1563
+ daten = JSON.parse request.body.read
1564
+ "Hallo #{daten['name']}!"
1565
+ end
1566
+ ```
1567
+
1568
+ ### Anhänge
1569
+
1570
+ Damit der Browser erkennt, dass ein Response gespeichert und nicht im Browser
1571
+ angezeigt werden soll, kann der `attachment`-Helfer verwendet werden:
1572
+
1573
+ ```ruby
1574
+ get '/' do
1575
+ attachment
1576
+ "Speichern!"
1577
+ end
1578
+ ```
1579
+
1580
+ Ebenso kann eine Dateiname als Parameter hinzugefügt werden:
1581
+
1582
+ ```ruby
1583
+ get '/' do
1584
+ attachment "info.txt"
1585
+ "Speichern!"
1586
+ end
1587
+ ```
1588
+
1589
+ ### Umgang mit Datum und Zeit
1590
+
1591
+ Sinatra bietet eine `time_for`-Helfer-Methode, die aus einem gegebenen Wert ein
1592
+ Time-Objekt generiert. Ebenso kann sie nach `DateTime`, `Date` und ähnliche
1593
+ Klassen konvertieren:
1594
+
1595
+ ```ruby
1596
+ get '/' do
1597
+ pass if Time.now > time_for('Dec 23, 2012')
1598
+ "noch Zeit"
1599
+ end
1600
+ ```
1601
+
1602
+ Diese Methode wird intern für +expires, `last_modiefied` und ihresgleichen
1603
+ verwendet. Mit ein paar Handgriffen lässt sich diese Methode also in ihrem
1604
+ Verhalten erweitern, indem man `time_for` in der eigenen Applikation
1605
+ überschreibt:
1606
+
1607
+ ```ruby
1608
+ helpers do
1609
+ def time_for(value)
1610
+ case value
1611
+ when :yesterday then Time.now - 24*60*60
1612
+ when :tomorrow then Time.now + 24*60*60
1613
+ else super
1614
+ end
1615
+ end
1616
+ end
1617
+
1618
+ get '/' do
1619
+ last_modified :yesterday
1620
+ expires :tomorrow
1621
+ "Hallo"
1622
+ end
1623
+ ```
1624
+
1625
+ ### Nachschlagen von Template-Dateien
1626
+
1627
+ Die `find_template`-Helfer-Methode wird genutzt, um Template-Dateien zum Rendern
1628
+ aufzufinden:
1629
+
1630
+ ```ruby
1631
+ find_template settings.views, 'foo', Tilt[:haml] do |file|
1632
+ puts "könnte diese hier sein: #{file}"
1633
+ end
1634
+ ```
1635
+
1636
+ Das ist zwar nicht wirklich brauchbar, aber wenn man sie überschreibt, kann sie
1637
+ nützlich werden, um eigene Nachschlage-Mechanismen einzubauen. Zum Beispiel
1638
+ dann, wenn mehr als nur ein view-Verzeichnis verwendet werden soll:
1639
+
1640
+ ```ruby
1641
+ set :views, ['views', 'templates']
1642
+
1643
+ helpers do
1644
+ def find_template(views, name, engine, &block)
1645
+ Array(views).each { |v| super(v, name, engine, &block) }
1646
+ end
1647
+ end
1648
+ ```
1649
+
1650
+ Ein anderes Beispiel wäre, verschiedene Vereichnisse für verschiedene Engines
1651
+ zu verwenden:
1652
+
1653
+ ```ruby
1654
+ set :views, :sass => 'views/sass', :haml => 'templates', :default => 'views'
1655
+
1656
+ helpers do
1657
+ def find_template(views, name, engine, &block)
1658
+ _, folder = views.detect { |k,v| engine == Tilt[k] }
1659
+ folder ||= views[:default]
1660
+ super(folder, name, engine, &block)
1661
+ end
1662
+ end
1663
+ ```
1664
+
1665
+ Ebensogut könnte eine Extension aber auch geschrieben und mit anderen geteilt
1666
+ werden!
1667
+
1668
+ Beachte, dass `find_template` nicht prüft, ob eine Datei tatsächlich existiert.
1669
+ Es wird lediglich der angegebene Block aufgerufen und nach allen möglichen
1670
+ Pfaden gesucht. Das ergibt kein Performance-Problem, da `render` `block`
1671
+ verwendet, sobald eine Datei gefunden wurde. Ebenso werden Template-Pfade samt
1672
+ Inhalt gecached, solange nicht im Entwicklungsmodus gearbeitet wird. Das sollte
1673
+ im Hinterkopf behalten werden, wenn irgendwelche verrückten Methoden
1674
+ zusammenbastelt werden.
1675
+
1676
+ ## Konfiguration
1677
+
1678
+ Wird einmal beim Starten in jedweder Umgebung ausgeführt:
1679
+
1680
+ ```ruby
1681
+ configure do
1682
+ # setze eine Option
1683
+ set :option, 'wert'
1684
+
1685
+ # setze mehrere Optionen
1686
+ set :a => 1, :b => 2
1687
+
1688
+ # das gleiche wie `set :option, true`
1689
+ enable :option
1690
+
1691
+ # das gleiche wie `set :option, false`
1692
+ disable :option
1693
+
1694
+ # dynamische Einstellungen mit Blöcken
1695
+ set(:css_dir) { File.join(views, 'css') }
1696
+ end
1697
+ ```
1698
+
1699
+ Läuft nur, wenn die Umgebung (RACK_ENV-Umgebungsvariable) auf `:production`
1700
+ gesetzt ist:
1701
+
1702
+ ```ruby
1703
+ configure :production do
1704
+ ...
1705
+ end
1706
+ ```
1707
+
1708
+ Läuft nur, wenn die Umgebung auf `:production` oder auf `:test` gesetzt ist:
1709
+
1710
+ ```ruby
1711
+ configure :production, :test do
1712
+ ...
1713
+ end
1714
+ ```
1715
+
1716
+ Diese Einstellungen sind über `settings` erreichbar:
1717
+
1718
+ ```ruby
1719
+ configure do
1720
+ set :foo, 'bar'
1721
+ end
1722
+
1723
+ get '/' do
1724
+ settings.foo? # => true
1725
+ settings.foo # => 'bar'
1726
+ ...
1727
+ end
1728
+ ```
1729
+
1730
+ ### Einstellung des Angriffsschutzes
1731
+
1732
+ Sinatra verwendet
1733
+ [Rack::Protection](https://github.com/rkh/rack-protection#readme), um die
1734
+ Anwendung vor häufig vorkommenden Angriffen zu schützen. Diese Voreinstellung
1735
+ lässt sich selbstverständlich deaktivieren, der damit verbundene
1736
+ Geschwindigkeitszuwachs steht aber in keinem Verhätnis zu den möglichen
1737
+ Risiken.
1738
+
1739
+ ```ruby
1740
+ disable :protection
1741
+ ```
1742
+
1743
+ Um einen bestimmten Schutzmechanismus zu deaktivieren, fügt man `protection`
1744
+ einen Hash mit Optionen hinzu:
1745
+
1746
+ ```ruby
1747
+ set :protection, :except => :path_traversal
1748
+ ```
1749
+
1750
+ Neben Strings akzeptiert `:except` auch Arrays, um gleich mehrere
1751
+ Schutzmechanismen zu deaktivieren:
1752
+
1753
+ ```ruby
1754
+ set :protection, :except => [:path_traversal, :session_hijacking]
1755
+ ```
1756
+ ## Möglichee Einstellungen
1757
+
1758
+ <dl>
1759
+ <dt>absolute_redirects</dt>
1760
+ <dd>Wenn ausgeschaltet, wird Sinatra relative Redirects zulassen. Jedoch ist
1761
+ Sinatra dann nicht mehr mit RFC 2616 (HTTP 1.1) konform, das nur absolute
1762
+ Redirects zulässt. Sollte eingeschaltet werden, wenn die Applikation hinter
1763
+ einem Reverse-Proxy liegt, der nicht ordentlich eingerichtet ist. Beachte,
1764
+ dass die <tt>url</tt>-Helfer-Methode nach wie vor absolute URLs erstellen
1765
+ wird, es sei denn, es wird als zweiter Parameter <tt>false</tt> angegeben.
1766
+ Standardmäßig nicht aktiviert.</dd>
1767
+
1768
+ <dt>add_charsets</dt>
1769
+ <dd>
1770
+ Mime-Types werden hier automatisch der Helfer-Methode <tt>content_type</tt>
1771
+ zugeordnet. Es empfielt sich, Werte hinzuzufügen statt sie zu
1772
+ überschreiben: <tt>settings.add_charsets << "application/foobar"</tt>
1773
+ </dd>
1774
+
1775
+ <dt>app_file</dt>
1776
+ <dd>Pfad zur Hauptdatei der Applikation. Wird verwendet, um das Wurzel-,
1777
+ Inline-, View- und öffentliche Verzeichnis des Projekts festzustellen.</dd>
1778
+
1779
+ <dt>bind</dt>
1780
+ <dd>IP-Address, an die gebunden wird (Standardwert: 0.0.0.0). Wird nur für
1781
+ den eingebauten Server verwendet.</dd>
1782
+
1783
+ <dt>default_encoding</dt>
1784
+ <dd>Das Encoding, falls keines angegeben wurde. Standardwert ist
1785
+ <tt>"utf-8"</tt>.</dd>
1786
+
1787
+ <dt>dump_errors</dt>
1788
+ <dd>Fehler im Log anzeigen.</dd>
1789
+
1790
+ <dt>environment</dt>
1791
+ <dd>Momentane Umgebung. Standardmäßig auf <tt>content_type</tt> oder
1792
+ <tt>"development"</tt> eingestellt, soweit ersteres nicht vorhanden.</dd>
1793
+
1794
+ <dt>logging</dt>
1795
+ <dd>Den Logger verwenden.</dd>
1796
+
1797
+ <dt>lock</dt>
1798
+ <dd>Jeder Request wird gelocked. Es kann nur ein Request pro Ruby-Prozess
1799
+ gleichzeitig verarbeitet werden. Eingeschaltet, wenn die Applikation
1800
+ threadsicher ist. Standardmäßig nicht aktiviert.</dd>
1801
+
1802
+ <dt>method_override</dt>
1803
+ <dd>Verwende <tt>_method</tt>, um put/delete-Formulardaten in Browsern zu
1804
+ verwenden, die dies normalerweise nicht unterstützen.</dd>
1805
+
1806
+ <dt>port</dt>
1807
+ <dd>Port für die Applikation. Wird nur im internen Server verwendet.</dd>
1808
+
1809
+ <dt>prefixed_redirects</dt>
1810
+ <dd>Entscheidet, ob <tt>request.script_name</tt> in Redirects eingefügt wird
1811
+ oder nicht, wenn kein absoluter Pfad angegeben ist. Auf diese Weise verhält
1812
+ sich <tt>redirect '/foo'</tt> so, als wäre es ein <tt>redirect
1813
+ to('/foo')</tt>. Standardmäßig nicht aktiviert.</dd>
1814
+
1815
+ <dt>protection</dt>
1816
+ <dd>Legt fest, ob der Schutzmechanismus für häufig Vorkommende Webangriffe
1817
+ auf Webapplikationen aktiviert wird oder nicht. Weitere Informationen im
1818
+ vorhergehenden Abschnitt.</dd>
1819
+
1820
+ <dt>public_folder</dt>
1821
+ <dd>Das öffentliche Verzeichnis, aus dem Daten zur Verfügung gestellt werden
1822
+ können. Wird nur dann verwendet, wenn statische Daten zur Verfügung gestellt
1823
+ werden können (s.u. <tt>static</tt> Option). Leitet sich von der
1824
+ <tt>app_file</tt> Einstellung ab, wenn nicht gesetzt.</dd>
1825
+
1826
+ <dt>public_dir</dt>
1827
+ <dd>Alias für <tt>public_folder</tt>, s.o.</dd>
1828
+
1829
+ <dt>reload_templates</dt>
1830
+ <dd>Im development-Modus aktiviert.</dd>
1831
+
1832
+ <dt>root</dt>
1833
+ <dd>Wurzelverzeichnis des Projekts. Leitet sich von der <tt>app_file</tt>
1834
+ Einstellung ab, wenn nicht gesetzt.</dd>
1835
+
1836
+ <dt>raise_errors</dt>
1837
+ <dd>Einen Ausnahmezustand aufrufen. Beendet die Applikation. Ist automatisch
1838
+ aktiviert, wenn die Umgebung auf <tt>"test"</tt> eingestellt ist. Ansonsten
1839
+ ist diese Option deaktiviert.</dd>
1840
+
1841
+ <dt>run</dt>
1842
+ <dd>Wenn aktiviert, wird Sinatra versuchen, den Webserver zu starten. Nicht
1843
+ verwenden, wenn Rackup oder anderes verwendet werden soll.</dd>
1844
+
1845
+ <dt>running</dt>
1846
+ <dd>Läuft der eingebaute Server? Diese Einstellung nicht ändern!</dd>
1847
+
1848
+ <dt>server</dt>
1849
+ <dd>Server oder Liste von Servern, die als eingebaute Server zur Verfügung
1850
+ stehen. Standardmäßig auf [‘thin’, ‘mongrel’, ‘webrick’] voreingestellt. Die
1851
+ Anordnung gibt die Priorität
1852
+ vor.</dd>
1853
+
1854
+ <dt>sessions</dt>
1855
+ <dd>Sessions auf Cookiebasis mittels
1856
+ <tt>Rack::Session::Cookie</tt>aktivieren. Für weitere Infos bitte in der
1857
+ Sektion ‘Sessions verwenden’ nachschauen.</dd>
1858
+
1859
+ <dt>show_exceptions</dt>
1860
+ <dd>Bei Fehlern einen Stacktrace im Browseranzeigen. Ist automatisch
1861
+ aktiviert, wenn die Umgebung auf <tt>"development"</tt> eingestellt ist.
1862
+ Ansonsten ist diese Option deaktiviert. Kann auch auf <tt>:after_handler</tt>
1863
+ gestellt werden, um eine anwendungsspezifische Fehlerbehandlung auszulösen,
1864
+ bevor der Fehlerverlauf im Browser angezeigt wird.</dd>
1865
+
1866
+ <dt>static</dt>
1867
+ <dd>Entscheidet, ob Sinatra statische Dateien zur Verfügung stellen soll oder
1868
+ nicht. Sollte nicht aktiviert werden, wenn ein Server verwendet wird, der
1869
+ dies auch selbstständig erledigen kann. Deaktivieren wird die Performance
1870
+ erhöhen. Standardmäßig aktiviert.</dd>
1871
+
1872
+ <dt>static_cache_control</dt>
1873
+ <dd>Wenn Sinatra statische Daten zur Verfügung stellt, können mit dieser
1874
+ Einstellung die <tt>Cache-Control</tt> Header zu den Responses hinzugefügt
1875
+ werden. Die Einstellung verwendet dazu die <tt>cache_control</tt>
1876
+ Helfer-Methode. Standardmäßig deaktiviert. Ein Array wird verwendet, um
1877
+ mehrere Werte gleichzeitig zu übergeben: <tt>set :static_cache_control,
1878
+ [:public, :max_age => 300]</tt></dd>
1879
+
1880
+ <dt>views</dt>
1881
+ <dd>Verzeichnis der Views. Leitet sich von der <tt>app_file</tt> Einstellung
1882
+ ab, wenn nicht gesetzt.</dd>
1883
+ </dl>
1884
+
1885
+ ## Umgebungen
1886
+
1887
+ Es gibt drei voreingestellte Umgebungen in Sinatra: `"development"`,
1888
+ `"production"` und `"test"`. Umgebungen können über die `RACK_ENV`
1889
+ Umgebungsvariable gesetzt werden. Die Standardeinstellung ist `"development"`.
1890
+ In diesem Modus werden alle Templates zwischen Requests neu geladen. Dazu gibt
1891
+ es besondere Fehlerseiten für 404 Stati und Fehlermeldungen. In `"production"`
1892
+ und `"test"` werden Templates automatisch gecached.
1893
+
1894
+ Um die Anwendung in einer anderen Umgebung auszuführen kann man die `-e`
1895
+ Option verwenden:
1896
+
1897
+ ```
1898
+ ruby my_app.rb -e [ENVIRONMENT]
1899
+ ```
1900
+
1901
+ In der Anwendung kann man die die Methoden `development?`, `test?` und
1902
+ `production?` verwenden, um die aktuelle Umgebung zu erfahren.
1903
+
1904
+ ## Fehlerbehandlung
1905
+
1906
+ Error-Handler laufen in demselben Kontext wie Routen und Filter, was bedeutet,
1907
+ dass alle Goodies wie `haml`, `erb`, `halt`, etc. verwendet werden können.
1908
+
1909
+ ### Nicht gefunden
1910
+
1911
+ Wenn eine `Sinatra::NotFound`-Exception geworfen wird oder der Statuscode 404
1912
+ ist, wird der `not_found`-Handler ausgeführt:
1913
+
1914
+ ```ruby
1915
+ not_found do
1916
+ 'Seite kann nirgendwo gefunden werden.'
1917
+ end
1918
+ ```
1919
+
1920
+ ### Fehler
1921
+
1922
+ Der `error`-Handler wird immer ausgeführt, wenn eine Exception in einem
1923
+ Routen-Block oder in einem Filter geworfen wurde. Die Exception kann über die
1924
+ `sinatra.error`-Rack-Variable angesprochen werden:
1925
+
1926
+ ```ruby
1927
+ error do
1928
+ 'Entschuldige, es gab einen hässlichen Fehler - ' + env['sinatra.error'].name
1929
+ end
1930
+ ```
1931
+
1932
+ Benutzerdefinierte Fehler:
1933
+
1934
+ ```ruby
1935
+ error MeinFehler do
1936
+ 'Au weia, ' + env['sinatra.error'].message
1937
+ end
1938
+ ```
1939
+
1940
+ Dann, wenn das passiert:
1941
+
1942
+ ```ruby
1943
+ get '/' do
1944
+ raise MeinFehler, 'etwas Schlimmes ist passiert'
1945
+ end
1946
+ ```
1947
+
1948
+ bekommt man dieses:
1949
+
1950
+ ```
1951
+ Au weia, etwas Schlimmes ist passiert
1952
+ ```
1953
+
1954
+ Alternativ kann ein Error-Handler auch für einen Status-Code definiert werden:
1955
+
1956
+ ```ruby
1957
+ error 403 do
1958
+ 'Zugriff verboten'
1959
+ end
1960
+
1961
+ get '/geheim' do
1962
+ 403
1963
+ end
1964
+ ```
1965
+
1966
+ Oder ein Status-Code-Bereich:
1967
+
1968
+ ```ruby
1969
+ error 400..510 do
1970
+ 'Hallo?'
1971
+ end
1972
+ ```
1973
+
1974
+ Sinatra setzt verschiedene `not_found`- und `error`-Handler in der
1975
+ Development-Umgebung.
1976
+
1977
+ ## Rack-Middleware
1978
+
1979
+ Sinatra baut auf [Rack](http://rack.rubyforge.org/), einem minimalistischen
1980
+ Standard-Interface für Ruby-Webframeworks. Eines der interessantesten Features
1981
+ für Entwickler ist der Support von Middlewares, die zwischen den Server und
1982
+ die Anwendung geschaltet werden und so HTTP-Request und/oder Antwort
1983
+ überwachen und/oder manipulieren können.
1984
+
1985
+ Sinatra macht das Erstellen von Middleware-Verkettungen mit der
1986
+ Top-Level-Methode `use` zu einem Kinderspiel:
1987
+
1988
+ ```ruby
1989
+ require 'sinatra'
1990
+ require 'meine_middleware'
1991
+
1992
+ use Rack::Lint
1993
+ use MeineMiddleware
1994
+
1995
+ get '/hallo' do
1996
+ 'Hallo Welt'
1997
+ end
1998
+ ```
1999
+
2000
+ Die Semantik von `use` entspricht der gleichnamigen Methode der
2001
+ [Rack::Builder](http://rack.rubyforge.org/doc/classes/Rack/Builder.html)-DSL
2002
+ (meist verwendet in Rackup-Dateien). Ein Beispiel dafür ist, dass die
2003
+ `use`-Methode mehrere/verschiedene Argumente und auch Blöcke entgegennimmt:
2004
+
2005
+ ```ruby
2006
+ use Rack::Auth::Basic do |username, password|
2007
+ username == 'admin' && password == 'geheim'
2008
+ end
2009
+ ```
2010
+
2011
+ Rack bietet eine Vielzahl von Standard-Middlewares für Logging, Debugging,
2012
+ URL-Routing, Authentifizierung und Session-Verarbeitung. Sinatra verwendet
2013
+ viele von diesen Komponenten automatisch, abhängig von der Konfiguration. So
2014
+ muss `use` häufig nicht explizit verwendet werden.
2015
+
2016
+ Hilfreiche Middleware gibt es z.B. hier:
2017
+ [rack](https://github.com/rack/rack/tree/master/lib/rack),
2018
+ [rack-contrib](https://github.com/rack/rack-contrib#readme), mit
2019
+ [CodeRack](http://coderack.org/) oder im [Rack
2020
+ wiki](https://github.com/rack/rack/wiki/List-of-Middleware).
2021
+
2022
+ ## Testen
2023
+
2024
+ Sinatra-Tests können mit jedem auf Rack aufbauendem Test-Framework geschrieben
2025
+ werden. [Rack::Test](http://rdoc.info/github/brynary/rack-test/master/frames)
2026
+ wird empfohlen:
2027
+
2028
+ ```ruby
2029
+ require 'my_sinatra_app'
2030
+ require 'test/unit'
2031
+ require 'rack/test'
2032
+
2033
+ class MyAppTest < Test::Unit::TestCase
2034
+ include Rack::Test::Methods
2035
+
2036
+ def app
2037
+ Sinatra::Application
2038
+ end
2039
+
2040
+ def test_my_default
2041
+ get '/'
2042
+ assert_equal 'Hallo Welt!', last_response.body
2043
+ end
2044
+
2045
+ def test_with_params
2046
+ get '/meet', :name => 'Frank'
2047
+ assert_equal 'Hallo Frank!', last_response.body
2048
+ end
2049
+
2050
+ def test_with_rack_env
2051
+ get '/', {}, 'HTTP_USER_AGENT' => 'Songbird'
2052
+ assert_equal "Du verwendest Songbird!", last_response.body
2053
+ end
2054
+ end
2055
+ ```
2056
+
2057
+ ## Sinatra::Base - Middleware, Bibliotheken und modulare Anwendungen
2058
+
2059
+ Das Definieren einer Top-Level-Anwendung funktioniert gut für
2060
+ Mikro-Anwendungen, hat aber Nachteile, wenn wiederverwendbare Komponenten wie
2061
+ Middleware, Rails Metal, einfache Bibliotheken mit Server-Komponenten oder
2062
+ auch Sinatra-Erweiterungen geschrieben werden sollen.
2063
+
2064
+ Das Top-Level geht von einer Konfiguration für eine Mikro-Anwendung aus (wie
2065
+ sie z.B. bei einer einzelnen Anwendungsdatei, `./public` und `./views` Ordner,
2066
+ Logging, Exception-Detail-Seite, usw.). Genau hier kommt `Sinatra::Base` ins
2067
+ Spiel:
2068
+
2069
+ ```ruby
2070
+ require 'sinatra/base'
2071
+
2072
+ class MyApp < Sinatra::Base
2073
+ set :sessions, true
2074
+ set :foo, 'bar'
2075
+
2076
+ get '/' do
2077
+ 'Hallo Welt!'
2078
+ end
2079
+ end
2080
+ ```
2081
+
2082
+ Die MyApp-Klasse ist eine unabhängige Rack-Komponente, die als Middleware,
2083
+ Endpunkt oder via Rails Metal verwendet werden kann. Verwendet wird sie durch
2084
+ `use` oder `run` von einer Rackup-`config.ru`-Datei oder als Server-Komponente
2085
+ einer Bibliothek:
2086
+
2087
+ ```ruby
2088
+ MyApp.run! :host => 'localhost', :port => 9090
2089
+ ```
2090
+
2091
+ Die Methoden der `Sinatra::Base`-Subklasse sind genau dieselben wie die der
2092
+ Top-Level-DSL. Die meisten Top-Level-Anwendungen können mit nur zwei
2093
+ Veränderungen zu `Sinatra::Base` konvertiert werden:
2094
+
2095
+ * Die Datei sollte `require 'sinatra/base'` anstelle von `require
2096
+ 'sinatra/base'` aufrufen, ansonsten werden alle von Sinatras DSL-Methoden
2097
+ in den Top-Level-Namespace importiert.
2098
+ * Alle Routen, Error-Handler, Filter und Optionen der Applikation müssen in
2099
+ einer Subklasse von `Sinatra::Base` definiert werden.
2100
+
2101
+
2102
+ `Sinatra::Base` ist ein unbeschriebenes Blatt. Die meisten Optionen sind per
2103
+ Standard deaktiviert. Das betrifft auch den eingebauten Server. Siehe
2104
+ [Optionen und Konfiguration](http://sinatra.github.com/configuration.html) für
2105
+ Details über mögliche Optionen.
2106
+
2107
+ ### Modularer vs. klassischer Stil
2108
+
2109
+ Entgegen häufiger Meinungen gibt es nichts gegen den klassischen Stil
2110
+ einzuwenden. Solange es die Applikation nicht beeinträchtigt, besteht kein
2111
+ Grund, eine modulare Applikation zu erstellen.
2112
+
2113
+ Der größte Nachteil der klassischen Sinatra Anwendung gegenüber einer
2114
+ modularen ist die Einschränkung auf eine Sinatra Anwendung pro Ruby-Prozess.
2115
+ Sollen mehrere zum Einsatz kommen, muss auf den modularen Stil umgestiegen
2116
+ werden. Dabei ist es kein Problem klassische und modulare Anwendungen
2117
+ miteinander zu vermischen.
2118
+
2119
+ Bei einem Umstieg, sollten einige Unterschiede in den Einstellungen beachtet
2120
+ werden:
2121
+
2122
+ ```
2123
+ Szenario Classic Modular
2124
+ ---------------------------------------------------
2125
+
2126
+ app_file sinatra ladende Datei Sinatra::Base subklassierende Datei
2127
+ run $0 == app_file false
2128
+ logging true false
2129
+ method_override true false
2130
+ inline_templates true false
2131
+ ```
2132
+
2133
+ ### Eine modulare Applikation bereitstellen
2134
+
2135
+ Es gibt zwei übliche Wege, eine modulare Anwendung zu starten. Zum einen über
2136
+ `run!`:
2137
+
2138
+ ```ruby
2139
+ # mein_app.rb
2140
+ require 'sinatra/base'
2141
+
2142
+ class MeinApp < Sinatra::Base
2143
+ # ... Anwendungscode hierhin ...
2144
+
2145
+ # starte den Server, wenn die Ruby-Datei direkt ausgeführt wird
2146
+ run! if app_file == $0
2147
+ end
2148
+ ```
2149
+
2150
+ Starte mit:
2151
+
2152
+ ```
2153
+ ruby mein_app.rb
2154
+ ```
2155
+
2156
+ Oder über eine `config.ru`-Datei, die es erlaubt, einen beliebigen
2157
+ Rack-Handler zu verwenden:
2158
+
2159
+ ```ruby
2160
+ # config.ru
2161
+ require './mein_app'
2162
+ run MeineApp
2163
+ ```
2164
+
2165
+ Starte:
2166
+
2167
+ ```
2168
+ rackup -p 4567
2169
+ ```
2170
+
2171
+ ### Eine klassische Anwendung mit einer config.ru verwenden
2172
+
2173
+ Schreibe eine Anwendungsdatei:
2174
+
2175
+ ```ruby
2176
+ # app.rb
2177
+ require 'sinatra'
2178
+
2179
+ get '/' do
2180
+ 'Hallo Welt!'
2181
+ end
2182
+ ```
2183
+
2184
+ sowie eine dazugehörige `config.ru`-Datei:
2185
+
2186
+ ```ruby
2187
+ require './app'
2188
+ run Sinatra::Application
2189
+ ```
2190
+
2191
+ ### Wann sollte eine config.ru-Datei verwendet werden?
2192
+
2193
+ Anzeichen dafür, dass eine `config.ru`-Datei gebraucht wird:
2194
+
2195
+ * Es soll ein anderer Rack-Handler verwendet werden (Passenger, Unicorn,
2196
+ Heroku, ...).
2197
+ * Es gibt mehr als nur eine Subklasse von `Sinatra::Base`.
2198
+ * Sinatra soll als Middleware verwendet werden, nicht als Endpunkt.
2199
+
2200
+
2201
+ **Es gibt keinen Grund, eine `config.ru`-Datei zu verwenden, nur weil eine
2202
+ Anwendung im modularen Stil betrieben werden soll. Ebenso wird keine Anwendung
2203
+ mit modularem Stil benötigt, um eine `config.ru`-Datei zu verwenden.**
2204
+
2205
+ ### Sinatra als Middleware nutzen
2206
+
2207
+ Es ist nicht nur möglich, andere Rack-Middleware mit Sinatra zu nutzen, es
2208
+ kann außerdem jede Sinatra-Anwendung selbst als Middleware vor jeden
2209
+ beliebigen Rack-Endpunkt gehangen werden. Bei diesem Endpunkt muss es sich
2210
+ nicht um eine andere Sinatra-Anwendung handeln, es kann jede andere
2211
+ Rack-Anwendung sein (Rails/Ramaze/Camping/...):
2212
+
2213
+ ```ruby
2214
+ require 'sinatra/base'
2215
+
2216
+ class LoginScreen < Sinatra::Base
2217
+ enable :sessions
2218
+
2219
+ get('/login') { haml :login }
2220
+
2221
+ post('/login') do
2222
+ if params[:name] == 'admin' && params[:password] == 'admin'
2223
+ session['user_name'] = params[:name]
2224
+ else
2225
+ redirect '/login'
2226
+ end
2227
+ end
2228
+ end
2229
+
2230
+ class MyApp < Sinatra::Base
2231
+ # Middleware wird vor Filtern ausgeführt
2232
+ use LoginScreen
2233
+
2234
+ before do
2235
+ unless session['user_name']
2236
+ halt "Zugriff verweigert, bitte <a href='/login'>einloggen</a>."
2237
+ end
2238
+ end
2239
+
2240
+ get('/') { "Hallo #{session['user_name']}." }
2241
+ end
2242
+ ```
2243
+
2244
+ ### Dynamische Applikationserstellung
2245
+
2246
+ Manche Situationen erfordern die Erstellung neuer Applikationen zur Laufzeit,
2247
+ ohne dass sie einer Konstanten zugeordnet werden. Dies lässt sich mit
2248
+ `Sinatra.new` erreichen:
2249
+
2250
+ ```ruby
2251
+ require 'sinatra/base'
2252
+ my_app = Sinatra.new { get('/') { "hallo" } }
2253
+ my_app.run!
2254
+ ```
2255
+
2256
+ Die Applikation kann mit Hilfe eines optionalen Parameters erstellt werden:
2257
+
2258
+ ```ruby
2259
+ # config.ru
2260
+ require 'sinatra/base'
2261
+
2262
+ controller = Sinatra.new do
2263
+ enable :logging
2264
+ helpers MyHelpers
2265
+ end
2266
+
2267
+ map('/a') do
2268
+ run Sinatra.new(controller) { get('/') { 'a' } }
2269
+ end
2270
+
2271
+ map('/b') do
2272
+ run Sinatra.new(controller) { get('/') { 'b' } }
2273
+ end
2274
+ ```
2275
+
2276
+ Das ist besonders dann interessant, wenn Sinatra-Erweiterungen getestet werden
2277
+ oder Sinatra in einer Bibliothek Verwendung findet.
2278
+
2279
+ Ebenso lassen sich damit hervorragend Sinatra-Middlewares erstellen:
2280
+
2281
+ ```ruby
2282
+ require 'sinatra/base'
2283
+
2284
+ use Sinatra do
2285
+ get('/') { ... }
2286
+ end
2287
+
2288
+ run RailsProject::Application
2289
+ ```
2290
+
2291
+ ## Geltungsbereich und Bindung
2292
+
2293
+ Der Geltungsbereich (Scope) legt fest, welche Methoden und Variablen zur
2294
+ Verfügung stehen.
2295
+
2296
+ ### Anwendungs- oder Klassen-Scope
2297
+
2298
+ Jede Sinatra-Anwendung entspricht einer `Sinatra::Base`-Subklasse. Falls die
2299
+ Top- Level-DSL verwendet wird (`require 'sinatra'`), handelt es sich um
2300
+ `Sinatra::Application`, andernfalls ist es jene Subklasse, die explizit
2301
+ angelegt wurde. Auf Klassenebene stehen Methoden wie `get` oder `before` zur
2302
+ Verfügung, es gibt aber keinen Zugriff auf das `request`-Object oder die
2303
+ `session`, da nur eine einzige Klasse für alle eingehenden Anfragen genutzt
2304
+ wird.
2305
+
2306
+ Optionen, die via `set` gesetzt werden, sind Methoden auf Klassenebene:
2307
+
2308
+ ```ruby
2309
+ class MyApp < Sinatra::Base
2310
+ # Hey, ich bin im Anwendungsscope!
2311
+ set :foo, 42
2312
+ foo # => 42
2313
+
2314
+ get '/foo' do
2315
+ # Hey, ich bin nicht mehr im Anwendungs-Scope!
2316
+ end
2317
+ end
2318
+ ```
2319
+
2320
+ Im Anwendungs-Scope befindet man sich:
2321
+
2322
+ * In der Anwendungs-Klasse.
2323
+ * In Methoden, die von Erweiterungen definiert werden.
2324
+ * Im Block, der an `helpers` übergeben wird.
2325
+ * In Procs und Blöcken, die an `set` übergeben werden.
2326
+ * Der an `Sinatra.new` übergebene Block
2327
+
2328
+
2329
+ Auf das Scope-Objekt (die Klasse) kann wie folgt zugegriffen werden:
2330
+
2331
+ * Über das Objekt, das an den `configure`-Block übergeben wird (`configure {
2332
+ |c| ... }`).
2333
+ * `settings` aus den anderen Scopes heraus.
2334
+
2335
+
2336
+ ### Anfrage- oder Instanz-Scope
2337
+
2338
+ Für jede eingehende Anfrage wird eine neue Instanz der Anwendungs-Klasse
2339
+ erstellt und alle Handler in diesem Scope ausgeführt. Aus diesem Scope heraus
2340
+ kann auf `request` oder `session` zugegriffen und Methoden wie `erb` oder
2341
+ `haml` aufgerufen werden. Außerdem kann mit der `settings`-Method auf den
2342
+ Anwendungs-Scope zugegriffen werden:
2343
+
2344
+ ```ruby
2345
+ class MyApp < Sinatra::Base
2346
+ # Hey, ich bin im Anwendungs-Scope!
2347
+ get '/neue_route/:name' do
2348
+ # Anfrage-Scope für '/neue_route/:name'
2349
+ @value = 42
2350
+
2351
+ settings.get "/#{params[:name]}" do
2352
+ # Anfrage-Scope für "/#{params[:name]}"
2353
+ @value # => nil (nicht dieselbe Anfrage)
2354
+ end
2355
+
2356
+ "Route definiert!"
2357
+ end
2358
+ end
2359
+ ```
2360
+
2361
+ Im Anfrage-Scope befindet man sich:
2362
+
2363
+ * In get/head/post/put/delete-Blöcken
2364
+ * In before/after-Filtern
2365
+ * In Helfer-Methoden
2366
+ * In Templates
2367
+
2368
+
2369
+ ### Delegation-Scope
2370
+
2371
+ Vom Delegation-Scope aus werden Methoden einfach an den Klassen-Scope
2372
+ weitergeleitet. Dieser verhält sich jedoch nicht 100%ig wie der Klassen-Scope,
2373
+ da man nicht die Bindung der Klasse besitzt: Nur Methoden, die explizit als
2374
+ delegierbar markiert wurden, stehen hier zur Verfügung und es kann nicht auf
2375
+ die Variablen des Klassenscopes zugegriffen werden (mit anderen Worten: es
2376
+ gibt ein anderes `self`). Weitere Delegationen können mit
2377
+ `Sinatra::Delegator.delegate :methoden_name` hinzugefügt werden.
2378
+
2379
+ Im Delegation-Scop befindet man sich:
2380
+
2381
+ * Im Top-Level, wenn `require 'sinatra'` aufgerufen wurde.
2382
+ * In einem Objekt, das mit dem `Sinatra::Delegator`-Mixin erweitert wurde.
2383
+
2384
+
2385
+ Schau am besten im Code nach: Hier ist [Sinatra::Delegator
2386
+ mixin](http://github.com/sinatra/sinatra/blob/master/lib/sinatra/base.rb#L1064
2387
+ ) definiert und wird in den [globalen Namespace
2388
+ eingebunden](http://github.com/sinatra/sinatra/blob/master/lib/sinatra/main.rb
2389
+
2390
+ ## Kommandozeile
2391
+
2392
+ Sinatra-Anwendungen können direkt von der Kommandozeile aus gestartet werden:
2393
+
2394
+ ```
2395
+ ruby myapp.rb [-h] [-x] [-e ENVIRONMENT] [-p PORT] [-h HOST] [-s HANDLER]
2396
+ ```
2397
+
2398
+ Die Optionen sind:
2399
+
2400
+ ```
2401
+ -h # Hilfe
2402
+ -p # Port setzen (Standard ist 4567)
2403
+ -h # Host setzen (Standard ist 0.0.0.0)
2404
+ -e # Umgebung setzen (Standard ist development)
2405
+ -s # Rack-Server/Handler setzen (Standard ist thin)
2406
+ -x # Mutex-Lock einschalten (Standard ist off)
2407
+ ```
2408
+
2409
+ ## Systemanforderungen
2410
+
2411
+ Die folgenden Versionen werden offiziell unterstützt:
2412
+
2413
+ <dl>
2414
+ <dt>Ruby 1.8.7</dt>
2415
+ <dd>1.8.7 wird vollständig unterstützt, aber solange nichts dagegen spricht,
2416
+ wird ein Update auf 1.9.2 oder ein Umstieg auf JRuby/Rubinius empfohlen.
2417
+ Unterstützung für 1.8.7 wird es mindestens bis Sinatra 2.0 und Ruby 2.0
2418
+ geben, es sei denn, dass der unwahrscheinliche Fall eintritt und 1.8.8
2419
+ rauskommt. Doch selbst dann ist es eher wahrscheinlich, dass 1.8.7 weiterhin
2420
+ unterstützt wird. <b>Ruby 1.8.6 wird nicht mehr unterstützt.</b> Soll Sinatra
2421
+ unter 1.8.6 eingesetzt werden, muss Sinatra 1.2 verwendet werden, dass noch
2422
+ bis zum Release von Sinatra 1.4.0 fortgeführt wird.</dd>
2423
+
2424
+ <dt>Ruby 1.9.2</dt>
2425
+ <dd>1.9.2 wird voll unterstützt und empfohlen. Version 1.9.2p0 sollte nicht
2426
+ verwendet werden, da unter Sinatra immer wieder Segfaults auftreten.
2427
+ Unterstützung wird es mindestens bis zum Release von Ruby 1.9.4/2.0 geben und
2428
+ das letzte Sinatra Release für 1.9 wird so lange unterstützt, wie das Ruby
2429
+ Core-Team 1.9 pflegt.</dd>
2430
+
2431
+ <dt>Ruby 1.9.3</dt>
2432
+ <dd>1.9.3 wird vollständig unterstützt und empfohlen. Achtung, bei einem
2433
+ Wechsel zu 1.9.3 werden alle Sessions ungültig.</dd>
2434
+
2435
+ <dt>Rubinius</dt>
2436
+ <dd>Rubinius (rbx >= 1.2.4) wird offiziell unter Einbezug aller Templates
2437
+ unterstützt. Die kommende 2.0 Version wird ebenfalls unterstützt, samt 1.9
2438
+ Modus.</dd>
2439
+
2440
+ <dt>JRuby</dt>
2441
+ <dd>JRuby wird offiziell unterstützt (JRuby >= 1.6.7). Probleme mit
2442
+ Template- Bibliotheken Dritter sind nicht bekannt. Falls JRuby zum Einsatz
2443
+ kommt, sollte aber darauf geachtet werden, dass ein JRuby-Rack-Handler zum
2444
+ Einsatz kommt – die Thin und Mongrel Web-Server werden bisher nicht
2445
+ unterstütz. JRubys Unterstützung für C-Erweiterungen sind zur Zeit ebenfalls
2446
+ experimenteller Natur, betrifft im Moment aber nur die RDiscount, Redcarpet,
2447
+ RedCloth und Yajl Templates.</dd>
2448
+ </dl>
2449
+
2450
+ Weiterhin werden wir die kommende Ruby-Versionen im Auge behalten.
2451
+
2452
+ Die nachfolgend aufgeführten Ruby-Implementierungen werden offiziell nicht von
2453
+ Sinatra unterstützt, funktionieren aber normalerweise:
2454
+
2455
+ * Ruby Enterprise Edition
2456
+ * Ältere Versionen von JRuby und Rubinius
2457
+ * MacRuby, Maglev, IronRuby
2458
+ * Ruby 1.9.0 und 1.9.1 (wird jedoch nicht empfohlen, s.o.)
2459
+
2460
+
2461
+ Nicht offiziell unterstützt bedeutet, dass wenn Sachen nicht funktionieren,
2462
+ wir davon ausgehen, dass es nicht an Sinatra sondern an der jeweiligen
2463
+ Implentierung liegt.
2464
+
2465
+ Im Rahmen unserer CI (Kontinuierlichen Integration) wird bereits ruby-head
2466
+ (das kommende Ruby 2.0.0) und 1.9.4 mit eingebunden. Da noch alles im Fluss
2467
+ ist, kann zur Zeit für nichts garantiert werden. Es kann aber erwartet werden,
2468
+ dass Ruby 2.0.0p0 und 1.9.4p0 von Sinatra unterstützt werden wird.
2469
+
2470
+ Sinatra sollte auf jedem Betriebssystem laufen, dass den gewählten Ruby-
2471
+ Interpreter unterstützt.
2472
+
2473
+ Sinatra wird aktuell nicht unter Cardinal, SmallRuby, BleuRuby oder
2474
+ irgendeiner Version von Ruby vor 1.8.7 laufen.
2475
+
2476
+ ## Der neuste Stand (The Bleeding Edge)
2477
+
2478
+ Um auf dem neusten Stand zu bleiben, kann der Master-Branch verwendet werden.
2479
+ Er sollte recht stabil sein. Ebenso gibt es von Zeit zu Zeit prerelease Gems,
2480
+ die so installiert werden:
2481
+
2482
+ ```
2483
+ gem install sinatra --pre
2484
+ ```
2485
+
2486
+ ### Mit Bundler
2487
+
2488
+ Wenn die Applikation mit der neuesten Version von Sinatra und
2489
+ [Bundler](http://gembundler.com/) genutzt werden soll, empfehlen wir den
2490
+ nachfolgenden Weg.
2491
+
2492
+ Soweit Bundler noch nicht installiert ist:
2493
+
2494
+ ```
2495
+ gem install bundler
2496
+ ```
2497
+
2498
+ Anschließend wird eine `Gemfile`-Datei im Projektverzeichnis mit folgendem
2499
+ Inhalt erstellt:
2500
+
2501
+ ```ruby
2502
+ source :rubygems
2503
+ gem 'sinatra', :git => "git://github.com/sinatra/sinatra.git"
2504
+
2505
+ # evtl. andere Abhängigkeiten
2506
+ gem 'haml' # z.B. wenn du Haml verwendest...
2507
+ gem 'activerecord', '~> 3.0' # ...oder ActiveRecord 3.x
2508
+ ```
2509
+
2510
+ Beachte: Hier sollten alle Abhängigkeiten eingetragen werden. Sinatras eigene,
2511
+ direkte Abhängigkeiten (Tilt und Rack) werden von Bundler automatisch aus dem
2512
+ Gemfile von Sinatra hinzugefügt.
2513
+
2514
+ Jetzt kannst du deine Applikation starten:
2515
+
2516
+ ```
2517
+ bundle exec ruby myapp.rb
2518
+ ```
2519
+
2520
+ ### Eigenes Repository
2521
+ Um auf dem neuesten Stand von Sinatras Code zu sein, kann eine lokale Kopie
2522
+ angelegt werden. Gestartet wird in der Anwendung mit dem `sinatra/lib`- Ordner
2523
+ im `LOAD_PATH`:
2524
+
2525
+ ```
2526
+ cd myapp
2527
+ git clone git://github.com/sinatra/sinatra.git
2528
+ ruby -Isinatra/lib myapp.rb
2529
+ ```
2530
+
2531
+ Alternativ kann der `sinatra/lib`-Ordner zum `LOAD_PATH` in der Anwendung
2532
+ hinzugefügt werden:
2533
+
2534
+ ```ruby
2535
+ $LOAD_PATH.unshift File.dirname(__FILE__) + '/sinatra/lib'
2536
+ require 'rubygems'
2537
+ require 'sinatra'
2538
+
2539
+ get '/ueber' do
2540
+ "Ich laufe auf Version " + Sinatra::VERSION
2541
+ end
2542
+ ```
2543
+
2544
+ Um Sinatra-Code von Zeit zu Zeit zu aktualisieren:
2545
+
2546
+ ```
2547
+ cd myproject/sinatra
2548
+ git pull
2549
+ ```
2550
+
2551
+ ### Gem erstellen
2552
+
2553
+ Aus der eigenen lokalen Kopie kann nun auch ein globales Gem gebaut werden:
2554
+
2555
+ ```
2556
+ git clone git://github.com/sinatra/sinatra.git
2557
+ cd sinatra
2558
+ rake sinatra.gemspec
2559
+ rake install
2560
+ ```
2561
+
2562
+ Falls Gems als Root installiert werden sollen, sollte die letzte Zeile
2563
+ folgendermaßen lauten:
2564
+
2565
+ ```
2566
+ sudo rake install
2567
+ ```
2568
+
2569
+ ## Versions-Verfahren
2570
+
2571
+ Sinatra folgt dem sogenannten [Semantic Versioning](http://semver.org/), d.h.
2572
+ SemVer und SemVerTag.
2573
+
2574
+ ## Mehr
2575
+
2576
+ * [Projekt-Website](http://sinatra.github.com/) - Ergänzende Dokumentation,
2577
+ News und Links zu anderen Ressourcen.
2578
+ * [Mitmachen](http://sinatra.github.com/contributing.html) - Einen Fehler
2579
+ gefunden? Brauchst du Hilfe? Hast du einen Patch?
2580
+ * [Issue-Tracker](http://github.com/sinatra/sinatra/issues)
2581
+ * [Twitter](http://twitter.com/sinatra)
2582
+ * [Mailing-Liste](http://groups.google.com/group/sinatrarb)
2583
+ * [ #sinatra](irc://chat.freenode.net/#sinatra) auf http://freenode.net
2584
+ * [Sinatra Book](http://sinatra-book.gittr.com) Kochbuch Tutorial
2585
+ * [Sinatra Recipes](http://recipes.sinatrarb.com/) Sinatra-Rezepte aus der
2586
+ Community
2587
+ * API Dokumentation für die [aktuelle
2588
+ Version](http://rubydoc.info/gems/sinatra) oder für
2589
+ [HEAD](http://rubydoc.info/github/sinatra/sinatra) auf http://rubydoc.info
2590
+ * [CI Server](http://travis-ci.org/sinatra/sinatra)