sinatra/README.de.rdoc

= Sinatra
<i>Wichtig: Dieses Dokument ist eine Übersetzung aus dem Englischen und unter 
Umständen nicht auf dem aktuellsten Stand.</i>

Sinatra ist eine DSL, die das schnelle Erstellen von Webanwendungen in Ruby
mit minimalen Aufwand ermöglicht:

  # myapp.rb
  require 'sinatra'
  get '/' do
    'Hallo Welt!'
  end

Einfach via rubygems installieren und starten:

  gem install sinatra
  ruby -rubygems myapp.rb

Die Seite kann nun unter http://localhost:4567 betrachtet werden.

== Routen

In Sinatra wird eine Route durch eine HTTP-Methode und ein URL-Muster definiert. 
Jeder dieser Routen wird ein Ruby-Block zugeordnet.

  get '/' do
    .. zeige etwas ..
  end

  post '/' do
    .. erstelle etwas ..
  end

  put '/' do
    .. update etwas ..
  end

  delete '/' do
    .. entferne etwas ..
  end
  
  options '/' do
    .. lege etwas fest ..
  end

Die Routen werden in der Reihenfolge durchlaufen, in der sie definiert wurden.
Das erste Routemuster, das mit dem Request übereinstimmt, wird ausgeführt.

Die Muster der Routen können benannte Parameter beinhalten, die über den
<tt>params</tt>-Hash zugänglich gemacht werden:

  get '/hallo/:name' do
    # passt auf "GET /hallo/foo" und "GET /hallo/bar"
    # params[:name] ist 'foo' oder 'bar'
    "Hallo #{params[:name]}!"
  end

Man kann auf diese auch mit Blockparametern zugreifen:

  get '/hallo/:name' do |n|
    "Hallo #{n}!"
  end

Routenmuster können auch mit Splat- oder Wildcardparametern über das
<tt>params[:splat]</tt> Array angesprochen werden.

  get '/sag/*/zu/*' do
    # passt auf /sag/hallo/zu/welt
    params[:splat] # => ["hallo", "welt"]
  end

  get '/download/*.*' do
    # passt auf /download/pfad/zu/datei.xml
    params[:splat] # => ["pfad/zu/datei", "xml"]
  end

Routen mit regulären Ausdrücken sind auch möglich:

  get %r{/hallo/([\w]+)} do
    "Hallo, #{params[:captures].first}!"
  end

Und auch hier kann man Blockparameter nutzen:

  get %r{/hallo/([\w]+)} do |c|
    "Hallo, #{c}!"
  end

=== Bedingungen

An Routen können eine Vielzahl von Bedingungen angehängt werden, die erfüllt
sein müssen, damit der Block ausgeführt wird. Möglich wäre etwa eine
Einschränkung des User Agents:

  get '/foo', :agent => /Songbird (\d\.\d)[\d\/]*?/ do
    "Du verwendest Songbird Version #{params[:agent][0]}"
  end

  get '/foo' do
    # passt auf andere Browser
  end

Andere mitgelieferte Bedingungen sind +host_name+ und +provides+:

  get '/', :host_name => /^admin\./ do
    "Adminbereich, Zugriff verweigert!"
  end

  get '/', :provides => 'html' do
    haml :index
  end

  get '/', :provides => ['rss', 'atom', 'xml'] do
    builder :feed
  end

Man kann auch relativ einfach eigene Bedingungen hinzufügen:

  set(:probability) { |value| condition { rand <= value } }

  get '/auto_gewinnen', :probability => 0.1 do
    "Du hast gewonnen!"
  end

  get '/auto_gewinnen' do
    "Tut mir leid, verloren."
  end

=== Rückgabewerte

Durch den Rückgabewert eines Routenblocks wird mindestens der Response Body
festgelegt, der an den HTTP Client, bzw die nächste Rack Middleware
weitergegeben wird. Im Normalfall handelt es sich hierbei, wie
in den vorangehenden Beispielen zu sehen war, um einen String. Es werden allerdings auch andere
Werte akzeptiert.

Man kann jedes Objekt zurückgeben, bei dem es sich entweder um einenen validen
Rack-Rückgabewert, einen validen Rack-Body oder einen HTTP Status Code
handelt:

* Ein Array mit drei Elementen: <tt>[Status (Fixnum), Headers (Hash), Response Body (hört auf #each)]</tt>
* Ein Array mit zwei Elementen: <tt>[Status (Fixnum), Response Body (hört auf #each)]</tt>
* Ein Objekt, das auf <tt>#each</tt> hört und den an diese Methode übergebenen Block nur mit Strings als Übergabewerte aufruft.
* Ein Fixnum, das den Status Code festlegt.

Damit lässt sich relativ einfach Streaming implementieren:

    class Stream
      def each
        100.times { |i| yield "#{i}\n" }
      end
    end

    get('/') { Stream.new }

== Statische Dateien

Statische Dateien werden aus dem <tt>./public</tt> Ordner ausgeliefert. Es ist
möglich einen anderen Ort zu definieren, indem man die <tt>:public</tt> Option
setzt:

  set :public, File.dirname(__FILE__) + '/static'

Zu beachten ist, dass der Ordnername public nicht Teil der URL ist. Die Datei
<tt>./public/css/style.css</tt> ist unter
<tt>http://example.com/css/style.css</tt> zu finden.

== Views / Templates

Standardmäßig wird davon ausgegangen, dass sich Templates im
<tt>./views</tt> Ordner befinden. Man kann jedoch einen anderen Ordner
festlegen:

  set :views, File.dirname(__FILE__) + '/templates'

Eine wichtige Sache, die man sich hierbei merken sollte, ist das man immer mit
Symbols auf Templates verweisen sollte, auch wenn sich ein Template in einem
Unterordner befindet (in diesen Fall <tt>:'subdir/template'</tt>).
Renderingmethoden rendern jeden String direkt.

=== Haml-Templates

Das +haml+ gem wird benötigt, um Haml-Templates rendern zu können:

  # haml muss eingebunden werden
  require 'haml'

  get '/' do
    haml :index
  end

Dieser Code rendert <tt>./views/index.haml</tt>.

{Hamls Optionen}[http://haml-lang.com/docs/yardoc/file.HAML_REFERENCE.html#options]
können global durch die Sinatrakonfiguration gesetzt werden,
siehe {Optionen und Konfiguration}[http://www.sinatrarb.com/configuration.html],
und individuell überschrieben werden.

  set :haml, :format => :html5 # Standard Haml-Format ist :xhtml

  get '/' do
    haml :index, :format => :html4 # überschrieben
  end

=== Erb-Templates

  # erb muss eingebunden werden
  require 'erb'

  get '/' do
    erb :index
  end

Dieser Code rendert <tt>./views/index.erb</tt>.

=== Erubis

Das +erubis+ gem wird benötigt, um Erubis-Templates rendern zu können:

  # erbubis muss eingebunden werden
  require 'erubis'

  get '/' do
    erubis :index
  end

Dieser Code rendert <tt>./views/index.erubis</tt>.

Es ist auch möglich Erb mit Erubis zu ersetzen:

  require 'erubis'
  Tilt.register :erb, Tilt[:erubis]
  
  get '/' do
    erb :index
  end

Dieser Code rendert ebenfalls <tt>./views/index.erb</tt>.

=== Builder-Templates

Das +builder+ gem wird benötigt, um Builder-Templates rendern zu können:

  # builder muss eingebunden werden
  require 'builder'

  get '/' do
    builder :index
  end

Dieser Code rendert <tt>./views/index.builder</tt>.

=== Nokogiri-Templates

Das +nokogiri+ gem wird benötigt, um Nokogiri-Templates rendern zu können:

  # nokogiri muss eingebunden werden
  require 'nokogiri'

  get '/' do
    nokogiri :index
  end

Dieser Code rendert <tt>./views/index.nokogiri</tt>.

=== Sass-Templates

Das +haml+ oder +sass+ gem wird benötigt, um Sass-Templates rendern zu können:

  # sass muss eingebunden werden
  require 'sass'

  get '/stylesheet.css' do
    sass :stylesheet
  end

Dieser Code rendert <tt>./views/stylesheet.sass</tt>.

{Sass Optionen}[http://sass-lang.com/docs/yardoc/file.SASS_REFERENCE.html#options]
können global durch die Sinatra-Konfiguration gesetzt werden,
siehe {Optionen und Konfiguration}[http://www.sinatrarb.com/configuration.html],
und individuell überschrieben werden.

  set :sass, :style => :compact # Standard Sass-Style ist :nested

  get '/stylesheet.css' do
    sass :stylesheet, :style => :expanded # überschrieben
  end

=== Scss-Templates

Das +haml+ oder +sass+ gem wird benötigt, um SCSS-Templates rendern zu können:

  # sass muss eingebunden werden
  require 'sass'

  get '/stylesheet.css' do
    scss :stylesheet
  end

Dieser Code rendert <tt>./views/stylesheet.scss</tt>.

{Scss Optionen}[http://sass-lang.com/docs/yardoc/file.SASS_REFERENCE.html#options]
können global durch die Sinatra-Konfiguration gesetzt werden,
siehe {Optionen und Konfiguration}[http://www.sinatrarb.com/configuration.html],
und individuell überschrieben werden.

  set :scss, :style => :compact # Standard Scss-Style ist :nested

  get '/stylesheet.css' do
    scss :stylesheet, :style => :expanded # überschrieben
  end

=== Less-Templates

Das +less+ gem wird benötigt, um Less-Templates rendern zu können:

  # less muss eingebunden werden
  require 'less'

  get '/stylesheet.css' do
    less :stylesheet
  end

Dieser Code rendert <tt>./views/stylesheet.less</tt>.

=== Liquid-Templates

Das +liquid+ gem wird benötigt, um Liquid-Templates rendern zu können:

  # liquid muss eingebunden werden
  require 'liquid'

  get '/' do
    liquid :index
  end

Dieser Code rendert <tt>./views/index.liquid</tt>.

Da man aus Liquid-Templates heraus keine Methoden (abgesehen von +yield+)
aufrufen kann, will man nahezu in allen Fällen +locals+ übergeben:

  liquid :index, :locals => { :key => 'value' }

=== Markdown-Templates

Das +rdiscount+ gem wird benötigt, um Markdown-Templates rendern zu können:

  # rdiscount muss eingebunden werden
  require "rdiscount"

  get '/' do
    markdown :index
  end

Dieser Code rendert <tt>./views/index.markdown</tt> (+md+ und +mkd+ sind
ebenfalls zulässige Dateiendungen).

Da es weder möglich ist Methoden aufzurufen, noch +locals+ zu übergeben, ist
es am sinnvollsten Markdown in Kombination mit einer anderen Template-Engine
zu nutzen:

  erb :overview, :locals => { :text => markdown(:introduction) }

Es ist auch möglich die +markdown+ Methode aus anderen Templates heraus
aufzurufen:

  %h1 Hallo von Haml!
  %p= markdown(:greetings)

Da man Ruby aus Markdown heraus nicht aufrufen kann, ist es nicht
möglich Layouts zu verwenden, die in Markdown geschrieben sind. Es ist aber
möglich einen anderen Renderer für das Template zu verwenden als für das
Layout, indem man die <tt>:layout_engine</tt> option angibt:

  get '/' do
    markdown :index, :layout_engine => :erb
  end

Das wird <tt>./views/index.md</tt> mit <tt>./views/layout.erb</tt> als Layout
rendern.

Denk dran, dass man solche Einstellungen auch global setzen kann:

  set :markdown, :layout_engine => :haml, :layout => :post

  get '/' do
    markdown :index
  end

Das wird <tt>./views/index.md</tt> (und jedes andere Markdown Template) mit
<tt>./views/post.haml</tt> als Layout rendern.

Ebenso ist es möglich Markdown mit BlueCloth anstelle von RDsicount zu parsen:

  require 'bluecloth'
  
  Tilt.register 'markdown', BlueClothTemplate
  Tilt.register 'mkd',      BlueClothTemplate
  Tilt.register 'md',       BlueClothTemplate
  
  get '/' do
    markdown :index
  end

Das sollte <tt>./views/index.md</tt> mit BlueCloth rendern.

=== Textile-Templates

Das +redcloth+ gem wird benötigt, um Textile-Templates rendern zu können:

  # redcloth muss eingebunden werden
  require "redcloth"

  get '/' do
    textile :index
  end

Dieser Code rendert <tt>./views/index.textile</tt>.

Da es weder möglich ist Methoden aufzurufen, noch +locals+ zu übergeben, ist
es am sinnvollsten Textile in Kombination mit einer anderen Template-Engine
zu nutzen:

  erb :overview, :locals => { :text => textile(:introduction) }

Es ist auch möglich die +textile+ Methode aus anderen Templates heraus
aufzurufen:

  %h1 Hallo von Haml!
  %p= textile(:greetings)

Da man Ruby aus Textile heraus nicht aufrufen kann, ist es nicht
möglich Layouts zu verwenden, die in Textile geschrieben sind. Es ist aber
möglich einen anderen Renderer für das Template zu verwenden als für das
Layout, indem man die <tt>:layout_engine</tt> option angibt:

  get '/' do
    textile :index, :layout_engine => :erb
  end

Das wird <tt>./views/index.textile</tt> mit 
<tt>./views/layout.erb</tt> als Layout
rendern.

Denk dran, dass man solche Einstellungen auch global setzen kann:

  set :textile, :layout_engine => :haml, :layout => :post

  get '/' do
    textile :index
  end

Das wird <tt>./views/index.textile</tt> (und jedes andere Markdown Template) mit
<tt>./views/post.haml</tt> als Layout rendern.

=== RDoc-Templates

Das +rdoc+ gem wird benötigt, um RDoc-Templates rendern zu können:

  # RDoc muss eingebunden werden
  require "rdoc"

  get '/' do
    rdoc :index
  end

Dieser Code rendert <tt>./views/index.rdoc</tt>.

Da es weder möglich ist Methoden aufzurufen, noch +locals+ zu übergeben, ist
es am sinnvollsten RDoc in Kombination mit einer anderen Template-Engine
zu nutzen:

  erb :overview, :locals => { :text => rdoc(:introduction) }

Es ist auch möglich die +rdoc+ Methode aus anderen Templates heraus
aufzurufen:

  %h1 Hallo von Haml!
  %p= rdoc(:greetings)

Da man Ruby aus RDoc heraus nicht aufrufen kann, ist es nicht
möglich Layouts zu verwenden, die in RDoc geschrieben sind. Es ist aber
möglich einen anderen Renderer für das Template zu verwenden als für das
Layout, indem man die <tt>:layout_engine</tt> option angibt:

  get '/' do
    rdoc :index, :layout_engine => :erb
  end

Das wird <tt>./views/index.rdoc</tt> mit 
<tt>./views/layout.erb</tt> als Layout
rendern.

Denk dran, dass man solche Einstellungen auch global setzen kann:

  set :rdoc, :layout_engine => :haml, :layout => :post

  get '/' do
    rdoc :index
  end

Das wird <tt>./views/index.rdoc</tt> (und jedes andere Markdown Template) mit
<tt>./views/post.haml</tt> als Layout rendern.


=== Radius-Templates

Das +radius+ gem wird benötigt, um Radius-Templates rendern zu können:

  # radius muss eingebunden werden
  require 'radius'

  get '/' do
    radius :index
  end

Dieser Code rendert <tt>./views/index.radius</tt>.

Da man aus Radius-Templates heraus keine Methoden (abgesehen von +yield+)
aufrufen kann, will man nahezu in allen Fällen +locals+ übergeben:

  radius :index, :locals => { :key => 'value' }

=== Markaby-Templates

Das +markaby+ gem wird benötigt, um Markaby-Templates rendern zu können:

  # markaby muss eingebunden werden
  require 'markaby'

  get '/' do
    markaby :index
  end

Dieser Code rendert <tt>./views/index.mab</tt>.

=== Slim-Templates

Das +slim+ gem wird benötigt, um Slim-Templates rendern zu können:

  # slim muss eingebunden werden
  require 'slim'

  get '/' do
    slim :index
  end

Dieser Code rendert <tt>./views/index.slim</tt>.

=== CoffeeScript-Templates

Das +coffee+-script gem und  mindestens eine der folgenden Optionen werden 
benötigt, um JavaScript auf dem Server ausführen zu können:

* +node+ (von Node.js) befindet sich im Pfad
* du bist unter OS X
* +therubyracer+ gem/library

Siehe auch http://github.com/josh/ruby-coffee-script für eine vollständige 
Liste aller Optionen.

Nun kannst Du CoffeeScript Templates in Deiner App rendern:

  # coffee-script muss eingebunden werden
  require 'coffee-script'

  get '/application.js' do
    coffee :application
  end

Dieser Code rendert <tt>./views/application.coffee</tt>.

=== Inline-Templates

  get '/' do
    haml '%div.title Hallo Welt'
  end

Rendert den Inline-Template-String.

=== Auf Variablen in Templates zugreifen

Templates werden im selben Kontext ausgeführt wie Routen. Instanzvariablen in
Routen sind auch direkt im Template verfügbar:

  get '/:id' do
    @foo = Foo.find(params[:id])
    haml '%h1= @foo.name'
  end

Oder durch einen expliziten Hash von lokalen Variablen:

  get '/:id' do
    foo = Foo.find(params[:id])
    haml '%h1= foo.name', :locals => { :foo => foo }
  end

Dies wird typischerweise bei Verwendung von Subtemplates (partials) in anderen
Templates eingesetzt.

=== Inline-Templates

Templates können auch am Ende der Datei definiert werden:

  require 'sinatra'

  get '/' do
    haml :index
  end

  __END__

  @@ layout
  %html
    = yield

  @@ index
  %div.title Hallo Welt!!!!!

Anmerkung: Inline-Templates die in der Datei definiert sind, die <tt>require
'sinatra'</tt> aufruft, werden automatisch geladen. Um andere Inline-Templates
in anderen Dateien aufzurufen, muss <tt>enable :inline_templates</tt> explizit
verwendet werden.

=== Benannte Templates

Templates können auch mit der Top-Level <tt>template</tt>-Methode definiert
werden:

  template :layout do
    "%html\n  =yield\n"
  end

  template :index do
    '%div.title Hallo Welt!'
  end

  get '/' do
    haml :index
  end

Wenn ein Template mit dem Namen "layout" existiert, wird es bei jedem Aufruf
verwendet. Durch <tt>:layout => false</tt> kann das Ausführen verhindert werden.

  get '/' do
    haml :index, :layout => !request.xhr?
  end

=== Datieendungen zuordnen

Um eine Dateiendung einer Template Engine zuzuordnen, benutzt man am besten
<tt>Tilt.register</tt>. Wenn man zum Beispiel die Dateiendung +tt+ für Textile
Templates nutzen möchte, so lässt sich das wie folgt bewerkstelligen:

  Tilt.register :tt, Tilt[:textile]

=== Eine eigene Template Engine hinzufügen

Zu allererst muss man die Engine bei Tilt registrieren und danach eine
Rendering-Methode erstellen:

  Tilt.register :mtt, MeineTolleTemplateEngine

  helpers do
    def mtt(*args) render(:mtt, *args) end
  end

  get '/' do
    mtt :index
  end

Dieser Code rendert <tt>./views/application.mtt</tt>. Siehe
https://github.com/rtomayko/tilt um mehr über Tilt zu lernen.

== Filter

Before-Filter werden immer vor jedem Request in dem selben Kontext wie danach
die Routen ausgeführt. So kann man etwa Request und Antwort ändern. Gesetzte
Instanzvariablen in Filtern können in Routen und Templates verwendet werden:

  before do
    @note = 'Hi!'
    request.path_info = '/foo/bar/baz'
  end

  get '/foo/*' do
    @note #=> 'Hi!'
    params[:splat] #=> 'bar/baz'
  end

After-Filter werden nach jedem Request im selben Kontext ausgeführt, und
können ebenfalls Request und Antwort ändern. In Before-Filtern gesetzte
Instanzvariablen können in After-Filterm verwendet werden:

  after do
    puts response.status
  end

Filter können optional auch mit einem Pattern ausgestattet werden, welche auf 
den Request-Pfad passen müssen, damit der Filter ausgeführt wird:

  before '/protected/*' do
    authenticate!
  end

  after '/create/:slug' do |slug|
    session[:last_slug] = slug
  end

Ähnlich wie Routen können Filter auch mit weiteren Bedingungen eingeschränkt
werden:

  before :agent => /Songbird/ do
    # ...
  end
  
  after '/blog/*', :host_name => 'example.com' do
    # ...
  end

== Helfer

Durch die Top-Level <tt>helpers</tt>-Methode, werden sogenannte Helfer-Methoden
definiert, die in Routen und Templates verwendet werden können:

  helpers do
    def bar(name)
      "#{name}bar"
    end
  end

  get '/:name' do
    bar(params[:name])
  end

== Anhalten

Zum sofortigen stoppen eines Request in einem Filter oder einer Route:

  halt

Der Status kann beim stoppen auch angegeben werden:

  halt 410

Oder auch den Response-Body:

  halt 'Hier steht der Body'

Oder beides:

  halt 401, 'verschwinde!'

Sogar mit Headers:

  halt 402, {'Content-Type' => 'text/plain'}, 'Rache'

== Weiterspringen

Eine Route kann mittels <tt>pass</tt> zu der nächsten passenden Route springen:

  get '/raten/:wer' do
    pass unless params[:wer] == 'Frank'
    'Du hast mich!'
  end

  get '/raten/*' do
    'Du hast mich verfehlt!'
  end

Der Block wird sofort verlassen und es wird nach der nächsten treffenden Route
gesucht. Ein 404 Fehler wird zurückgegeben, wenn kein treffendes Routen-Muster
gefunden wird.

--
=== Triggering Another Route

Sometimes +pass+ is not what you want, instead you would like to get the result
of calling another route. Simply use +call+ to achieve this:

  get '/foo' do
    status, headers, body = call request.env.merge("PATH_INFO" => '/bar')
    [status, body.upcase]
  end

  get '/bar' do
    "bar"
  end

Note that in the example above, you would ease testing and increase performance
by simply moving <tt>"bar"</tt> into a helper method used by both <tt>/foo</tt>
and <tt>/bar</tt>.

If you want the request to be sent to the same application instance rather than
a duplicate, use <tt>call!</tt> instead of <tt>call</tt>.

Check out the Rack specification if you want to learn more about <tt>call</tt>.

=== Setting Body and Status Code

It is possible and recommended to set the status code and response body with the
return value of the route block. However, in some scenarios you might want to
set the body at an arbitrary point in the execution flow. You can do so with the
+body+ helper method. If you do so, you can use that method from there on to
access the body:

  get '/foo' do
    body "bar"
  end
  
  after do
    puts body
  end

It is also possible to pass a block to +body+, that will be executed by the Rack
handler (this can be used to implement streaming, see "Return Values").

Similar to +body+, you can also set the status code:

  get '/foo' do
    status 418
    halt "I'm a tea pot!"
  end

=== Generating URLs

For generating URLs you should use the +url+ helper method, for instance, in
Haml:

  %a{:href => url('/foo')} foo

It takes reverse proxies and Rack routers into account, if present.

This method is also aliased to +to+ (see below) for an
example).

=== Browser Redirect

You can trigger a browser redirect with the +redirect+ helper method:

  get '/foo' do
    redirect to('/bar')
  end

Any additional parameters are handled like arguments passed to +halt+:

  redirect to('/bar'), 303
  redirect 'http://google.com', 'wrong place, buddy'

You can also easily redirect back to the page the user came from with
<tt>redirect back</tt>:

  get '/foo' do
    "<a href='/bar'>do something</a>"
  end

  get '/bar' do
    do_something
    redirect back
  end

To pass arguments with a redirect, either add them to the query:

  redirect to('/bar?sum=42')

Or use a session:

  enable :session
  
  get '/foo' do
    session[:secret] = 'foo'
    redirect to('/bar')
  end
  
  get '/bar' do
    session[:secret]
  end

=== Sending Files

For sending files, you can use the <tt>send_file</tt> helper method:

  get '/' do
    send_file 'foo.png'
  end

It also takes a couple of options:

  send_file 'foo.png', :type => :jpg

The options are:

[filename]
  file name in response, defaults to the real file name.

[last_modified]
  value for Last-Modified header, defaults to the file's mtime.

[type]
  content type to use, guessed from the file extension if missing.

[disposition]
  used for Content-Disposition, possible values: +nil+ (default),
  <tt>:attachement</tt> and <tt>:inline</tt>

[length]
  Content-Length header, defaults to file size.

If supported by the Rack handler, other means than streaming from the Ruby
process will be used. If you use this helper method, Sinatra will automatically
handle range requests.

++

== Das Request-Objekt

Auf das `request`-Objeket der eigehenden Anfrage kann man vom Anfragescope aus zugreifen:

  # App läuft unter http://example.com/example
  get '/foo' do
    request.body              # Request Body des Clients (siehe unten)
    request.scheme            # "http"
    request.script_name       # "/example"
    request.path_info         # "/foo"
    request.port              # 80
    request.request_method    # "GET"
    request.query_string      # ""
    request.content_length    # Länge von request.body
    request.media_type        # Media-Type von request.body
    request.host              # "example.com"
    request.get?              # true (ähnliche Methoden für andere Verben)
    request.form_data?        # false
    request["SOME_HEADER"]    # Wert des SOME_HEADER-headers
    request.referer           # der Referrer des Clients oder '/'
    request.user_agent        # User Agent (genutzt von :agent-Bedingung)
    request.cookies           # Hash der Cookies
    request.xhr?              # Ist dies eine Ajax-Anfrage?
    request.url               # "http://example.com/example/foo"
    request.path              # "/example/foo"
    request.ip                # Client IP-Addresse
    request.secure?           # false
    requuest.env              # env-Hash den Rack durchreicht
  end

Manche Optionen, wie etwa <tt>script_name</tt> oder <tt>path_info</tt> sind
auch schreibbar:

  before { request.path_info = "/" }
  
  get "/" do
    "Alle Anfragen kommen hier an!"
  end

Der <tt>request.body</tt> ist einn IO- oder StringIO-Objekt:

  post "/api" do
    request.body.rewind  # falls schon jemand davon gelesen hat
    daten = JSON.parse request.body.read
    "Hallo #{daten['name']}!"
  end

--
=== Looking Up Template Files

The <tt>find_template</tt> helper is used to find template files for rendering:

  find_template settings.views, 'foo', Tilt[:haml] do |file|
    puts "could be #{file}"
  end

This is not really useful. But it is useful that you can actually override this
method to hook in your own lookup mechanism. For instance, if you want to be
able to use more than one view directory:

  set :views, ['views', 'templates']

  helpers do
    def find_template(views, name, engine, &block)
      Array(views).each { |v| super(v, name, engine, &block) }
    end
  end

Another example would be to use different directories for different engines:

  set :views, :sass => 'views/sass', :haml => 'templates', :default => 'views'

  helpers do
    def find_template(views, name, engine, &block)
      _, folder = views.detect { |k,v| engine == Tilt[k] }
      folder ||= views[:default]
      super(folder, name, engine, &block)
    end
  end

You can also easily wrap this up in an extension and share with others!

Note that <tt>find_template</tt> does not check if the file really exists but
rather calls the given block for all possible paths. This is not a performance
issue, since +render+ will use +break+ as soon as a file is found. Also,
template locations (and content) will be cached if you are not running in
development mode. You should keep that in mind if you write a really crazy
method.

++

== Konfiguration

Wird einmal beim Starten in jedweder Umgebung ausgeführt:

  configure do
    # setze eine Option
    set :option, 'wert'
    
    # setze mehrere Optionen
    set :a => 1, :b => 2
    
    # das gleiche wie `set :option, true`
    enable :option
    
    # das gleiche wie `set :option, false`
    disable :option
    
    # Dynamische Einstellungen mit Blöcken
    set(:css_dir) { File.join(views, 'css') }
  end

Läuft nur, wenn die Umgebung (RACK_ENV Umgebungsvariable) auf
<tt>:production</tt> gesetzt ist:

  configure :production do
    ...
  end

Läuft nur, wenn die Umgebung auf <tt>:production</tt> oder auf <tt>:test</tt>
gesetzt ist:

  configure :production, :test do
    ...
  end

Zugang zu diesen Einstellungen bekommt man über +settings+:

  configure do
    set :foo, 'bar'
  end

  get '/' do
    settings.foo? # => true
    settings.foo  # => 'bar'
    ...
  end

--
=== Available Settings

[absolute_redirects]  If disabled, Sinatra will allow relative redirects,
                      however, Sinatra will no longer conform with RFC 2616
                      (HTTP 1.1), which only allows absolute redirects.
                      
                      Enable if your app is running behind a reverse proxy that
                      has not been set up properly. Note that the +url+ helper
                      will still produce absolute URLs, unless you pass in
                      +false+ as second parameter.
                      
                      Disabled per default.

[add_charsets]        mime types the <tt>content_type</tt> helper will
                      automatically add the charset info to.
                      
                      You should add to it rather than overriding this option:
                      
                        settings.add_charsets << "application/foobar"

[app_file]            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.

[default_encoding]    encoding to assume if unknown
                      (defaults to <tt>"utf-8"</tt>).

[dump_errors]         display errors in the log.

[environment]         current environment, defaults to <tt>ENV['RACK_ENV']</tt>,
                      or <tt>"development"</tt> if not available.

[logging]             use the logger.

[lock]                Places a lock around every request, only running
                      processing on request per Ruby process concurrently.
                      
                      Enabled if your app is not thread-safe.
                      Disabled per default.

[method_override]     use <tt>_method</tt> magic to allow put/delete forms in
                      browsers that don't support it.

[port]                Port to listen on. Only used for built-in server.

[prefixed_redirects]  Whether or not to insert <tt>request.script_name</tt> into
                      redirects if no absolute path is given. That way
                      <tt>redirect '/foo'</tt> would behave like
                      <tt>redirect to('/foo')</tt>. Disabled per default.

[public]              folder public files are served from

[reload_templates]    whether or not to reload templates between requests.
                      Enabled in development mode and on Ruby 1.8.6 (to
                      compensate a bug in Ruby causing a memory leak).

[root]                project root folder.

[raise_errors]        raise exceptions (will stop application).

[run]                 if enabled, Sinatra will handle starting the web server,
                      do not enable if using rackup or other means.

[running]             is the built-in server running now?
                      do not change this setting!

[server]              server or list of servers to use for built-in server.
                      defaults to ['thin', 'mongrel', 'webrick'], order indicates
                      priority.

[sessions]            enable cookie based sessions.

[show_exceptions]     show a stack trace in the browser.

[static]              Whether Sinatra should handle serving static files.
                      Disable when using a Server able to do this on its own.
                      Disabling will boost performance.
                      Enabled per default.

[views]               views folder.

++
== Fehlerbehandlung

Error Handler laufen im selben Kontext wie Routen und Filter, was bedeutet,
dass alle Goodies wie <tt>haml</tt>, <tt>erb</tt>, <tt>halt</tt>, etc.
verwendet werden können.

=== Nicht gefunden

Wenn eine <tt>Sinatra::NotFound</tt> Exception geworfen wird oder der Statuscode 404 ist, wird der <tt>not_found</tt> Handler ausgeführt:

  not_found do
    'Seite kann nirgendwo gefunden werden.'
  end

=== Fehler

Der +error+ Handler wird immer ausgeführt, wenn eine Exception in einem Routenblock
oder in einen Filter geworfen wurde. Die Exception kann über die
<tt>sinatra.error</tt> Rack-Variable angesprochen werden:

  error do
    'Entschuldige es gab einen hässlichen Fehler - ' + env['sinatra.error'].name
  end

Benutzerdefinierte Fehler:

  error MeinFehler do
    'Was passiert ist...' + request.env['sinatra.error'].message
  end

Dann, wenn das passiert:

  get '/' do
    raise MeinFehler, 'etwas schlechtes'
  end

Bekommt man dieses:

  Was passiert ist... etwas schlechtes

Alternativ kann ein Error Handler auch für Statuscode definiert werden:

  error 403 do
    'Zugriff verboten'
  end

  get '/geheim' do
    403
  end

Oder ein Statuscode-Bereich:

  error 400..510 do
    'Boom'
  end

Sinatra setzt verschiedene <tt>not_found</tt> und <tt>error</tt>
Handler in der Development Umgebung.

== Mime-Types

Wenn <tt>send_file</tt> oder statische Dateien verwendet werden, kann es
vorkommen, dass Sinatra den Mime-Typ nicht kennt. Registriert wird dieser mit
+mime_type+ per Dateiendung:

  mime_type :foo, 'text/foo'

Es kann aber auch der +content_type+ Helfer verwendet werden:

  content_type :foo

== Rack Middleware

Sinatra baut auf Rack[http://rack.rubyforge.org/], einem minimalen Standardinterface für Ruby Webframeworks. Eines der interessantesten
Features für Entwickler ist der Support von Middleware, die
zwischen den Server und die Anwendung geschaltet wird und so HTTP
Request und/oder Antwort überwachen und/oder manipulieren kann.

Sinatra macht das erstellen von Middleware-Verkettungen mit der Top-Level
Methode +use+ zu einem Kinderspiel:

  require 'sinatra'
  require 'meine_middleware'

  use Rack::Lint
  use MeineMiddleware

  get '/hallo' do
    'Hallo Welt'
  end

Die Semantik von +use+ entspricht der gleichnamigen Methode der
Rack::Builder[http://rack.rubyforge.org/doc/classes/Rack/Builder.html] DSL
(meist verwendet in Rackup-Dateien). Ein Beispiel dafür ist, dass die
+use+-Methode mehrere/verschiedene Argumente und auch Blöcke entgegen nimmt:

  use Rack::Auth::Basic do |username, password|
    username == 'admin' && password == 'geheim'
  end

Rack bietet eine Vielzahl von standard Middleware für Logging, Debugging,
URL-Routing, Authentifizierung und Session-Verarbeitung.
Sinatra verwendet viele von diesen Komponenten automatisch, abhängig von der
Konfiguration. So muss man häufig +use+ nicht explizit verwenden.

== Testen

Sinatra Tests können mit jedem auf Rack aufbauendem Test Framework geschrieben
werden. {Rack::Test}[http://gitrdoc.com/brynary/rack-test] wird empfohlen:

  require 'my_sinatra_app'
  require 'test/unit'
  require 'rack/test'

  class MyAppTest < Test::Unit::TestCase
    include Rack::Test::Methods

    def app
      Sinatra::Application
    end

    def test_my_default
      get '/'
      assert_equal 'Hallo Welt!', last_response.body
    end

    def test_with_params
      get '/meet', :name => 'Frank'
      assert_equal 'Hallo Frank!', last_response.body
    end

    def test_with_rack_env
      get '/', {}, 'HTTP_USER_AGENT' => 'Songbird'
      assert_equal "Du verwendest Songbird!", last_response.body
    end
  end

Anmerkung: Das eingebaute Sinatra::Test Modul und die Sinatra::TestHarness
Klasse werden seit Version 0.9.2 nicht mehr unterstützt.

== Sinatra::Base - Middleware, Bibliotheken, und modulare Anwendungen

Das Definitieren einer Top-Level Anwendung funktioniert gut für
Microanwendungen, hat aber Nachteile, wenn man wiederverwendbare Komponenten
wie Middleware, Rails Metal, einfache Bibliotheken mit Server Komponenten
oder auch Sinatra Erweiterungen bauen will.
Die Top-Level DSL belastet den Objekt-Namespace und setzt einen Microanwendungsstil voraus (eine einzelne Anwendungsdatei, ./public und ./views
Ordner, Logging, Exception-Detail-Seite, usw.). Genau hier kommt Sinatra::Base
ins Spiel:

  require 'sinatra/base'

  class MyApp < Sinatra::Base
    set :sessions, true
    set :foo, 'bar'

    get '/' do
      'Hallo Welt!'
    end
  end

Die MyApp-Klasse ist eine unabhängige Rack-Komponente, die als Middleware,
Endpunkt oder via Rails Metal verwendet werden kann. Verwendet wird sie durch
+use+ oder +run+ von einer Rackup +config.ru+ Datei oder als Serverkomponente
einer Bibliothek:

   MyApp.run! :host => 'localhost', :port => 9090

Die Methoden der Sinatra::Base-Subklasse sind genau die selben wie die
der Top-Level DSL. Die meisten Top-Level Anwendungen können mit nur zwei Veränderungen zu Sinatra::Base-Komponenten konvertiert werden:

* Die Datei sollte <tt>require 'sinatra/base'</tt> anstelle von
  <tt>require 'sinatra/base'</tt> aufrufen, ansonsten werden alle von
  Sinatras DSL Methoden in den Top-Level- Namespace importiert.
* Alle Routen, Error Handler, Filter und Optionen der Applikation müssen in
  einer Subklasse von Sinatra::Base definiert werden.

<tt>Sinatra::Base</tt> ist ein unbeschriebenes Blatt. Die meisten Optionen sind per default deaktiviert. Das betrifft auch den eingebauten Server. Siehe {Optionen und Konfiguration}[http://sinatra.github.com/configuration.html] für Details über mögliche Optionen.

--
=== Modular vs. Classic Style

Contrary to common believes, there is nothing wrong with classic style. If it
suits your application, you do not have to switch to a modular application.

There are only two downsides compared to modular style:

* You may only have one Sinatra application per Ruby process - if you plan to
  use more, switch to modular style.

* Classic style pollutes Object with delegator methods - if you plan to ship
  your application in a library/gem, switch to modular style.

There is no reason you cannot mix modular and classic style.

If switching from one style to the other, you should be aware of slight
differences in the setting:

  Setting             Classic                 Modular

  app_file            file loading sinatra    nil
  run                 $0 == app_file          false
  logging             true                    false
  method_override     true                    false
  inline_templates    true                    false


=== Serving a Modular Application

There are two common options for starting a modular app, actively starting with
<tt>run!</tt>:

  # my_app.rb
  require 'sinatra/base'
  
  class MyApp < Sinatra::Base
    # ... app code here ...
    
    # start the server if ruby file is executed directly
    run! if app_file == $0
  end

Start with:

  ruby my_app.rb

Or with a <tt>config.ru</tt>, which allows using any Rack handler:

  # config.ru
  require 'my_app'
  run MyApp

Run:

  rackup -p 4567

=== Using a Classic Style Application with a config.ru

Write your app file:

  # app.rb
  require 'sinatra'
  
  get '/' do
    'Hello world!'
  end

And a corresponding <tt>config.ru</tt>:

  require 'app'
  run Sinatra::Application

=== When to use a config.ru?

Good signs you probably want to use a <tt>config.ru</tt>:

* You want to deploy with a different Rack handler (Passenger, Unicorn,
  Heroku, ...).
* You want to use more than one subclass of <tt>Sinatra::Base</tt>.
* You want to use Sinatra only for middleware, but not as endpoint.

<b>There is no need to switch to a <tt>config.ru</tt> only because you
switched to modular style, and you don't have to use modular style for running
with a <tt>config.ru</tt>.</b>

++

=== Sinatra als Middleware nutzen

Es ist nicht nur möglich andere Rack-Middleware mit Sinatra zu nutzen, man
kann außerdem jede Sinatra-Anwendung selbst als Middlware vor jeden beliebigen
Rack-Endpunkt hängen. Bei diesem Endpunkt muss es sich nicht um eine andere
Sinatra-Anwendung handen, es kann jede andere Rack-Anwendung sein
(Rails/Ramaze/Camping/...).

  require 'sinatra/base'

  class LoginScreen < Sinatra::Base
    enable :sessions
  
    get('/login') { haml :login }
  
    post('/login') do
      if params[:name] = 'admin' and params[:password] = 'admin'
        session['user_name'] = params[:name]
      else
        redirect '/login'
      end
    end
  end

  class MyApp < Sinatra::Base
    # Middleware wird vor Filtern ausgeführt
    use LoginScreen
  
    before do
      unless session['user_name']
        halt "Zugriff verweigert, bitte <a href='/login'>einloggen</a>."
      end
    end
  
    get('/') { "Hallo #{session['user_name']}." }
  end

== Geltungsbereich und Bindung

Der Geltungsbereich (scope) legt fest, welche Methoden und Variablen zur 
Verfügung stehen.

=== Anwendungs- oder Klassenscope

Jede Sinatra-Anwendung entspricht einer Sinatra::Base-Subklasse. Falls man die
Top-Level-DSL verwendet (<tt>require 'sinatra'</tt>), so handelt es sich 
hierbei um Sinatra::Application, andernfalls is es jene Subklasse, die man 
explizit angelegt hat. Auf Klassenebene stehen Methoden wie `get` oder `before`
zur Verfügung, man hat aber keinen Zugriff auf das `request`-Object oder die 
`session`, da nur eine einzige Klasse für alle eingehenden Anfragen genutzt 
wird.

Optionen die via `set` gesetzt werden, sind Methoden auf Klassenebene:

  class MyApp < Sinatra::Base
    # Hey, ich bin im Anwendungsscope!
    set :foo, 42
    foo # => 42
    
    get '/foo' do
      # Hey, ich bin nicht mehr im Anwendungsscope!
    end
  end

Im Anwendungsscope befindet man sich:

* In der Anwendungsklasse.
* In Methoden die von Erweiterungen definiert werden.
* Im Block, der an `helpers` übergeben wird.
* In Procs und Blöcken die an `set` übergeben werden.

Man kann auf das Scope-Object (die Klasse) wie folgt zugreifen:

* Über das Objekt, dass an den `configure`-Block übergeben wird (<tt>configure
  { |c| ... }</tt>).
* `settings` aus den anderen Scopes heraus.

=== Anfrage- oder Instanzscope

Für jede eingehende Anfrage wird eine neue Instanz der Anwendungsklasse erstellt und alle Handlers werden in diesem Scope ausgeführt. Aus diesem Scope heraus kann man auf `request` oder `session` zugreifen und Methoden wie `erb` oder `haml` aufrufen. Man kann mit der `settings` Methode außerdem auf den Anwengungsscope zugreifen.

  class MyApp < Sinatra::Base
    # Hey, ich bin im Anwendungsscope!
    get '/neue_route/:name' do
      # Anfragescope für '/neue_route/:name'
      @value = 42
      
      settings.get "/#{params[:name]}" do
        # Anfragescope für "/#{params[:name]}"
        @value # => nil (nicht die gleiche Anfrage)
      end
      
      "Route definiert!"
    end
  end

Im Anfragescope befindet man sich:

* In get/head/post/put/delete Blöcken
* In before/after Filtern
* In Helfermethoden
* In Templates

=== Delegation-Scope

Vom Delegation-Scope aus werden Methoden einfach an den Klassenscope
weitergeleitet. Dieser verhält sich jedoch nicht 100%ig wie der Klassenscope,
da man nicht die Bindung der Klasse besitzt: Nur Methoden, die explizit als
delegierbar markiert wurden stehen hier zur Verfügung und man kann nicht auf
die Variablen des Klassenscopes zugreifen (mit anderen Worten: man hat ein
anderes `self`). Man kann mit <tt>Sinatra::Delegator.delegate
:methoden_name</tt> auch weitere Delegationen hinzufügen.

Im Delegation-Scop befindet man sich:

* Im Top-Level, wenn man <tt>require 'sinatra'</tt> aufgerufen hat.
* In einem Objekt, dass mit dem `Sinatra::Delegator` mixin erweitert wurde.

Schau am besten im Code nach: Hier ist {Sinatra::Delegator mixin}[http://github.com/sinatra/sinatra/blob/master/lib/sinatra/base.rb#L1064] definiert und wird in den {globalen Namespace eingebunden}[http://github.com/sinatra/sinatra/blob/master/lib/sinatra/main.rb#L25].

== Kommandozeile

Sinatra Anwendungen können direkt von der Kommandozeile aus gestartet werden:

  ruby myapp.rb [-h] [-x] [-e ENVIRONMENT] [-p PORT] [-h HOST] [-s HANDLER]

Die Optionen sind:

  -h # Hilfe
  -p # Port setzen (Standard ist 4567)
  -h # Host setzen (Standard ist 0.0.0.0)
  -e # Umgebung setzen (Standard ist development)
  -s # Rack Server/Handler setzen (Standard ist thin)
  -x # Mutex lock einschalten (Standard ist off)

== Der neueste Stand (The Bleeding Edge)
Um auf dem neusten Stand zu bleiben, kannst Du den Master Branch verwenden. Er
sollte recht stabil sein. Ebenso gibt es von Zeit zu Zeit prerelease Gems, die
du so installierst:
  
  gem install sinatra --pre

=== Mit Bundler
Wenn du deine App mit der neusten Version von Sinatra mit 
{Bundler}[http://gembundler.com/] nutzen willst, dann ist dies der 
vorgeschlagene Weg:

Soweit du Bundler noch nicht installiert hast, folgendes:

  gem install bundler
  
Dann erstellst Du in deinem Projektverzeichnis eine sog. +Gemfile+ Datei mit 
folgendem Inhalt:

  source :rubygems
  gem 'sinatra', :git => "git://github.com/sinatra/sinatra.git"
  
  # evtl. andere Abhängigkeiten
  gem 'haml'                    # z.B. wenn du haml verwendest...
  gem 'activerecord', '~> 3.0'  # ...oder ActiveRecord 3.x  

Beachte: Du solltest hier alle Abhängigkeiten eintragen. Sinatras eigenen,
direkten Abhängigkeiten (Tilt und Rack) werden von Bundler automatisch aus dem
Gemfile von Sinatra hinzugefügt.

Jetzt kannst du deine App starten:

  bundle exec ruby myapp.rb
  
=== Eigenes Repository
Um auf den neuesten Stand von Sinatras Code zu sein, kann eine lokale Kopie
angelegt werden. Gestartet wird in der Anwendung mit dem <tt>sinatra/lib</tt>
Ordner im <tt>LOAD_PATH</tt>:

  cd myapp
  git clone git://github.com/sinatra/sinatra.git
  ruby -Isinatra/lib myapp.rb

Alternativ kann der <tt>sinatra/lib</tt> Ordner zum <tt>LOAD_PATH</tt> in
der Anwendung hinzugefügt werden:

  $LOAD_PATH.unshift File.dirname(__FILE__) + '/sinatra/lib'
  require 'rubygems'
  require 'sinatra'

  get '/ueber' do
    "Ich laufe auf Version " + Sinatra::VERSION
  end

Um Sinatra Code von Zeit zu Zeit zu aktualisieren:

  cd myproject/sinatra
  git pull

=== Gem erstellen

Aus der eigenen lokalen Kopie kann nun auch ein globales gem gebaut werden:

  git clone git://github.com/sinatra/sinatra.git
  cd sinatra
  rake sinatra.gemspec
  rake install

Falls du normalerweise gems als root installierst, sollte die letzte Zeile 
so lauten:

  sudo rake install



== Mehr

* {Projekt Website}[http://sinatra.github.com/] - Ergänzende Dokumentation,
  News und Links zu anderen Ressourcen.
* {Hilfe beisteuern}[http://sinatra.github.com/contributing.html] - Einen Fehler gefunden? Brauchst du Hilfe? Hast du einen Patch?
* {Issue Tracker}[http://github.com/sinatra/sinatra/issues]
* {Twitter}[http://twitter.com/sinatra]
* {Mailingliste}[http://groups.google.com/group/sinatrarb]
* {IRC: #sinatra}[irc://chat.freenode.net/#sinatra] auf http://freenode.net