Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 646 lines (447 sloc) 17.525 kb
aed84d9b » lucianosousa
2010-11-17 Add Portugese translation.
1 = Sinatra
2
3 Sinatra é uma DSL para criar rapidamente aplicações web em Ruby com o mínimo de
4 esforço:
5
6 # minhaapp.rb
7 require 'rubygems'
8 require 'sinatra'
9 get '/' do
10 'Olá Mundo!'
11 end
12
13 Instale a gem e execute como:
14
15 sudo gem install sinatra
16 ruby minhaapp.rb
17
18 Acesse em: http://localhost:4567
19
20 == Rotas
21
22 No Sinatra, uma rota é um metodo HTTP associado a uma URL correspondente padrão.
23 Cada rota é associada a um bloco:
24
25 get '/' do
26 .. mostrando alguma coisa ..
27 end
28
29 post '/' do
30 .. criando alguma coisa ..
31 end
32
33 put '/' do
34 .. atualizando alguma coisa ..
35 end
36
37 delete '/' do
38 .. apagando alguma coisa ..
39 end
40
41 Rotas são encontradas na ordem em que são definidas. A primeira rota que
42 é encontrada invoca o pedido.
43
44 Padrões de rota podem incluir parâmetros nomeados, acessáveis via a
45 hash <tt>params</tt>:
46
47 get '/ola/:nome' do
48 # corresponde a "GET /ola/foo" e "GET /ola/bar"
49 # params[:nome] é 'foo' ou 'bar'
50 "Olá #{params[:nome]}!"
51 end
52
53 Você também pode acessar parâmetros nomeados via bloco de parâmetros:
54
55 get '/ola/:nome' do |n|
56 "Olá #{n}!"
57 end
58
59 Padrões de rota também podem incluir parâmetros splat (ou curingas), acessáveis
60 via o array <tt>params[:splat]</tt>.
61
62 get '/diga/*/para/*' do
63 # corresponde a /diga/ola/para/mundo
64 params[:splat] # => ["ola", "mundo"]
65 end
66
67 get '/download/*.*' do
68 # corresponde a /download/pasta/do/arquivo.xml
69 params[:splat] # => ["pasta/do/arquivo", "xml"]
70 end
71
72 Rotas se correspondem com expressões regulares:
73
74 get %r{/ola/([\w]+)} do
75 "Olá, #{params[:captures].first}!"
76 end
77
78 Ou com um bloco de parâmetro:
79
80 get %r{/ola/([\w]+)} do |c|
81 "Hello, #{c}!"
82 end
83
84 Rotas podem incluir uma variedade de condições correspondes, tal como o agente usuário:
85
86 get '/foo', :agent => /Songbird (\d\.\d)[\d\/]*?/ do
87 "Você está utilizando a versão #{params[:agent][0]} do Songbird."
88 end
89
90 get '/foo' do
91 # Corresponde a um navegador não Songbird
92 end
93
94 == Arquivos estáticos
95
96 Arquivos estáticos são disponibilizados a partir do diretório <tt>./public</tt>. Você pode especificar
97 um local diferente pela opção <tt>:public</tt>
98
99 set :public, File.dirname(__FILE__) + '/estatico'
100
101 Note que o nome do diretório público não é incluido na URL. Um arquivo
102 <tt>./public/css/style.css</tt> é disponibilizado como
103 <tt>http://example.com/css/style.css</tt>.
104
105 == Views / Templates
106
107 Templates presumem-se estar localizados sob o diretório <tt>./views</tt>.
108 Para utilizar um diretório view diferente:
109
110 set :views, File.dirname(__FILE__) + '/modelo'
111
112 Uma coisa importante a ser lembrada é que você sempre tem as referências dos
113 templates como símbolos, mesmo se eles estiverem em um sub-diretório (nesse
114 caso utilize <tt>:'subdir/template'</tt>). Métodos de renderização irão processar
115 qualquer string passada diretamente para elas.
116
117 === Haml Templates
118
119 A gem/biblioteca haml é necessária para renderizar templates HAML:
120
121 ## Você precisa do 'require haml' em sua aplicação.
122 require 'haml'
123
124 get '/' do
125 haml :index
126 end
127
128 Renderiza <tt>./views/index.haml</tt>.
129
130 {Opções Haml}[http://haml-lang.com/docs/yardoc/file.HAML_REFERENCE.html#options]
131 podem ser setadas globalmente através das configurações do sinatra,
132 veja {Opções e Configurações}[http://www.sinatrarb.com/configuration.html],
133 e substitua em uma requisição individual.
134
135 set :haml, {:format => :html5 } # o formato padrão do Haml é :xhtml
136
137 get '/' do
138 haml :index, :haml_options => {:format => :html4 } # substituido
139 end
140
141
142 === Erb Templates
143
144 ## Você precisa do 'require erb' em sua aplicação
145 require 'erb'
146
147 get '/' do
148 erb :index
149 end
150
151 Renderiza <tt>./views/index.erb</tt>
152
153 === Erubis
154
155 A gem/biblioteca erubis é necessária para renderizar templates erubis:
156
157 ## Você precisa do 'require erubis' em sua aplicação.
158 require 'erubis'
159
160 get '/' do
161 erubis :index
162 end
163
164 Renderiza <tt>./views/index.erubis</tt>
165
166 === Builder Templates
167
168 A gem/biblioteca builder é necessária para renderizar templates builder:
169
170 ## Você precisa do 'require builder' em sua aplicação.
171 require 'builder'
172
173 get '/' do
174 content_type 'application/xml', :charset => 'utf-8'
175 builder :index
176 end
177
178 Renderiza <tt>./views/index.builder</tt>.
179
180 === Sass Templates
181
182 A gem/biblioteca sass é necessária para renderizar templates sass:
183
184 ## Você precisa do 'require haml' ou 'require sass' em sua aplicação.
185 require 'sass'
186
187 get '/stylesheet.css' do
188 content_type 'text/css', :charset => 'utf-8'
189 sass :stylesheet
190 end
191
192 Renderiza <tt>./views/stylesheet.sass</tt>.
193
194 {Opções Sass}[http://sass-lang.com/docs/yardoc/file.SASS_REFERENCE.html#options]
195 podem ser setadas globalmente através das configurações do sinatra,
196 veja {Opções e Configurações}[http://www.sinatrarb.com/configuration.html],
197 e substitua em uma requisição individual.
198
199 set :sass, {:style => :compact } # o estilo padrão do Sass é :nested
200
201 get '/stylesheet.css' do
202 content_type 'text/css', :charset => 'utf-8'
203 sass :stylesheet, :style => :expanded # substituido
204 end
205
206 === Less Templates
207
208 A gem/biblioteca less é necessária para renderizar templates Less:
209
210 ## Você precisa do 'require less' em sua aplicação.
211 require 'less'
212
213 get '/stylesheet.css' do
214 content_type 'text/css', :charset => 'utf-8'
215 less :stylesheet
216 end
217
218 Renderiza <tt>./views/stylesheet.less</tt>.
219
220 === Inline Templates
221
222 get '/' do
223 haml '%div.title Olá Mundo'
224 end
225
226 Renderiza a string, em uma linha, no template.
227
228 === Acessando Variáveis nos Templates
229
230 Templates são avaliados dentro do mesmo contexto como manipuladores de rota. Variáveis
231 de instância setadas em rotas manipuladas são diretamente acessadas por templates:
232
233 get '/:id' do
234 @foo = Foo.find(params[:id])
235 haml '%h1= @foo.nome'
236 end
237
238 Ou, especifique um hash explícito para variáveis locais:
239
240 get '/:id' do
241 foo = Foo.find(params[:id])
242 haml '%h1= foo.nome', :locals => { :foo => foo }
243 end
244
245 Isso é tipicamente utilizando quando renderizamos templates como partials dentro
246 de outros templates.
247
248 === Templates Inline
249
250 Templates podem ser definidos no final do arquivo fonte(.rb):
251
252 require 'rubygems'
253 require 'sinatra'
254
255 get '/' do
256 haml :index
257 end
258
259 __END__
260
261 @@ layout
262 %html
263 = yield
264
265 @@ index
266 %div.title Olá Mundo!!!!!
267
268 NOTA: Templates inline definidos no arquivo fonte são automaticamente carregados
269 pelo sinatra. Digite `enable :inline_templates` se você tem templates
270 inline no outro arquivo fonte.
271
272 === Templates nomeados
273
274 Templates também podem ser definidos utilizando o método top-level <tt>template</tt>:
275
276 template :layout do
277 "%html\n =yield\n"
278 end
279
280 template :index do
281 '%div.title Olá Mundo!'
282 end
283
284 get '/' do
285 haml :index
286 end
287
288 Se existir um template com nome "layout", ele será utilizado toda vez que um
289 template for renderizado. Você pode desabilitar layouts passando <tt>:layout => false</tt>.
290
291 get '/' do
292 haml :index, :layout => !request.xhr?
293 end
294
295 == Helpers
296
297 Use o método de alto nível <tt>helpers</tt> para definir métodos auxiliares para utilizar em
298 manipuladores de rotas e modelos:
299
300 helpers do
301 def bar(nome)
302 "#{nome}bar"
303 end
304 end
305
306 get '/:nome' do
307 bar(params[:nome])
308 end
309
310 == Filtros
311
312 Filtros Before são avaliados antes de cada requisição dentro do contexto da requisição
313 e pode modificar a requisição e a reposta. Variáveis de instância setadas nos
314 filtros são acessadas através de rotas e templates:
315
316 before do
317 @nota = 'Oi!'
318 request.path_info = '/foo/bar/baz'
319 end
320
321 get '/foo/*' do
322 @nota #=> 'Oi!'
323 params[:splat] #=> 'bar/baz'
324 end
325
326 Filtros After são avaliados após cada requisição dentro do contexto da
327 requisição e também podem modificar o pedido e a resposta. Variáveis de instância
328 definidas nos filtros before e rotas são acessadas através dos filtros after:
329
330 after do
331 puts response.status
332 end
333
334 Filtros opcionalmente tem um padrão, fazendo com que sejam avaliados somente se o caminho
335 do pedido coincidir com esse padrão:
336
337 before '/protected/*' do
338 authenticate!
339 end
340
341 after '/create/:slug' do |slug|
342 session[:last_slug] = slug
343 end
344
345 == Halting
346
347 Para parar imediatamente uma requisição com um filtro ou rota utilize:
348
349 halt
350
351 Você também pode especificar o status quando parar...
352
353 halt 410
354
355 Ou com corpo de texto...
356
357 halt 'isso será o corpo do texto'
358
359 Ou também...
360
361 halt 401, 'vamos embora!'
362
363 Com cabeçalhos...
364
365 halt 402, {'Content-Type' => 'text/plain'}, 'revanche'
366
367 == Passing
368
369 Uma rota pode processar aposta para a próxima rota correspondente usando <tt>pass</tt>:
370
371 get '/adivinhar/:quem' do
372 pass unless params[:quem] == 'Frank'
373 'Você me pegou!'
374 end
375
376 get '/adivinhar/*' do
377 'Você falhou!'
378 end
379
380 O bloqueio da rota é imediatamente encerrado e o controle continua com a próxima
381 rota de parâmetro. Se o parâmetro da rota não for encontrado, um 404 é retornado.
382
383 == Configuração
384
385 Rodando uma vez, na inicialização, em qualquer ambiente:
386
387 configure do
388 ...
389 end
390
391 Rodando somente quando o ambiente (RACK_ENV environment variável) é setado para
392 <tt>:production</tt>:
393
394 configure :production do
395 ...
396 end
397
398 Rodando quando o ambiente é setado para <tt>:production</tt> ou
399 <tt>:test</tt>:
400
401 configure :production, :test do
402 ...
403 end
404
405 == Tratamento de Erros
406
407 Tratamento de erros rodam dentro do mesmo contexto como rotas e filtros before, o
408 que significa que você pega todos os presentes que tem para oferecer, como <tt>haml</tt>, <tt>erb</tt>,
409 <tt>halt</tt>, etc.
410
411 === Não Encontrado
412
413 Quando um <tt>Sinatra::NotFound</tt> exception é levantado, ou o código de status
414 da reposta é 404, o <tt>not_found</tt> manipulador é invocado:
415
416 not_found do
417 'Isto está longe de ser encontrado'
418 end
419
420 === Erro
421
422 O manipulador +error+ é invocado toda a vez que uma exceção é lançada a partir de
423 um bloco de rota ou um filtro. O objeto da exceção pode ser obtido a partir da variável
424 Rack <tt>sinatra.error</tt>:
425
426 error do
427 'Desculpe, houve um erro desagradável - ' + env['sinatra.error'].name
428 end
429
430 Erros customizados:
431
432 error MeuErroCustomizado do
433 'Então que aconteceu foi...' + request.env['sinatra.error'].message
434 end
435
436 Então, se isso acontecer:
437
438 get '/' do
439 raise MeuErroCustomizado, 'alguma coisa ruim'
440 end
441
442 Você receberá isso:
443
444 Então que aconteceu foi... alguma coisa ruim
445
446 Alternativamente, você pode instalar manipulador de erro para um código de status:
447
448 error 403 do
449 'Accesso negado'
450 end
451
452 get '/secreto' do
453 403
454 end
455
456 Ou um range:
457
458 error 400..510 do
459 'Boom'
460 end
461
462 O Sinatra instala os manipuladores especiais <tt>not_found</tt> e <tt>error</tt> quando
463 roda sobre o ambiente de desenvolvimento.
464
465 == Mime Types
466
467 Quando utilizamos <tt>send_file</tt> ou arquivos estáticos você pode ter mime types Sinatra
468 não entendidos. Use +mime_type+ para registrar eles por extensão de arquivos:
469
470 mime_type :foo, 'text/foo'
471
472 Você também pode utilizar isto com o helper +content_type+:
473
474 content_type :foo
475
476 == Middleware Rack
477
478 O Sinatra roda no Rack[http://rack.rubyforge.org/], uma interface padrão
479 mínima para frameworks web em Ruby. Um das capacidades mais interessantes do Rack
480 para desenvolver aplicativos é suporte a "middleware" -- componentes que ficam
481 entre o servidor e sua aplicação monitorando e/ou manipulando o request/response do
482 HTTP para prover vários tipos de funcionalidades comuns.
483
484 O Sinatra faz construtores pipelines do middleware Rack facilmente em um nível superior
485 utilizando o método +use+:
486
487 require 'sinatra'
488 require 'meu_middleware_customizado'
489
490 use Rack::Lint
491 use MeuMiddlewareCustomizado
492
493 get '/ola' do
494 'Olá mundo'
495 end
496
497 A semântica de +use+ é idêntica aquela definida para a DSL
498 Rack::Builder[http://rack.rubyforge.org/doc/classes/Rack/Builder.html]
499 (mais frequentemente utilizada para arquivos rackup). Por exemplo, o método +use+
500 aceita múltiplos argumentos/variáveis bem como blocos:
501
502 use Rack::Auth::Basic do |usuario, senha|
503 usuario == 'admin' && senha == 'secreto'
504 end
505
506 O Rack é distribuido com uma variedade de middleware padrões para logs,
507 debugs, rotas de URL, autenticação, e manipuladores de sessão. Sinatra utilizada
508 muitos desses componentes automaticamente baseando sobre configuração, então, tipicamente
509 você não tem +use+ explicitamente.
510
511 == Testando
512
513 Testes no Sinatra podem ser escritos utilizando qualquer biblioteca ou framework
514 de teste baseados no Rack. {Rack::Test}[http://gitrdoc.com/brynary/rack-test] é
515 recomendado:
516
517 require 'minha_aplicacao_sinatra'
518 require 'rack/test'
519
520 class MinhaAplicacaoTeste < Test::Unit::TestCase
521 include Rack::Test::Methods
522
523 def app
524 Sinatra::Application
525 end
526
527 def meu_test_default
528 get '/'
529 assert_equal 'Ola Mundo!', last_response.body
530 end
531
532 def teste_com_parametros
533 get '/atender', :name => 'Frank'
534 assert_equal 'Olá Frank!', last_response.bodymeet
535 end
536
537 def test_com_ambiente_rack
538 get '/', {}, 'HTTP_USER_AGENT' => 'Songbird'
539 assert_equal "Você está utilizando o Songbird!", last_response.body
540 end
541 end
542
543 NOTA: Os módulos de classe embutidos Sinatra::Test e Sinatra::TestHarness
544 são depreciados na versão 0.9.2.
545
546 == Sinatra::Base - Middleware, Bibliotecas e aplicativos modulares
547
548 Definir sua aplicação em um nível superior de trabalho funciona bem para micro aplicativos, mas tem
549 consideráveis incovenientes na construção de componentes reutilizáveis como um middleware Rack,
550 metal Rails, bibliotecas simples como um componente de servidor, ou
551 mesmo extensões Sinatra. A DSL de nível superior polui o espaço do objeto
552 e assume um estilo de configuração de micro aplicativos (exemplo: uma simples arquivo de
553 aplicação, diretórios ./public e ./views, logs, página de detalhes de exceção,
554 etc.). É onde o Sinatra::Base entra em jogo:
555
556 require 'sinatra/base'
557
558 class MinhaApp < Sinatra::Base
559 set :sessions, true
560 set :foo, 'bar'
561
562 get '/' do
563 'Ola mundo!'
564 end
565 end
566
567 A classe MinhaApp é um componente Rack independente que pode agir como um
568 middleware Rack, uma aplicação Rack, ou metal Rails. Você pode +utilizar+ ou
569 +executar+ esta classe com um arquivo rackup +config.ru+; ou, controlar um componente
570 de servidor fornecendo como biblioteca:
571
572 MinhaApp.run! :host => 'localhost', :port => 9090
573
574 Os métodos disponíveis para subclasses Sinatra::Base são exatamente como aqueles
575 disponíveis via a DSL de nível superior. Aplicações de nível mais alto podem ser convertidas para
576 componentes Sinatra::Base com duas modificações:
577
578 * Seu arquivo deve requerer +sinatra/base+ ao invés de +sinatra+;
579 outra coisa, todos os métodos DSL do Sinatra são importados para o espaço
580 principal.
581 * Coloque as rotas da sua aplicação, manipuladores de erro, filtros e opções na subclasse de
582 um Sinatra::Base.
583
584 +Sinatra::Base+ é um quadro branco. Muitas opções são desabilitadas por padrão,
585 incluindo o servidor embutido. Veja {Opções e Configurações}[http://sinatra.github.com/configuration.html]
586 para detalhes de opções disponíveis e seus comportamentos.
587
588 SIDEBAR: A DSL de alto nível do Sinatra é implementada utilizando um simples sistema de
589 delegação. A classe +Sinatra::Application+ -- uma subclasse especial da
590 Sinatra::Base -- recebe todos os :get, :put, :post, :delete, :before,
591 :error, :not_found, :configure, e :set messages enviados para o
592 alto nível. Dê uma olhada no código você mesmo: aqui está o
593 {Sinatra::Delegator mixin}[http://github.com/sinatra/sinatra/blob/ceac46f0bc129a6e994a06100aa854f606fe5992/lib/sinatra/base.rb#L1128]
594 sendo {incluido dentro de um espaço principal}[http://github.com/sinatra/sinatra/blob/ceac46f0bc129a6e994a06100aa854f606fe5992/lib/sinatra/main.rb#L28]
595
596 == Linha de Comando
597
598 Aplicações Sinatra podem ser executadas diretamente:
599
600 ruby minhaapp.rb [-h] [-x] [-e AMBIENTE] [-p PORTA] [-o HOST] [-s SERVIDOR]
601
602 As opções são:
603
604 -h # ajuda
605 -p # define a porta (padrão é 4567)
606 -o # define o host (padrão é 0.0.0.0)
607 -e # define o ambiente (padrão é development)
608 -s # especifica o servidor/manipulador rack (padrão é thin)
609 -x # ativa o bloqueio (padrão é desligado)
610
611 == A última versão
612
613 Se você gostaria de utilizar o código da última versão do Sinatra, crie um clone
614 local e execute sua aplicação com o diretório <tt>sinatra/lib</tt> no
615 <tt>LOAD_PATH</tt>:
616
617 cd minhaapp
618 git clone git://github.com/sinatra/sinatra.git
619 ruby -I sinatra/lib minhaapp.rb
620
621 Alternativamente, você pode adicionar o diretório do <tt>sinatra/lib</tt> no
622 <tt>LOAD_PATH</tt> do seu aplicativo:
623
624 $LOAD_PATH.unshift File.dirname(__FILE__) + '/sinatra/lib'
625 require 'rubygems'
626 require 'sinatra'
627
628 get '/sobre' do
629 "Estou rodando a versão" + Sinatra::VERSION
630 end
631
632 Para atualizar o código do Sinatra no futuro:
633
634 cd meuprojeto/sinatra
635 git pull
636
637 == Mais
638
639 * {Website do Projeto}[http://www.sinatrarb.com/] - Documentação adicional,
640 novidades e links para outros recursos.
641 * {Contribuir}[http://www.sinatrarb.com/contributing] - Encontrar um bug? Precisa
642 de ajuda? Tem um patch?
643 * {Acompanhar Questões}[http://github.com/sinatra/sinatra/issues]
644 * {Twitter}[http://twitter.com/sinatra]
645 * {Lista de Email}[http://groups.google.com/group/sinatrarb/topics]
646 * {IRC: #sinatra}[irc://chat.freenode.net/#sinatra] em http://freenode.net
Something went wrong with that request. Please try again.