| Path: | README.de.rdoc |
| Last Update: | Thu Mar 24 20:56:06 +0200 2011 |
Wichtig: Dieses Dokument ist eine Übersetzung aus dem Englischen und unter Umständen nicht auf dem aktuellsten Stand.
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 localhost:4567 betrachtet werden.
Es wird empfohlen den Thin Server via gem install thin zu installieren, den Sinatra, soweit vorhanden, dann automatisch verwendet.
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 params-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 params[:splat] 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
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
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:
Damit lässt sich relativ einfach Streaming implementieren:
class Stream
def each
100.times { |i| yield "#{i}\n" }
end
end
get('/') { Stream.new }
Wie oben schon beschrieben, ist Sinatra von Haus aus mit Unterstützung für String Muster und Reguläre Ausdrücke zum Abgleichen von Routen ausgestattet. Das muss aber noch nicht alles sein, man kann ohne größeren Aufwand auch eigene Routenmuster erstellen:
class AllButPattern
Match = Struct.new(:captures)
def initialize(except)
@except = except
@captures = Match.new([])
end
def match(str)
@captures unless @except === str
end
end
def all_but(pattern)
AllButPattern.new(pattern)
end
get all_but("/index") do
# ...
end
Beachte, dass das obige Beispiel etwas übertrieben wirkt. Es geht auch leichter:
get // do
pass if request.path_info == "/index"
# ...
end
Oder unter Verwendung eines negativen look ahead:
get %r{^(?!/index$)} do
# ...
end
Statische Dateien werden aus dem ./public Ordner ausgeliefert. Es ist möglich einen anderen Ort zu definieren, indem man die :public Option setzt:
set :public, File.dirname(__FILE__) + '/static'
Zu beachten ist, dass der Ordnername public nicht Teil der URL ist. Die Datei ./public/css/style.css ist unter example.com/css/style.css zu finden.
Standardmäßig wird davon ausgegangen, dass sich Templates im ./views 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 :’subdir/template‘). Renderingmethoden rendern jeden String direkt.
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 ./views/index.haml.
Hamls Optionen können global durch die Sinatrakonfiguration gesetzt werden, siehe Optionen und Konfiguration, und individuell überschrieben werden.
set :haml, :format => :html5 # Standard Haml-Format ist :xhtml
get '/' do
haml :index, :format => :html4 # überschrieben
end
# erb muss eingebunden werden
require 'erb'
get '/' do
erb :index
end
Dieser Code rendert ./views/index.erb.
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 ./views/index.erubis.
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 ./views/index.erb.
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 ./views/index.builder.
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 ./views/index.nokogiri.
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 ./views/stylesheet.sass.
Sass Optionen können global durch die Sinatra-Konfiguration gesetzt werden, siehe Optionen und Konfiguration, und individuell überschrieben werden.
set :sass, :style => :compact # Standard Sass-Style ist :nested
get '/stylesheet.css' do
sass :stylesheet, :style => :expanded # überschrieben
end
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 ./views/stylesheet.scss.
Scss Optionen können global durch die Sinatra-Konfiguration gesetzt werden, siehe Optionen und Konfiguration, und individuell überschrieben werden.
set :scss, :style => :compact # Standard Scss-Style ist :nested
get '/stylesheet.css' do
scss :stylesheet, :style => :expanded # überschrieben
end
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 ./views/stylesheet.less.
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 ./views/index.liquid.
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' }
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 ./views/index.markdown (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 :layout_engine option angibt:
get '/' do
markdown :index, :layout_engine => :erb
end
Das wird ./views/index.md mit ./views/layout.erb 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 ./views/index.md (und jedes andere Markdown Template) mit ./views/post.haml als Layout rendern.
Ebenso ist es möglich Markdown mit BlueCloth anstelle von RDiscount zu parsen:
require 'bluecloth'
Tilt.register 'markdown', BlueClothTemplate
Tilt.register 'mkd', BlueClothTemplate
Tilt.register 'md', BlueClothTemplate
get '/' do
markdown :index
end
Das sollte ./views/index.md mit BlueCloth rendern.
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 ./views/index.textile.
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 :layout_engine option angibt:
get '/' do
textile :index, :layout_engine => :erb
end
Das wird ./views/index.textile mit ./views/layout.erb 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 ./views/index.textile (und jedes andere Markdown Template) mit ./views/post.haml als Layout rendern.
Das rdoc gem wird benötigt, um RDoc-Templates rendern zu können:
# rdoc/markup/to_html muss eingebunden werden
require "rdoc/markup/to_html"
get '/' do
rdoc :index
end
Dieser Code rendert ./views/index.rdoc.
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 :layout_engine option angibt:
get '/' do
rdoc :index, :layout_engine => :erb
end
Das wird ./views/index.rdoc mit ./views/layout.erb 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 ./views/index.rdoc (und jedes andere Markdown Template) mit ./views/post.haml als Layout rendern.
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 ./views/index.radius.
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' }
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 ./views/index.mab.
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 ./views/index.slim.
Das coffee-script gem und mindestens eine der folgenden Optionen werden benötigt, um JavaScript auf dem Server ausführen zu können:
Siehe auch 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 ./views/application.coffee.
get '/' do
haml '%div.title Hallo Welt'
end
Rendert den Inline-Template-String.
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.
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 require ‘sinatra‘ aufruft, werden automatisch geladen. Um andere Inline-Templates in anderen Dateien aufzurufen, muss enable :inline_templates explizit verwendet werden.
Templates können auch mit der Top-Level template-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 :layout => false kann das Ausführen verhindert werden:
get '/' do
haml :index, :layout => !request.xhr?
end
Um eine Dateiendung einer Template Engine zuzuordnen, benutzt man am besten Tilt.register. 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]
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 ./views/application.mtt. Siehe github.com/rtomayko/tilt, um mehr über Tilt zu lernen.
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
Durch die Top-Level helpers-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
Sessions werden verwendet, um Zustände zwischen den Requests zu speichern. Sind sie aktiviert, hat man einen Session Hash pro Benutzer Session:
enable :sessions
get '/' do
"value = " << session[:value].inspect
end
get '/:value' do
session[:value] = params[:value]
end
Beachte, dass enable :sessions alle Daten in einem Cookie speichert. Unter Umständen kann dies negative Effekte haben, z.B. verursachen viele Daten höheren, teilweise überflüssigen Traffic. Um das zu vermeiden, kann man eine Rack Session Middleware verwenden. Dann aber nicht enable :sessions aufrufen, sondern die Middleware wie üblich in das Programm einbinden:
use Rack::Session::Pool, :expire_after => 2592000
get '/' do
"value = " << session[:value].inspect
end
get '/:value' do
session[:value] = params[:value]
end
Um die Sicherheit zu erhöhen, werden Cookies, die Session-Daten führen, mit einem sogenannten Session Secret signiert. Da sich jedoch dieses Geheimwort bei jedem Neustart der Applikation automatisch ändert, ist es sinnvoll selber eins zu wählen, damit alle Instanzen der Applikation sich das gleiche Session Secret teilen:
set :session_secret, 'super secret'
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'
Natürlich ist es auch möglich ein Template mit halt zu verwenden:
halt erb(:error)
Eine Route kann mittels pass 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.
Manchmal entspricht pass nicht den Anforderungen, wenn das Ergebnis einer anderen Route gefordert wird. Um das zu erreichen, lässt sich call nutzen:
get '/foo' do
status, headers, body = call request.env.merge("PATH_INFO" => '/bar')
[status, body.upcase]
end
get '/bar' do
"bar"
end
Beachte, dass in dem oben angegeben Beispiel die Performance erheblich erhöht werden kann, wenn man +"bar"+ in eine Helfermethode umwandelt, auf die +/foo+ und +/bar+ zugreifen können.
Wenn der Request innerhalb der gleichen App-Instanz aufgerufen und keine Kopie der Instanz erzeugt werden soll, dann verwende +call!+ anstelle von call.
Die Rack Spezifikationen enthalten weitere Informationen zu call.
Es ist möglich und empfohlen den Status Code sowie den Response Body mit einem Returnwert in der Route zu setzen. In manchen Situationen kann es jedoch sein, dass der Body an irgendeiner anderen Stelle während der Ausführung gesetzt wird. Das lässt sich mit der Helfermethode body bewerkstelligen. Wird body verwendet, dann lässt sich der Body jederzeit über diese Methode aufrufen:
get '/foo' do
body "bar"
end
after do
puts body
end
Ebenso ist es möglich einen Block an body weiterzureichen, der dann vom Rack Handler ausgeführt wird (lässt sich z.B. zur Umsetzung von Streaming einsetzen, siehe auch "Rückgabewerte").
Vergleichbar mit body lassen sich auch Status Code und Header setzen:
get '/foo' do
status 418
headers \
"Allow" => "BREW, POST, GET, PROPFIND, WHEN"
"Refresh" => "Refresh: 20; http://www.ietf.org/rfc/rfc2324.txt"
halt "Ich bin ein Teekesselchen"
end
Genau wie bei body, liest ein Aufrufen von headers oder status ohne Argumente den aktuellen Wert aus.
Wenn send_file 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:
get '/' do
content_type :foo
"foo foo foo"
end
Zum Generieren von URLs sollte man die url Helfermethode nutzen, so z.B. beim Einsatz von Haml:
%a{:href => url('/foo')} foo
Soweit vorhanden, wird Rücksicht auf Proxies und Rack Router genommen.
Diese Methode ist ebenso über den Alias to zu erreichen (siehe Beispiel unten).
Eine Browserumleitung kann mit Hilfe der redirect Hilfsmethode erreicht werden:
get '/foo' do
redirect to('/bar')
end
Weitere Parameter werden wie Argumente der halt Methode behandelt:
redirect to('/bar'), 303
redirect 'http://google.com', 'Hier bist Du falsch'
Ebenso leicht lässt sich ein Schritt zurück mit dem Alias redirect back erreichen:
get '/foo' do
"<a href='/bar'>mach was</a>"
end
get '/bar' do
mach_was
redirect back
end
Um Argumente an ein Redirect weiterzugeben, fügt man sie entweder dem Query hinzu:
redirect to('/bar?summe=42')
Oder man verwendet eine Session:
enable :session
get '/foo' do
session[:secret] = 'foo'
redirect to('/bar')
end
get '/bar' do
session[:secret]
end
Zum versenden von Dateien kann die send_file Helfermethode verwende werden:
get '/' do
send_file 'foo.png'
end
Für send_file stehen einige Hash-Optionen zur Verfügung:
send_file 'foo.png', :type => :jpg
Soweit vom Rack Handler unterstützt, werden neben der Übertragung über den Ruby Prozess auch andere Möglichkeiten genutzt. Bei Verwendung der send_file Helfermethode kümmert sich Sinatra selbständig um die Range Requests.
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.referrer # 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 (wäre true bei SSL)
request.forwarded? # true (wenn hinter Reverse Proxy)
requuest.env # env-Hash den Rack durchreicht
end
Manche Optionen, wie etwa script_name oder path_info sind auch schreibbar:
before { request.path_info = "/" }
get "/" do
"Alle Anfragen kommen hier an!"
end
Der request.body 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
Damit der Browser erkennt, dass ein Response gespeichert werden soll und nicht im Browser angezeigt wird, kann der attachment Helfer verwendet werden:
get '/' do
attachment
"Speichern!"
end
Ebenso kann man einen Dateinamen als Parameter hinzufügen:
get '/' do
attachment "info.txt"
"Speichern!"
end
Die find_template Helfermethode wird genutzt, um Template Dateien zum Rendern aufzufinden:
find_template settings.views, 'foo', Tilt[:haml] do |file|
puts "könnte diese hier sein: #{file}"
end
Das ist zwar nicht wirklich brauchbar, aber wenn man sie überschreibt, kann sie nützlich werden, um eigene Nachschlagemechanismen einzubauen. Zum Beispiel dann, wenn man mehr als nur ein view-Verzeichnis verwenden möchte:
set :views, ['views', 'templates']
helpers do
def find_template(views, name, engine, &block)
Array(views).each { |v| super(v, name, engine, &block) }
end
end
Ein anderes Beispiel wäre es verschiedene Vereichnisse für verschiedene Engines zu verwenden:
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
Ebensogut könnte man eine Extension schreiben und diese dann mit anderen teilen!
Beachte, dass find_template nicht prüft, ob eine Datei tatsächlich existiert. Es wird lediglich der angegebene Block aufgerufen und nach allen möglichen Pfaden gesucht. Das ergibt kein Performanceproblem, da render block verwendet, sobald eine Datei gefunden wurde. Ebenso werden Templatepfade samt Inhalt gecached, solange man nicht im Entwicklungsmodus ist. Das sollte man im Hinterkopf behalten, wenn man irgendwelche verrückten Methoden zusammenbastelt.
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 :production gesetzt ist:
configure :production do
...
end
Läuft nur, wenn die Umgebung auf :production oder auf :test 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
Sollte eingeschaltet werden, wenn man hinter einem Reverse Proxy ist, der nicht ordentlich eingerichtet ist. Beachte, dass die url Helfermethode nach wie vor absolute URLs erstellen wird, es sei denn man gibt als zweiten Parameter false an.
Standardmäßig nicht aktiviert.
Es empfielt sich Werte hinzuzufügen anstellen von überschreiben:
settings.add_charsets << "application/foobar"
Eingeschaltet wenn die Application Thread-Safe ist. Standardmäßig nicht aktiviert.
Error Handler laufen im selben Kontext wie Routen und Filter, was bedeutet, dass alle Goodies wie haml, erb, halt, etc. verwendet werden können.
Wenn eine Sinatra::NotFound Exception geworfen wird oder der Statuscode 404 ist, wird der not_found Handler ausgeführt:
not_found do
'Seite kann nirgendwo gefunden werden.'
end
Der error Handler wird immer ausgeführt, wenn eine Exception in einem Routenblock oder in einen Filter geworfen wurde. Die Exception kann über die sinatra.error 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
'Bums'
end
Sinatra setzt verschiedene not_found und error Handler in der Development Umgebung.
Sinatra baut auf Rack, 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 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.
Sinatra Tests können mit jedem auf Rack aufbauendem Test Framework geschrieben werden. 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.
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:
Sinatra::Base ist ein unbeschriebenes Blatt. Die meisten Optionen sind per default deaktiviert. Das betrifft auch den eingebauten Server. Siehe Optionen und Konfiguration für Details über mögliche Optionen.
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:
Es gibt keinen Grund, warum man modulare und klassische Elemente nicht vermischen sollte.
Will man jedoch von einem Stil auf den anderen umsteigen, sollten einige Unterschiede beachtet werden:
Szenario Classic Modular app_file file loading sinatra nil run $0 == app_file false logging true false method_override true false inline_templates true false
Es gibt zwei übliche Wege eine modulare Anwendung zu starten. Zum einen über run!:
# mein_app.rb
require 'sinatra/base'
class MeinApp < Sinatra::Base
# ... Anwendungscode hierhin ...
# starte den Server, wenn die Ruby Datei direkt ausgeführt wird
run! if app_file == $0
end
Starte mit:
ruby mein_app.rb
Oder über eine config.ru, die es erlaubt irgendeinen Rack Handler zu verwenden:
# config.ru require 'mein_app' run MeineApp
Starte:
rackup -p 4567
Schreibe eine Anwendungsdatei:
# app.rb
require 'sinatra'
get '/' do
'Hallo Welt!'
end
Sowie eine dazugehörige config.ru:
require 'app' run Sinatra::Application
Anzeichen dafür, dass man eine config.ru braucht:
Es gibt keinen Grund eine config.ru zu verwenden, nur weil man eine Anwendung im modularen Stil betreiben möchte. Ebenso braucht man keine Anwendung im modularen Stil, um eine config.ru verwenden zu können.
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
Der Geltungsbereich (scope) legt fest, welche Methoden und Variablen zur Verfügung stehen.
Jede Sinatra-Anwendung entspricht einer Sinatra::Base-Subklasse. Falls man die Top-Level-DSL verwendet (require ‘sinatra‘), 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:
Man kann auf das Scope-Object (die Klasse) wie folgt zugreifen:
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:
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 Sinatra::Delegator.delegate :methoden_name auch weitere Delegationen hinzufügen.
Im Delegation-Scop befindet man sich:
Schau am besten im Code nach: Hier ist Sinatra::Delegator mixin definiert und wird in den globalen Namespace eingebunden.
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)
Es wird empfohlen Sinatra unter Ruby 1.8.7, 1.9.2, JRuby oder Rubinius zu installieren.
Die folgenden Versionen werden offiziell unterstützt:
Weiterhin werden wir auf kommende Ruby Versionen ein Auge haben.
Die nachfolgend aufgeführten Ruby Implementationen werden offiziell nicht von Sinatra unterstützt, funktionieren aber normalerweise:
Nicht offiziell unterstützt bedeutet, dass wenn Sachen nicht funktionieren, dann gehen wir davon aus, dass es nicht an Sinatra, sondern an der jeweiligen Implentierung liegt.
Sinatra sollte auf jedem Betriebssystem laufen, dass den gewählten Ruby Interpreter unterstützt.
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
Wenn du deine App mit der neusten Version von Sinatra mit Bundler 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
Um auf den neuesten Stand von Sinatras Code zu sein, kann eine lokale Kopie angelegt werden. Gestartet wird in der Anwendung mit dem sinatra/lib Ordner im LOAD_PATH:
cd myapp git clone git://github.com/sinatra/sinatra.git ruby -Isinatra/lib myapp.rb
Alternativ kann der sinatra/lib Ordner zum LOAD_PATH 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
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
Sinatra folgt dem sog. Semantic Versioning, d.h. SemVer und SemVerTag.
Fehler gefunden? Brauchst du Hilfe? Hast du einen Patch?