Merge branch 'master' of github.com:sinatra/sinatra

README.de.rdoc

@@ -257,11 +257,90 @@ man die <tt>:static_cache_control</tt>-Einstellung (s.u.).
 
 == Views/Templates
 
-Standardmäßig wird davon ausgegangen, dass sich Templates im
-<tt>./views</tt>-Ordner befinden. Es kann jedoch ein anderer Ordner festgelegt
-werden:
+Alle Templatesprachen verwenden ihre eigene Renderingmethode, die jeweils
+einen String zurückgibt:
 
-  set :views, File.dirname(__FILE__) + '/templates'
+  get '/' do
+    erb :index
+  end
+
+Dieses Beispiel rendert <tt>views/index.erb</tt>.
+
+Anstelle eines Templatenamens kann man auch direkt die Templatesprache
+verwenden:
+
+  get '/' do
+    code = "<%= Time.now %>"
+    erb code
+  end
+
+Templates nehmen ein zweite Argument an, den Options-Hash:
+
+  get '/' do
+    erb :index, :layout => :post
+  end
+
+Dieses Beispiel rendert <tt>views/index.erb</tt> eingebettet in
+<tt>views/post.erb</tt> (Voreinstellung ist <tt>views/layout.erb</tt>, sofern
+es vorhanden ist.)
+
+Optionen, die Sinatra nicht versteht, werden an das Template weitergereicht:
+
+  get '/' do
+    haml :index, :format => :html5
+  end
+
+Für alle Templates können auch generelle Einstellungen festgelegt werden:
+
+  set :haml, :format => :html5
+
+  get '/' do
+    haml :index
+  end
+
+Optionen, die an die Rendermethode weitergegeben werden, überschreiben die
+Einstellungen, die mit +set+ festgelegt wurden.
+
+Mögliche Einstellungen:
+
+[locals]
+  Liste von lokalen Variablen, die and das Dokument weitergegeben werden.
+  Praktisch für Partials.
+  Beispiel: <tt>erb "<%= foo %>", :locals => {:foo => "bar"}</tt>
+
+[default_encoding]
+  Gibt die Stringkodierung an, die verwendet werden soll. Voreingestellt auf
+  <tt>settings.default_encoding</tt>.
+
+[views]
+  Ordner, aus dem die Templates heraus geladen werden. Voreingestellt auf
+  <tt>settings.views</tt>.
+
+[layout]
+  Legt fest, ob ein Layouttemplate verwendet werden soll oder nicht (+true+
+  oder +false+). Ist es ein Symbol, dass legt es fest, welches Template als
+  Layout verwendet wird. Beispiel:
+   <tt>erb :index, :layout => !request.xhr?</tt>
+
+[content_type]
+  Content-Type den das Template ausgibt. Voreinstellung hängt von der
+  Templatesprache ab.
+
+[scope]
+  Scope, in dem das Template gerendert wird. Liegt standardmäßig innerhalb der
+  App-Instanz. Wird Scope geändert, sind Instanzvariablen und Helfermethoden
+  nicht verfügbar.
+
+[layout_engine]
+  Legt fest, welcher Renderer für das Layout verantwortlich ist.
+  Hilfreich für Sprachen, die sonst keine Templates unterstützen.
+  Voreingestellt auf den Renderer, der für das Template verwendet wird.
+  Beispiel: <tt>set :rdoc, :layout_engine => :erb</tt>
+
+Sinatra geht davon aus, dass die Templates sich im <tt>./views</tt> Verzeichnis
+befinden. Es kann jedoch ein anderer Ordner festgelegt werden:
+
+  set :views, settings.root + '/templates'
 
 Es ist zu beachten, dass immer mit Symbolen auf Templates verwiesen werden
 muss, auch dann, wenn sie sich in einem Unterordner befinden:
@@ -357,7 +436,7 @@ Beachte, dass man die +markdown+-Methode auch aus anderen Templates heraus
 aufrufen kann:
 
   %h1 Gruß von Haml!
-  %p= markdown(:Grüsse)
+  %p= markdown(:Grüße)
 
 Da man Ruby nicht von Markdown heraus aufrufen kann, können auch Layouts nicht
 in Markdown geschrieben werden. Es ist aber möglich, einen Renderer für die
