Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 647 lines (447 sloc) 17.575 kb
e43ec7e Filipe Dobreira Added PT-PT README file based off the existing PT-BR one.
filp authored
1 = Sinatra
2 <i>Atenção: Este documento é apenas uma tradução da versão em inglês e pode estar desatualizado.</i>
3
4 Sinatra é uma DSL para criar rapidamente aplicações web em Ruby com o mínimo de
5 esforço:
6
7 # minhaapp.rb
8 require 'rubygems'
9 require 'sinatra'
10 get '/' do
11 'Olá Mundo!'
12 end
13
14 Instale a gem e execute com:
15
16 sudo gem install sinatra
17 ruby minhaapp.rb
18
19 Aceda em: http://localhost:4567
20
21 == Rotas
22
23 No Sinatra, uma rota é um metodo HTTP associado a uma URL correspondente padrão.
24 Cada rota é associada a um bloco:
25
26 get '/' do
27 .. mostrar algo ..
28 end
29
30 post '/' do
31 .. criar algo ..
32 end
33
34 put '/' do
35 .. atualizar algo ..
36 end
37
38 delete '/' do
39 .. apagar algo ..
40 end
41
42 Rotas são encontradas na ordem em que são definidas. A primeira rota que
43 é encontrada invoca o pedido.
44
45 Padrões de rota podem incluir parâmetros nomeados, acessíveis através da
46 hash <tt>params</tt>:
47
48 get '/ola/:nome' do
49 # corresponde a "GET /ola/foo" e "GET /ola/bar"
50 # params[:nome] é 'foo' ou 'bar'
51 "Olá #{params[:nome]}!"
52 end
53
54 Pode também aceder a parâmetros nomeados através do bloco de parâmetros:
55
56 get '/ola/:nome' do |n|
57 "Olá #{n}!"
58 end
59
60 Padrões de rota podem também incluir parâmetros splat (asteriscos), acessíveis
61 através do array <tt>params[:splat]</tt>.
62
63 get '/diga/*/ao/*' do
64 # corresponde a /diga/ola/ao/mundo
65 params[:splat] # => ["ola", "mundo"]
66 end
67
68 get '/download/*.*' do
69 # corresponde a /download/pasta/do/arquivo.xml
70 params[:splat] # => ["pasta/do/arquivo", "xml"]
71 end
72
73 Rotas correspondem-se com expressões regulares:
74
75 get %r{/ola/([\w]+)} do
76 "Olá, #{params[:captures].first}!"
77 end
78
79 Ou com um bloco de parâmetro:
80
81 get %r{/ola/([\w]+)} do |c|
82 "Olá, #{c}!"
83 end
84
85 Rotas podem incluir uma variedade de condições correspondentes, por exemplo, o agente usuário:
86
87 get '/foo', :agent => /Songbird (\d\.\d)[\d\/]*?/ do
88 "Você está a utilizar a versão #{params[:agent][0]} do Songbird."
89 end
90
91 get '/foo' do
92 # Corresponde a um navegador não Songbird
93 end
94
95 == Arquivos estáticos
96
97 Arquivos estáticos são disponibilizados a partir do directório <tt>./public</tt>. Você pode especificar
d1ab58d Konstantin Haase rename public to public_folder, fixes #301
rkh authored
98 um local diferente através da opção <tt>:public_folder</tt>
e43ec7e Filipe Dobreira Added PT-PT README file based off the existing PT-BR one.
filp authored
99
d1ab58d Konstantin Haase rename public to public_folder, fixes #301
rkh authored
100 set :public_folder, File.dirname(__FILE__) + '/estatico'
e43ec7e Filipe Dobreira Added PT-PT README file based off the existing PT-BR one.
filp authored
101
102 Note que o nome do directório público não é incluido no URL. Um arquivo
103 <tt>./public/css/style.css</tt> é disponibilizado como
104 <tt>http://example.com/css/style.css</tt>.
105
106 == Views / Templates
107
108 Templates presumem-se estar localizados sob o directório <tt>./views</tt>.
109 Para utilizar um directório de views diferente:
110
111 set :views, File.dirname(__FILE__) + '/modelo'
112
113 Uma coisa importante a ser lembrada é que você sempre tem as referências dos
114 templates como símbolos, mesmo se eles estiverem num sub-directório (nesse
115 caso utilize <tt>:'subdir/template'</tt>). Métodos de renderização irão processar
116 qualquer string passada directamente para elas.
117
118 === Haml Templates
119
120 A gem/biblioteca haml é necessária para renderizar templates HAML:
121
122 # É necessário requerir 'haml' na aplicação.
123 require 'haml'
124
125 get '/' do
126 haml :index
127 end
128
129 Renderiza <tt>./views/index.haml</tt>.
130
131 {Opções Haml}[http://haml-lang.com/docs/yardoc/file.HAML_REFERENCE.html#options]
132 podem ser definidas globalmente através das configurações do sinatra,
133 veja {Opções e Configurações}[http://www.sinatrarb.com/configuration.html],
134 e substitua em uma requisição individual.
135
136 set :haml, {:format => :html5 } # o formato padrão do Haml é :xhtml
137
138 get '/' do
139 haml :index, :haml_options => {:format => :html4 } # substituido
140 end
141
142
143 === Erb Templates
144
145 # É necessário requerir 'erb' na aplicação.
146 require 'erb'
147
148 get '/' do
149 erb :index
150 end
151
152 Renderiza <tt>./views/index.erb</tt>
153
154 === Erubis
155
156 A gem/biblioteca erubis é necessária para renderizar templates erubis:
157
158 # É necessário requerir 'erubis' na aplicação.
159 require 'erubis'
160
161 get '/' do
162 erubis :index
163 end
164
165 Renderiza <tt>./views/index.erubis</tt>
166
167 === Builder Templates
168
169 A gem/biblioteca builder é necessária para renderizar templates builder:
170
171 # É necessário requerir 'builder' na aplicação.
172 require 'builder'
173
174 get '/' do
175 content_type 'application/xml', :charset => 'utf-8'
176 builder :index
177 end
178
179 Renderiza <tt>./views/index.builder</tt>.
180
181 === Sass Templates
182
183 A gem/biblioteca sass é necessária para renderizar templates sass:
184
185 # É necessário requerir 'haml' ou 'sass' na aplicação.
186 require 'sass'
187
188 get '/stylesheet.css' do
189 content_type 'text/css', :charset => 'utf-8'
190 sass :stylesheet
191 end
192
193 Renderiza <tt>./views/stylesheet.sass</tt>.
194
195 {Opções Sass}[http://sass-lang.com/docs/yardoc/file.SASS_REFERENCE.html#options]
196 podem ser definidas globalmente através das configurações do sinatra,
197 veja {Opções e Configurações}[http://www.sinatrarb.com/configuration.html],
198 e substitua em uma requisição individual.
199
200 set :sass, {:style => :compact } # o estilo padrão do Sass é :nested
201
202 get '/stylesheet.css' do
203 content_type 'text/css', :charset => 'utf-8'
204 sass :stylesheet, :style => :expanded # substituido
205 end
206
207 === Less Templates
208
209 A gem/biblioteca less é necessária para renderizar templates Less:
210
211 # É necessário requerir 'less' na aplicação.
212 require 'less'
213
214 get '/stylesheet.css' do
215 content_type 'text/css', :charset => 'utf-8'
216 less :stylesheet
217 end
218
219 Renderiza <tt>./views/stylesheet.less</tt>.
220
221 === Templates Inline
222
223 get '/' do
224 haml '%div.title Olá Mundo'
225 end
226
227 Renderiza a string, em uma linha, no template.
228
229 === Acedendo a Variáveis nos Templates
230
231 Templates são avaliados dentro do mesmo contexto que os manipuladores de rota. Variáveis
232 de instância definidas em rotas manipuladas são directamente acedidas por templates:
233
234 get '/:id' do
235 @foo = Foo.find(params[:id])
236 haml '%h1= @foo.nome'
237 end
238
239 Ou, especifique um hash explícito para variáveis locais:
240
241 get '/:id' do
242 foo = Foo.find(params[:id])
243 haml '%h1= foo.nome', :locals => { :foo => foo }
244 end
245
246 Isso é tipicamente utilizado quando renderizamos templates parciais (partials) dentro
247 de outros templates.
248
249 === Templates Inline
250
251 Templates podem ser definidos no final do arquivo fonte(.rb):
252
253 require 'rubygems'
254 require 'sinatra'
255
256 get '/' do
257 haml :index
258 end
259
260 __END__
261
262 @@ layout
263 %html
264 = yield
265
266 @@ index
267 %div.title Olá Mundo!!!!!
268
269 NOTA: Templates inline definidos no arquivo fonte são automaticamente carregados
270 pelo sinatra. Digite `enable :inline_templates` se tem templates inline no outro
271 arquivo fonte.
272
273 === Templates nomeados
274
275 Templates também podem ser definidos utilizando o método top-level <tt>template</tt>:
276
277 template :layout do
278 "%html\n =yield\n"
279 end
280
281 template :index do
282 '%div.title Olá Mundo!'
283 end
284
285 get '/' do
286 haml :index
287 end
288
289 Se existir um template com nome "layout", ele será utilizado sempre que um
290 template for renderizado. Pode desactivar layouts usando <tt>:layout => false</tt>.
291
292 get '/' do
293 haml :index, :layout => !request.xhr?
294 end
295
296 == Helpers
297
298 Use o método de alto nível <tt>helpers</tt> para definir métodos auxiliares para utilizar em
299 manipuladores de rotas e modelos:
300
301 helpers do
302 def bar(nome)
303 "#{nome}bar"
304 end
305 end
306
307 get '/:nome' do
308 bar(params[:nome])
309 end
310
311 == Filtros
312
313 Filtros Before são avaliados antes de cada requisição dentro do contexto da requisição
314 e podem modificar a requisição e a reposta. Variáveis de instância definidas nos
315 filtros são acedidas através de rotas e templates:
316
317 before do
318 @nota = 'Olá!'
319 request.path_info = '/foo/bar/baz'
320 end
321
322 get '/foo/*' do
323 @nota #=> 'Olá!'
324 params[:splat] #=> 'bar/baz'
325 end
326
327 Filtros After são avaliados após cada requisição dentro do contexto da
328 requisição e também podem modificar o pedido e a resposta. Variáveis de instância
329 definidas nos filtros before e rotas são acedidas através dos filtros after:
330
331 after do
332 puts response.status
333 end
334
335 Filtros opcionalmente têm um padrão, fazendo com que sejam avaliados somente se o caminho
336 do pedido coincidir com esse padrão:
337
338 before '/protected/*' do
339 autenticar!
340 end
341
342 after '/create/:slug' do |slug|
343 session[:last_slug] = slug
344 end
345
346 == Halting
347
348 Para parar imediatamente uma requisição dentro de um filtro ou rota utilize:
349
350 halt
351
352 Pode também especificar o status ao parar...
353
354 halt 410
355
356 Ou com um corpo de texto...
357
358 halt 'isto será o corpo de texto'
359
360 Ou também...
361
362 halt 401, 'vamos embora!'
363
364 Com cabeçalhos...
365
366 halt 402, {'Content-Type' => 'text/plain'}, 'revanche'
367
368 == Passing
369
370 Dentro de uma rota, pode passar para a próxima rota correspondente usando <tt>pass</tt>:
371
372 get '/adivinhar/:quem' do
373 pass unless params[:quem] == 'Frank'
374 'Apanhaste-me!'
375 end
376
377 get '/adivinhar/*' do
378 'Falhaste!'
379 end
380
381 O bloqueio da rota é imediatamente encerrado e o controle continua com a próxima
382 rota de parâmetro. Se o parâmetro da rota não for encontrado, um 404 é retornado.
383
384 == Configuração
385
386 Correndo uma vez, na inicialização, em qualquer ambiente:
387
388 configure do
389 ...
390 end
391
392 Correndo somente quando o ambiente (RACK_ENV environment variável) é definido para
393 <tt>:production</tt>:
394
395 configure :production do
396 ...
397 end
398
399 Correndo quando o ambiente é definido para <tt>:production</tt> ou
400 <tt>:test</tt>:
401
402 configure :production, :test do
403 ...
404 end
405
406 == Lidar com Erros
407
408 Lida-se com erros no mesmo contexto das rotas e filtros before, o que signifca que
409 <tt>haml</tt>, <tt>erb</tt>, etc, estão disponíveis.
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 manipulador <tt>not_found</tt> é invocado:
415
416 not_found do
417 'Isto está longe de ser encontrado'
418 end
419
420 === Erro
421
422 O manipulador +error+ é invocado sempre que uma exceção é lançada a partir de
423 um bloco de rota ou um filtro. O objecto da exceção pode ser obtido a partir da variável
424 Rack <tt>sinatra.error</tt>:
425
426 error do
427 'Peço desculpa, houve um erro desagradável - ' + env['sinatra.error'].name
428 end
429
430 Erros personalizados:
431
432 error MeuErroPersonalizado do
66f1256 Konstantin Haase env is accessable directly, no need to use request.env
rkh authored
433 'O que aconteceu foi...' + env['sinatra.error'].message
e43ec7e Filipe Dobreira Added PT-PT README file based off the existing PT-BR one.
filp authored
434 end
435
436 Então, se isso acontecer:
437
438 get '/' do
439 raise MeuErroPersonalizado, 'alguma coisa desagradável'
440 end
441
442 O resultado será:
443
444 O que aconteceu foi...alguma coisa desagradável
445
446 Alternativamente, pode definir um 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 (alcance):
457
458 error 400..510 do
459 'Boom'
460 end
461
462 O Sinatra define os manipuladores especiais <tt>not_found</tt> e <tt>error</tt> quando
463 corre no ambiente de desenvolvimento.
464
465 == Mime Types
466
467 Quando utilizamos <tt>send_file</tt> ou arquivos estáticos pode ter mime types Sinatra
468 não entendidos. Use +mime_type+ para os registar por extensão de arquivos:
469
470 mime_type :foo, 'text/foo'
471
472 Pode também utilizar isto com o helper +content_type+:
473
474 content_type :foo
475
476 == Middleware Rack
477
478 O Sinatra corre no Rack[http://rack.rubyforge.org/], uma interface padrão mínima para
479 frameworks web em Ruby. Uma das capacidades mais interessantes do Rack, para desenvolver
480 aplicações, é o suporte de "middleware" -- componentes que residem entre o servidor e
481 a aplicação, monitorizando e/ou manipulando o pedido/resposta (request/response) HTTP
482 para providenciar varios tipos de funcionalidades comuns.
483
484 O Sinatra torna a construção de pipelines do middleware Rack fácil a um nível superior
485 utilizando o método +use+:
486
487 require 'sinatra'
488 require 'meu_middleware_personalizado'
489
490 use Rack::Lint
491 use MeuMiddlewarePersonalizado
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 |utilizador, senha|
503 utilizador == '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 utiliza
508 muitos desses componentes automaticamente dependendo da configuração, por isso,
509 tipicamente nao é necessário utilizar +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 a 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: um simples arquivo de
553 aplicação, directórios ./public e ./views, logs, página de detalhes de excepçã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 'Olá mundo!'
564 end
565 end
566
567 A classe MinhaApp é um componente Rack independente que pode utilizar como um
568 middleware Rack, uma aplicação Rack, ou metal Rails. 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 desactivadas 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ê você mesmo uma vista de olhos ao código: 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 Comandos
597
598 As aplicações Sinatra podem ser executadas directamente:
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 # activa o bloqueio (padrão é desligado)
610
611 == A última versão
612
613 Se gostaria de utilizar o código da última versão do Sinatra, crie um clone
614 local e execute sua aplicação com o directó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, pode adicionar o directó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 correndo a versão" + Sinatra::VERSION
630 end
631
632 Para actualizar 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] - Encontrou 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.