sinatra/README.hu.rdoc

= Sinatra
<i>Fontos megjegyzés: Ez a dokumentum csak egy fordítása az angol nyelvű
változat, és lehet, hogy nem naprakész.</i>

A Sinatra egy DSL webalkalmazások Ruby nyelven történő fejlesztéséhez, minimális
energiabefektetéssel:

  # myapp.rb
  require 'sinatra'
  get '/' do
    'Helló Világ!'
  end

Telepítsd a gem-et és indítsd el az alkalmazást a következőképpen:

  sudo gem install sinatra
  ruby -rubygems myapp.rb

Az alkalmazás elérhető lesz itt: http://localhost:4567

== Útvonalak (routes)

A Sinatrában az útvonalat egy HTTP metódus és egy URL-re illeszkedő minta
párosa alkotja. Minden egyes útvonalhoz tartozik egy blokk:

  get '/' do
    .. megjelenítünk valamit ..
  end

  post '/' do
    .. létrehozunk valamit ..
  end

  put '/' do
    .. frissítünk valamit ..
  end

  delete '/' do
    .. törlünk valamit ..
  end

Az útvonalak illeszkedését a rendszer a definiálásuk sorrendjében
ellenőrzi. Sorrendben mindig az első illeszkedő útvonalhoz tartozó metódus kerül
meghívásra.

Az útvonalminták tartalmazhatnak paramétereket is, melyeket a <tt>params</tt>
hash-ből érhetünk el:

  get '/hello/:name' do
    # illeszkedik a "GET /hello/foo" és a "GET /hello/bar" útvonalakra
    # ekkor params[:name] értéke 'foo' vagy 'bar' lesz
    "Helló #{params[:name]}!"
  end

A kulcsszavas argumentumokat (named parameters) blokk paraméterek útján
is el tudod érni:

  get '/hello/:name' do |n|
    "Helló #{n}!"
  end

Az útvonalmintákban szerepelhetnek joker paraméterek is, melyeket a 
<tt>params[:splat]</tt> tömbön keresztül tudunk elérni.

  get '/say/*/to/*' do
    # illeszkedik a /say/hello/to/world mintára
    params[:splat] # => ["hello", "world"]
  end

  get '/download/*.*' do
    # illeszkedik a /download/path/to/file.xml mintára
    params[:splat] # => ["path/to/file", "xml"]
  end

Reguláris kifejezéseket is felvehetünk az útvonalba:

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

Vagy blokk paramétereket:

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

Az útvonalak azonban számos egyéb illeszkedési feltétel szerint is
tervezhetők, így például az user agent karakterláncot alapul véve:

  get '/foo', :agent => /Songbird (\d\.\d)[\d\/]*?/ do
    "A Songbird #{params[:agent][0]} verzióját használod"
  end

  get '/foo' do
    # illeszkedik az egyéb user agentekre
  end

== Statikus állományok

A statikus fájlok kiszolgálása a <tt>./public</tt> könyvtárból
történik, de természetesen más könyvtárat is megadhatsz erre a célra,
mégpedig a <tt>:public_folder</tt> kapcsoló beállításával:

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

Fontos mgejegyezni, hogy a nyilvános könyvtár neve nem szerepel az URL-ben.
A <tt>./public/css/style.css</tt> fájl az
<tt>http://example.com/css/style.css</tt> URL-en lesz elérhető.

== Nézetek és Sablonok

A sablonfájlokat rendszerint a  <tt>./views</tt> könyvtárba helyezzük, de
itt is lehetőség nyílik egyéb könyvtár használatára:

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

Nagyon fontos észben tartani, hogy a sablononkra mindig szimbólumokkal
hivatkozunk, még akkor is, ha egyéb (ebben az esetben a 
<tt>:'subdir/template'</tt>) könyvtárban tároljuk őket. A renderelő
metódusok minden, nekik közvetlenül átadott karakterláncot megjelenítenek.