@@ -380,7 +459,7 @@ Beachte, dass man die +textile+-Methode auch aus anderen Templates heraus
 aufrufen kann:
 
   %h1 Gruß von Haml!
-  %p= textile(:Grüsse)
+  %p= textile(:Grüße)
 
 Da man Ruby nicht von Textile heraus aufrufen kann, können auch Layouts nicht
 in Textile geschrieben werden. Es ist aber möglich, einen Renderer für die
@@ -791,17 +870,19 @@ zurückschicken, bis er die Verbindung abbricht. Für diese Fälle gibt es die
     end
   end
 
-Damit lassen sich Streaming-APIs realisieren, sog. {Server Sent Events}[http://dev.w3.org/html5/eventsource/]
-die als Basis für {WebSockets}[http://en.wikipedia.org/wiki/WebSocket] dienen.
-Ebenso können sie verwendet werden, um den Durchsatz zu erhöhen, wenn ein Teil
-der Daten von langsamen Ressourcen abhängig ist.
+Damit lassen sich Streaming-APIs realisieren, sog.
+{Server Sent Events}[http://dev.w3.org/html5/eventsource/] die als Basis für
+{WebSockets}[http://en.wikipedia.org/wiki/WebSocket] dienen. Ebenso können sie
+verwendet werden, um den Durchsatz zu erhöhen, wenn ein Teil der Daten von
+langsamen Ressourcen abhängig ist.
 
 Es ist zu beachten, dass das Verhalten beim Streaming, insbesondere die Anzahl
 nebenläufiger Anfragen, stark davon abhängt, welcher Webserver für die
 Applikation verwendet wird. Einige Server, z.B. WEBRick, unterstützen Streaming
 nicht oder nur teilweise. Sollte der Server Streaming nicht unterstützen, wird
 ein vollständiger Response-Body zurückgeschickt, sobald der an +stream+
-weitergegebene Block abgearbeitet ist.
+weitergegebene Block abgearbeitet ist. Mit Shotgun funktioniert Streaming z.B.
+überhaupt nicht.
 
 Ist der optionale Parameter +keep_open+ aktiviert, wird beim gestreamten Objekt
 +close+ nicht aufgerufen und es ist einem überlassen dies an einem beliebigen
@@ -842,11 +923,17 @@ voreingestellt ist. Wird über <tt>Sinatra::Base</tt> vererbt, muss es erst
 aktiviert werden:
 
   class MyApp < Sinatra::Base
-    configure(:production, :development) do
+    configure :production, :development  do
       enable :logging
     end
   end
 
+Damit auch keine Middleware das Logging aktivieren kann, muss die +logging+
+Einstellung auf +nil+ gesetzt werden. Das heißt aber auch, dass +logger+ in
+diesem Fall +nil+ zurückgeben wird. Üblicherweise wird das eingesetzt, wenn ein
+eigener Logger eingerichtet werden soll. Sinatra wird dann verwenden, was in
+<tt>env['rack.logger']</tt> eingetragen ist.
+
 == Mime-Types
 
 Wenn <tt>send_file</tt> oder statische Dateien verwendet werden, kann es
@@ -982,6 +1069,25 @@ Cache-Lösungen bietet sich z.B.
 Um den <tt>Cache-Control</tt>-Header mit Informationen zu versorgen, verwendet
 man die <tt>:static_cache_control</tt>-Einstellung (s.u.).
 
+Nach RFC 2616 sollte sich die Anwendung anders verhalten, wenn ein
+If-Match oder ein If-None_match Header auf <tt>*</tt> gesetzt wird in
+Abhängigkeit davon, ob die Resource bereits existiert. Sinatra geht
+davon aus, dass Ressourcen bei sicheren Anfragen (z.B. bei get oder Idempotenten
+Anfragen wie put) bereits existieren, wobei anderen Ressourcen
+(besipielsweise bei post), als neue Ressourcen behandelt werden. Dieses
+Verhalten lässt sich mit der <tt>:new_resource</tt> Option ändern:
+
+  get '/create' do
+    etag '', :new_resource => true
+    Article.create
+    erb :new_article
+  end
+
+Soll das schwache ETag trotzdem verwendet werden, verwendet man die
+<tt>:kind</tt> Option:
+
+  etag '', :new_resource => true, :kind => :weak
+
 === Dateien versenden
 
 Zum Versenden von Dateien kann die <tt>send_file</tt>-Helfer-Methode verwendet
@@ -1228,7 +1334,7 @@ einen Hash mit Optionen hinzu:
 Neben Strings akzeptiert <tt>:except</tt> auch Arrays, um gleich mehrere
 Schutzmechanismen zu deaktivieren:
 
-  set :protections, :except => [:path_traversal, :session_hijacking]
+  set :protection, :except => [:path_traversal, :session_hijacking]
 
 === Mögliche Einstellungen
 
@@ -1246,7 +1352,6 @@ Schutzmechanismen zu deaktivieren:
 
                         Standardmäßig nicht aktiviert.
 
-
 [add_charsets]          Mime-Types werden hier automatisch der Helfer-Methode
                         <tt>content_type</tt> zugeordnet.
 
@@ -1255,9 +1360,9 @@ Schutzmechanismen zu deaktivieren:
 
                           settings.add_charsets << "application/foobar"
 
-[app_file]              Hauptdatei der Applikation. Wird verwendet, um das
-                        Wurzel-, Inline-, View- und öffentliche Verzeichnis des
-                        Projekts festzustellen.
+[app_file]              Pfad zur Hauptdatei der Applikation. Wird verwendet, um
+                        das Wurzel-, Inline-, View- und öffentliche Verzeichnis
+                        des Projekts festzustellen.
 
 [bind]                  IP-Address, an die gebunden wird
                         (Standardwert: 0.0.0.0). Wird nur für den eingebauten
@@ -1300,14 +1405,21 @@ Schutzmechanismen zu deaktivieren:
                         Abschnitt.
 
 [public_folder]         Das öffentliche Verzeichnis, aus dem Daten zur
-                        Verfügung gestellt werden können.
+                        Verfügung gestellt werden können. Wird nur dann
+                        verwendet, wenn statische Daten zur Verfügung
+                        gestellt werden können (s.u. <tt>static</tt>
+                        Option). Leitet sich von der <tt>app_file</tt>
+                        Einstellung ab, wenn nicht gesetzt.
 
 [reload_templates]      Im development-Modus aktiviert.
 
-[root]                  Wurzelverzeichnis des Projekts.
+[root]                  Wurzelverzeichnis des Projekts. Leitet sich von der
+                        <tt>app_file</tt> Einstellung ab, wenn nicht gesetzt.
 
 [raise_errors]          Einen Ausnahmezustand aufrufen. Beendet die
-                        Applikation.
+                        Applikation. Ist automatisch aktiviert, wenn die
+                        Umgebung auf <tt>"test"</tt> eingestellt ist.
+                        Ansonsten ist diese Option deaktiviert.
 
 [run]                   Wenn aktiviert, wird Sinatra versuchen, den Webserver
                         zu starten. Nicht verwenden, wenn Rackup oder anderes
@@ -1321,9 +1433,16 @@ Schutzmechanismen zu deaktivieren:
                         Standardmäßig auf ['thin', 'mongrel', 'webrick']
                         voreingestellt. Die Anordnung gibt die Priorität vor.
 
-[sessions]              Sessions auf Cookiebasis aktivieren.
+[sessions]              Sessions auf Cookiebasis mittels
+                        <tt>Rack::Session::Cookie</tt>aktivieren. Für
+                        weitere Infos bitte in der Sektion 'Sessions
+                        verwenden' nachschauen.
+
+[show_exceptions]       Bei Fehlern einen Stacktrace im Browseranzeigen. Ist
+                        automatisch aktiviert, wenn die Umgebung auf
+                        <tt>"development"</tt> eingestellt ist. Ansonsten ist
+                        diese Option deaktiviert.
 
-[show_exceptions]       Stacktrace im Browser bei Fehlern anzeigen.
 
 [static]                Entscheidet, ob Sinatra statische Dateien zur Verfügung
                         stellen soll oder nicht.
@@ -1341,7 +1460,26 @@ Schutzmechanismen zu deaktivieren:
                         zu übergeben:
                         <tt>set :static_cache_control, [:public, :max_age => 300]</tt>
 
-[views]                 Verzeichnis der Views.
+[views]                 Verzeichnis der Views. Leitet sich von der
+                        <tt>app_file</tt> Einstellung ab, wenn nicht gesetzt.
+
+== Umgebungen
+
+Es gibt drei voreingestellte Umgebungen in Sinatra: <tt>"development"</tt>,
+<tt>"production"</tt> und <tt>"test"</tt>. Umgebungen können über die
++RACK_ENV+ Umgebungsvariable gesetzt werden. Die Standardeinstellung ist
+<tt>"development"</tt>. In diesem Modus werden alle Templates zwischen
+Requests neu geladen. Dazu gibt es besondere Fehlerseiten für 404 Stati
+und Fehlermeldungen. In <tt>"production"</tt> und <tt>"test"</tt> werden
+Templates automatisch gecached.
+
+Um die Anwendung in einer anderen Umgebung auszuführen kann man die
+<tt>-e</tt> Option verwenden:
+
+  ruby my_app.rb -e [ENVIRONMENT]
+
+In der Anwendung kann man die die Methoden  +development?+, +test?+ und
++production?+ verwenden, um die aktuelle Umgebung zu erfahren.
 
 == Fehlerbehandlung
 
@@ -1484,8 +1622,8 @@ Mikro-Anwendungen, hat aber Nachteile, wenn wiederverwendbare Komponenten wie
 Middleware, Rails Metal, einfache Bibliotheken mit Server-Komponenten oder auch
 Sinatra-Erweiterungen geschrieben werden sollen.
 
-Die Top-Level-DSL belastet den Objekt-Namespace und setzt einen
-Mikro-Anwendungsstil voraus (eine einzelne Anwendungsdatei, <tt>./public</tt>
+Das Top-Level geht von einer Konfiguration für eine Mikro-Anwendung aus
+(wie sie z.B. bei einer einzelnen Anwendungsdatei, <tt>./public</tt>
 und <tt>./views</tt> Ordner, Logging, Exception-Detail-Seite, usw.). Genau
 hier kommt <tt>Sinatra::Base</tt> ins Spiel:
 
@@ -1528,20 +1666,14 @@ Entgegen häufiger Meinungen gibt es nichts gegen den klassischen Stil
 einzuwenden. Solange es die Applikation nicht beeinträchtigt, besteht kein
 Grund, eine modulare Applikation zu erstellen.
 
-Lediglich zwei Nachteile gegenüber dem modularen Stil sollten beachtet werden:
+Der größte Nachteil der klassischen Sinatra Anwendung gegenüber einer modularen
+ist die Einschränkung auf eine Sinatra Anwendung pro Ruby-Prozess. Sollen
+mehrere zum Einsatz kommen, muss auf den modularen Stil umgestiegen werden.
+Dabei ist es kein Problem klassische und modulare Anwendungen miteinander zu
+vermischen.
 
-* Es kann nur eine Sinatra Applikation pro Ruby-Prozess laufen. Sollten mehrere
-  zum Einsatz kommen, muss auf den modularen Stil umgestiegen werden.
-  
-* Der klassische Stil füllt Object mit Delegations-Methoden. Sollte die
-  Applikation als Gem/Bibliothek zum Einsatz kommen, sollte auf den modularen
-  Stil umgestiegen werden.
-  
-Es gibt keinen Grund, warum modulare und klassische Elemente nicht
-vermischt werden sollten.
-
-Will man jedoch von einem Stil auf den anderen umsteigen, sollten einige
-Unterschiede beachtet werden:
+Bei einem Umstieg, sollten einige Unterschiede in den Einstellungen beachtet
+werden:
 
   Szenario            Classic                 Modular
 
@@ -1804,9 +1936,9 @@ Die folgenden Versionen werden offiziell unterstützt:
   1.8.7 wird vollständig unterstützt, aber solange nichts dagegen spricht,
   wird ein Update auf 1.9.2 oder ein Umstieg auf JRuby/Rubinius empfohlen.
   Unterstützung für 1.8.7 wird es mindestens bis Sinatra 2.0 und Ruby 2.0 geben,
-  es sei denn, dass der unwahrscheinliche Fall eintritt und 1.8.8 rauskommt. Doch
-  selbst dann ist es eher wahrscheinlich, dass 1.8.7 weiterhin unterstützt wird.
-  <b>Ruby 1.8.6 wird nicht mehr unterstützt.</b> Soll Sinatra unter 1.8.6 
+  es sei denn, dass der unwahrscheinliche Fall eintritt und 1.8.8 rauskommt.
+  Doch selbst dann ist es eher wahrscheinlich, dass 1.8.7 weiterhin unterstützt
+  wird. <b>Ruby 1.8.6 wird nicht mehr unterstützt.</b> Soll Sinatra unter 1.8.6
   eingesetzt werden, muss Sinatra 1.2 verwendet werden, dass noch bis zum
   Release von Sinatra 1.4.0 fortgeführt wird.
 
@@ -1819,21 +1951,25 @@ Die folgenden Versionen werden offiziell unterstützt:
   Core-Team 1.9 pflegt.
 
 [ Ruby 1.9.3 ]
+  1.9.3 wird vollständig unterstützt. Momentan wird empfohlen auf einen
+  höheren Pachtlevel zu warten, bevor Sinatra in der Produktion
+  eingesetzt wird (aktueller Patchlevel ist p0). Bei einem Wechsel zu
+  1.9.3 werden alle Sessions ungültig.
   Obwohl Tests bereits auf 1.9.3 laufen, sind bisher keine Applikationen auf
   1.9.3 in Produktion bekannt. Ebenso wie bei 1.9.2 besteht die gleiche Warnung 
   zum Patchlevel 0.
 
 [ Rubinius ]
   Rubinius (rbx >= 1.2.4) wird offiziell unter Einbezug aller Templates
-  unterstützt.
+  unterstützt. Die kommende 2.0 Version wird ebenfalls unterstützt.
 
 [ JRuby ]
-  JRuby wird offiziell unterstützt (JRuby >= 1.6.3). Probleme mit Template-
+  JRuby wird offiziell unterstützt (JRuby >= 1.6.5). Probleme mit Template-
   Bibliotheken Dritter sind nicht bekannt. Falls JRuby zum Einsatz kommt,
   sollte aber darauf geachtet werden, dass ein JRuby-Rack-Handler zum Einsatz
   kommt – der Thin-Web-Server wird bisher nicht unterstütz. JRubys
   Unterstützung für C-Erweiterungen sind zur Zeit noch experimenteller Natur,
-  betrifft im Moment aber nur RDiscount und Redcarpet.
+  betrifft im Moment aber nur RDiscount, Redcarpet und RedCloth.
 
 
 Weiterhin werden wir auf kommende Ruby-Versionen ein Auge haben.
@@ -1851,9 +1987,9 @@ wir davon ausgehen, dass es nicht an Sinatra sondern an der jeweiligen
 Implentierung liegt.
 
 Im Rahmen unserer CI (Kontinuierlichen Integration) wird bereits ruby-head
-(das kommende Ruby 1.9.4) mit eingebunden. Da noch alles im Fluss ist, kann zur
-Zeit für nichts garantiert werden. Es kann aber erwartet werden, dass Ruby 
-1.9.4p0 von Sinatra unterstützt werden wird.
+(das kommende Ruby 2.0.0) und 1.9.4 mit eingebunden. Da noch alles im Fluss ist,
+kann zur Zeit für nichts garantiert werden. Es kann aber erwartet werden, dass
+Ruby 2.0.0p0 und 1.9.4p0 von Sinatra unterstützt werden wird.
 
 Sinatra sollte auf jedem Betriebssystem laufen, dass den gewählten Ruby-
 Interpreter unterstützt.
@@ -1897,7 +2033,6 @@ Jetzt kannst du deine Applikation starten:
 
   bundle exec ruby myapp.rb
 
-  
 === Eigenes Repository
 Um auf dem neuesten Stand von Sinatras Code zu sein, kann eine lokale Kopie
 angelegt werden. Gestartet wird in der Anwendung mit dem <tt>sinatra/lib</tt>-
@@ -1959,3 +2094,4 @@ SemVer und SemVerTag.
   oder für {HEAD}[http://rubydoc.info/github/sinatra/sinatra] auf
   http://rubydoc.info
 * {CI Server}[http://ci.rkh.im/view/Sinatra/]
+

README.rdoc

@@ -559,7 +559,7 @@ Templates may be defined at the end of the source file:
     = yield
 
   @@ index
-  %div.title Hello world!!!!!
+  %div.title Hello world.
 
 NOTE: Inline templates defined in the source file that requires sinatra are
 automatically loaded. Call <tt>enable :inline_templates</tt> explicitly if you
@@ -1006,8 +1006,8 @@ It is also possible to use a
   etag @article.sha1, :weak
 
 These helpers will not do any caching for you, but rather feed the necessary
-information to your cache. If you are looking for a quick reverse-proxy caching solution, 
-try {rack-cache}[http://rtomayko.github.com/rack-cache/]:
+information to your cache. If you are looking for a quick reverse-proxy caching
+solution, try {rack-cache}[http://rtomayko.github.com/rack-cache/]:
 
   require "rack/cache"
   require "sinatra"
@@ -1300,8 +1300,8 @@ You can also hand in an array in order to disable a list of protections:
 
                          settings.add_charsets << "application/foobar"
 
-[app_file]             Path to the main application file, used to detect project root,
-                       views and public folder and inline templates.
+[app_file]             Path to the main application file, used to detect project
+                       root, views and public folder and inline templates.
 
 [bind]                 IP address to bind to (default: 0.0.0.0).
                        Only used for built-in server.
@@ -1347,8 +1347,8 @@ You can also hand in an array in order to disable a list of protections:
                        setting if not set.
 
 [raise_errors]         raise exceptions (will stop application). Enabled
-                       by default when <tt>environment</tt> is set to <tt>"test"</tt>,
-                       disabled otherwise.
+                       by default when <tt>environment</tt> is set to
+                       <tt>"test"</tt>, disabled otherwise.
 
 [run]                  if enabled, Sinatra will handle starting the web server,
                        do not enable if using rackup or other means.
@@ -1388,15 +1388,20 @@ You can also hand in an array in order to disable a list of protections:
 
 == Environments
 
-There are three predefined +environments+: <tt>development</tt>,  <tt>production</tt> and <tt>test</tt>. Environment can be set by RACK_ENV environment variable, and default value is <tt>development</tt>.
+There are three predefined +environments+: <tt>"development"</tt>,
+<tt>"production"</tt> and <tt>"test"</tt>. Environments can be set
+through the +RACK_ENV+ environment variable. The default value is
+<tt>"development"</tt>. In this mode, all templates are reloaded between
+requests. Special <tt>not_found</tt> and <tt>error</tt> handlers are installed
+for this environment so you will see a stack trace in your browser.
+In <tt>"production"</tt> and <tt>"test"</tt> templates are cached by default.
 
-You can also run different environemnt using <tt>-e</tt> option:
+To run different environments use the <tt>-e</tt> option:
 
   ruby my_app.rb -e [ENVIRONMENT]
 
-You can use predefinied methods: +development?+, +test?+ and +production?+, to check which enviroment is set.
-
-+Developemnt+ is default setting. In this mode, all templates are being reloaded between requests. Special <tt>not_found</tt> and <tt>error</tt> handlers are installed for this enviroment, so you will see nice error page. In +production+ and +test+ templates are being cached.
+You can use predefined methods: +development?+, +test?+ and +production?+ to
+check which enviroment is currently set.
 
 == Error Handling
 
@@ -1501,8 +1506,8 @@ with {CodeRack}[http://coderack.org/] or in the
 
 == Testing
 
-Sinatra tests can be written using any Rack-based testing library
-or framework. {Rack::Test}[http://rdoc.info/github/brynary/rack-test/master/frames] 
+Sinatra tests can be written using any Rack-based testing library or framework.
+{Rack::Test}[http://rdoc.info/github/brynary/rack-test/master/frames]
 is recommended:
 
   require 'my_sinatra_app'
@@ -1564,7 +1569,8 @@ available via the top-level DSL. Most top-level apps can be converted to
   of <tt>Sinatra::Base</tt>.
 
 <tt>Sinatra::Base</tt> is a blank slate. Most options are disabled by default,
-including the built-in server. See {Options and Configuration}[http://sinatra.github.com/configuration.html]
+including the built-in server. See
+{Options and Configuration}[http://sinatra.github.com/configuration.html]
 for details on available options and their behavior.
 
 === Modular vs. Classic Style