=== Haml sablonok

HAML sablonok rendereléséhez szükségünk lesz a haml gem-re vagy könyvtárra:

  # Importáljuk be a haml-t az alkalmazásba
  require 'haml'

  get '/' do
    haml :index
  end

Ez szépen lerendereli a <tt>./views/index.haml</tt> sablont.

A {Haml kapcsolói}[http://haml.hamptoncatlin.com/docs/rdoc/classes/Haml.html]
globálisan is beállíthatók a Sinatra konfigurációi között, lásd az
{Options and Configurations}[http://www.sinatrarb.com/configuration.html] lapot.
A globális beállításokat lehetőségünk van felülírni metódus szinten is.

  set :haml, {:format => :html5 } # az alapértelmezett Haml formátum az :xhtml

  get '/' do
    haml :index, :haml_options => {:format => :html4 } # immár felülírva
  end


=== Erb sablonok

  # Importáljuk be az erb-t az alkalmazásba
  require 'erb'

  get '/' do
    erb :index
  end

Ez a <tt>./views/index.erb</tt> sablont fogja lerenderelni.

=== Builder sablonok

Szükségünk lesz a builder gem-re vagy könyvtárra a builder sablonok
rendereléséhez:

  # Importáljuk be a builder-t az alkalmazásba
  require 'builder'

  get '/' do
    builder :index
  end

Ez pedig a <tt>./views/index.builder</tt> állományt fogja renderelni.

=== Sass sablonok

Sass sablonok használatához szükség lesz a haml gem-re vagy könyvtárra:

  # Be kell importálni a haml, vagy a sass könyvtárat
  require 'sass'

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

Így a <tt>./views/stylesheet.sass</tt> fájl máris renderelhető.

A {Sass kapcsolói}[http://haml.hamptoncatlin.com/docs/rdoc/classes/Sass.html]
globálisan is beállíthatók a Sinatra konfigurációi között, lásd az
{Options and Configurations}[http://www.sinatrarb.com/configuration.html] lapot.
A globális beállításokat lehetőségünk van felülírni metódus szinten is.

  set :sass, {:style => :compact } # az alapértelmezett Sass stílus a :nested

  get '/stylesheet.css' do
    sass :stylesheet, :sass_options => {:style => :expanded } # felülírva
  end


=== Beágyazott sablonok

  get '/' do
    haml '%div.title Helló Világ'
  end

Lerendereli a beágyazott sablon karakerláncát.

=== Változók elérése a sablonokban

A sablonok ugyanabban a kontextusban kerülnek kiértékelésre, mint az
útvonal metódusok (route handlers). Az útvonal metódusokban megadott
változók közvetlenül elérhetőek lesznek a sablonokban:

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

De megadhatod egy lokális változókat tartalmazó explicit hash-ben is:

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

Ezt leginkább akkor érdemes megtenni, ha partial-eket akarunk renderelni
valamely más sablonból.

=== Fájlon belüli sablonok

Sablonokat úgy is megadhatunk, hogy egyszerűen az alkalmazás fájl
végére begépeljük őket:

  require 'rubygems'
  require 'sinatra'

  get '/' do
    haml :index
  end

  __END__

  @@ layout
  %html
    = yield

  @@ index
  %div.title Helló Világ!!!!!

Megjegyzés: azok a fájlon belüli sablonok, amelyek az alkalmazás fájl végére
kerülnek és függnek a sinatra könyvtártól, automatikusan betöltődnek.
Ha ugyanezt más alkalmazásfájlban is szeretnéd megtenni, hívd meg 
a <tt>use_in_file_templates!</tt> metódust az adott fájlban.

=== Kulcsszavas sablonok

Sablonokat végül a felsőszintű <tt>template</tt> metódussal is 
definiálhatunk: 

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

  template :index do
    '%div.title Helló Világ!'
  end

  get '/' do
    haml :index
  end

Ha létezik "layout" nevű sablon, akkor az minden esetben meghívódik, amikor
csak egy sablon renderelésre kerül. A layoutokat ki lehet kapcsolni a
<tt>:layout => false</tt> meghívásával.

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

== Helperek

Használd a felső szintű <tt>helpers</tt> metódust azokhoz a helper
függvényekhez, amiket az útvonal metódusokban és a sablonokban akarsz
használni:

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

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

== Szűrők (filters)

Az előszűrők (before filter) az adott hívás kontextusában minden egyes
kérés alkalmával kiértékelődnek, így módosíthatják a kérést és a
választ egyaránt. A szűrőkbe felvett példányváltozók elérhetőek lesznek
az útvonalakban és a sablonokban is:

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

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

Az utószűrők az egyes kérések után, az adott kérés kontextusában kerülnek
kiértékelésre, így ezek is képesek módosítani a kérést és a választ egyaránt.
Az előszűrőkben és úvonalakban létrehozott példányváltozók elérhetőek lesznek
az utószűrők számára:

  after do
    puts response.status
  end

== Megállítás

Egy kérés szűrőben vagy útvonalban történő azonnal blokkolásához
használd a következő parancsot:

  halt

A megállításkor egy blokktörzset is megadhatsz ...

  halt 'ez fog megjelenni a törzsben'

Vagy állítsd be a HTTP státuszt és a törzset is egyszerre ...

  halt 401, 'menj innen!'

== Passzolás

Az útvonalak továbbadhatják a végrehajtást egy másik útvonalnak 
a <tt>pass</tt> függvényhívással:

  get '/guess/:who' do
    pass unless params[:who] == 'Frici'
    "Elkaptál!"
  end

  get '/guess/*' do
    "Elhibáztál!"
  end

Az útvonal blokkja azonnal kilép és átadja a vezérlést a következő
illeszkedő útvonalnak. Ha nem talál megfelelő útvonalat, a Sinatra
egy 404-es hibával tér vissza.

== Beállítások

Csak indításkor, de minden környezetre érvényesen fusson le:

  configure do
    ...
  end

Csak akkor fusson le, ha a környezet (a RACK_ENV környezeti változóban)
<tt>:production</tt>-ra van állítva:

  configure :production do
    ...
  end

Csak akkor fusson le, ha a környezet <tt>:production</tt> vagy <tt>:test</tt>:

  configure :production, :test do
    ...
  end

== Hibakezelés

A hibakezelők ugyanabban a kontextusban futnak le, mint az útvonalak és
előszűrők, ezért számukra is elérhetőek mindazok a könyvtárak, amelyek
az utóbbiak rendelkezésére is állnak; így például a <tt>haml</tt>, 
az <tt>erb</tt>, a <tt>halt</tt> stb.

=== Nem található

Amikor a <tt>Sinatra::NotFound</tt> kivétel fellép, vagy a válasz HTTP
státuszkódja 404-es, mindig a <tt>not_found</tt> metódus hívódik meg.

  not_found do
    'Sehol sem találom, amit keresel'
  end

=== Hiba

Az +error+ metódus hívódik meg olyankor, amikor egy útvonal, blokk vagy
előszűrő kivételt vált ki. A kivétel objektum lehívható a
<tt>sinatra.error</tt> Rack változótól:

  error do
    'Elnézést, de valami szörnyű hiba lépett fel - ' + env['sinatra.error'].name
  end

Egyéni hibakezelés:

  error MyCustomError do
    'Szóval az van, hogy...' + env['sinatra.error'].message
  end

És amikor fellép:

  get '/' do
    raise MyCustomError, 'valami nem stimmel!'
  end

Ez fog megjelenni:

  Szóval az van, hogy... valami nem stimmel!

A Sinatra speciális <tt>not_found</tt> és <tt>error</tt> hibakezelőket
használ, amikor a futtatási környezet fejlesztői módba van kapcsolva.

== Mime típusok

A <tt>send_file</tt> metódus használatakor, vagy statikus fájlok
kiszolgálásakor előfordulhat, hogy a Sinatra nem ismeri fel a fájlok
mime típusát. Ilyenkor használd a +mime_type+ kapcsolót a fájlkiterjesztés
bevezetéséhez:

  mime_type :foo, 'text/foo'

== Rack Middleware

A Sinatra egy Ruby keretrendszerek számára kifejlesztett egyszerű és szabványos
interfészre, a {Rack}[http://rack.rubyforge.org/] -re épül. A Rack fejlesztői 
szempontból egyik legérdekesebb jellemzője, hogy támogatja az úgynevezett
"middleware" elnevezésű komponenseket, amelyek beékelődnek a szerver és az
alkalmazás közé, így képesek megfigyelni és/vagy módosítani a HTTP 
kéréseket és válaszokat. Segítségükkel különféle, egységesen működő
funkciókat építhetünk be rendszerünkbe.

A Sinatra keretrendszerben gyerekjáték a Rack middleware-ek behúzása a
+use+ metódus segítségével:

  require 'sinatra'
  require 'my_custom_middleware'

  use Rack::Lint
  use MyCustomMiddleware

  get '/hello' do
    'Helló Világ'
  end

A +use+ metódus szemantikája megegyezik a 
Rack::Builder[http://rack.rubyforge.org/doc/classes/Rack/Builder.html] DSL-ben
használt +use+ metóduséval (az említett DSL-t leginkább rackup állományokban
használják). Hogy egy példát említsünk, a +use+ metódus elfogad 
változókat és blokkokat egyaránt, akár kombinálva is ezeket:

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

A Rack terjesztéssel egy csomó alap middleware komponens is érkezik,
amelyekkel a naplózás, URL útvonalak megadása, autentikáció és 
munkamenet-kezelés könnyen megvalósítható. A Sinatra ezek közül elég
sokat automatikusan felhasznál a beállításoktól függően, így ezek
explicit betöltésével (+use+) nem kell bajlódnod.

== Tesztelés

Sinatra teszteket bármely Rack alapú tesztelő könyvtárral vagy
keretrendszerrel készíthetsz. Mi a {Rack::Test}[http://gitrdoc.com/brynary/rack-test]
könyvtárat ajánljuk:

  require 'my_sinatra_app'
  require 'rack/test'

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

    def app
      Sinatra::Application
    end

    def test_my_default
      get '/'
      assert_equal 'Helló Világ!', last_response.body
    end

    def test_with_params
      get '/meet', :name => 'Frici'
      assert_equal 'Helló Frici!', last_response.body
    end

    def test_with_rack_env
      get '/', {}, 'HTTP_USER_AGENT' => 'Songbird'
      assert_equal "Songbird-öt használsz!", last_response.body
    end
  end

Megjegyzés: A beépített Sinatra::Test és Sinatra::TestHarness osztályok
a 0.9.2-es kiadástól kezdve elavultnak számítanak.

== Sinatra::Base - Middleware-ek, könyvtárak és moduláris alkalmazások

Az alkalmazást felső szinten építeni megfelelhet mondjuk egy kisebb
app esetén, ám kifejezetten károsnak bizonyulhat olyan komolyabb,
újra felhasználható komponensek készítésekor, mint például egy Rack
middleware, Rails metal, egyszerűbb kiszolgáló komponenssel bíró
könyvtárak vagy éppen Sinatra kiterjesztések. A felső szintű DSL
bepiszkítja az Objektum névteret, ráadásul kisalkalmazásokra szabott
beállításokat feltételez (így például egyetlen alkalmazásfájl, ./public
és ./views könyvtár meglétét, naplózást, kivételkezelő oldalt stb.).
Itt jön a képbe a Sinatra::Base osztály:

  require 'sinatra/base'

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

    get '/' do
      'Helló Világ!'
    end
  end

A MyApp osztály immár önálló Rack komponensként, mondjuk Rack middleware-ként
vagy alkalmazásként, esetleg Rails metal-ként is tud működni. Közvetlenül
használhatod (+use+) vagy futtathatod (+run+) az osztályodat egy rackup
konfigurációs állományban (+config.ru+), vagy egy szerverkomponenst
tartalmazó könyvtár vezérlésekor:

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

A Sinatra::Base gyermekosztályaiban elérhető metódusok egyúttal a felső
szintű DSL-en keresztül is hozzáférhetők. A legtöbb felső szintű
alkalmazás átalakítható Sinatra::Base alapú komponensekké két lépésben:

* A fájlban nem a +sinatra+, hanem a +sinatra/base+ osztályt kell
  beimportálni, mert egyébként az összes Sinatra DSL metódus a fő
  névtérbe kerül.
* Az alkalmazás útvonalait, hibakezelőit, szűrőit és beállításait
  a Sinatra::Base osztály gyermekosztályaiban kell megadni.

A +Sinatra::Base+ osztály igazából egy üres lap: a legtöbb funkció
alapból ki van kapcsolva, beleértve a beépített szervert is. A 
beállításokkal és az egyes kapcsolók hatásával az
{Options and Configuration}[http://sinatra.github.com/configuration.html] lap
foglalkozik.

Széljegyzet: A Sinatra felső szintű DSL-je egy egyszerű delegációs
rendszerre épül. A Sinatra::Application osztály - a Sinatra::Base egy
speciális osztályaként - fogadja az összes :get, :put, :post,
:delete, :before, :error, :not_found, :configure és :set üzenetet,
ami csak a felső szintre beérkezik. Érdemes utánanézned a kódban,
miképp {kerül be}[http://github.com/sinatra/sinatra/blob/master/lib/sinatra/main.rb#L25]
a {Sinatra::Delegator mixin}[http://github.com/sinatra/sinatra/blob/master/lib/sinatra/base.rb#L1064]
a fő névtérbe.

== Parancssori lehetőségek

Sinatra alkalmazásokat közvetlenül futtathatunk:

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

Az alábbi kapcsolókat ismeri fel a rendszer:

  -h # segítség
  -p # a port beállítása (alapértelmezés szerint ez a 4567-es)
  -e # a környezet beállítása (alapértelmezés szerint ez a development)
  -s # a rack szerver/handler beállítása (alapértelmezetten ez a thin)
  -x # a mutex lock bekapcsolása (alapértelmezetten ki van kapcsolva)

== Fejlesztői változat

Ha a Sinatra legfrissebb, fejlesztői változatát szeretnéd használni,
készíts egy helyi másolatot és indítsd az alkalmazásodat úgy,
hogy a <tt>sinatra/lib</tt> könyvtár elérhető legyen a 
<tt>LOAD_PATH</tt>-on:

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

De hozzá is adhatod a <tt>sinatra/lib</tt> könyvtárat a <tt>LOAD_PATH</tt>-hoz
az alkalmazásodban:

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

  get '/about' do
    "A következő változatot futtatom " + Sinatra::VERSION
  end

A Sinatra frissítését később így végezheted el:

  cd myproject/sinatra
  git pull

== További információk

* {A projekt weboldala}[http://sinatra.github.com/] - Kiegészítő dokumentáció,
  hírek, hasznos linkek
* {Közreműködés}[http://sinatra.github.com/contributing.html] - Hibát találtál?
  Segítségre van szükséged? Foltot küldenél be?
* {Lighthouse}[http://sinatra.lighthouseapp.com] - Hibakövetés és kiadások
* {Twitter}[http://twitter.com/sinatra]
* {Levelezőlista}[http://groups.google.com/group/sinatrarb]
* {IRC: #sinatra}[irc://chat.freenode.net/#sinatra] a http://freenode.net címen