sinatra 2.2.4 → 3.0.0

Sign up to get free protection for your applications and to get access to all the features.

Potentially problematic release.


This version of sinatra might be problematic. Click here for more details.

data/README.es.md DELETED
@@ -1,3231 +0,0 @@
1
- # Sinatra
2
-
3
- [![Build Status](https://secure.travis-ci.org/sinatra/sinatra.svg)](http://travis-ci.org/sinatra/sinatra)
4
-
5
- Sinatra es un
6
- [DSL](https://es.wikipedia.org/wiki/Lenguaje_específico_del_dominio) para
7
- crear aplicaciones web rápidamente en Ruby con un mínimo esfuerzo:
8
-
9
- ```ruby
10
- # miapp.rb
11
- require 'sinatra'
12
-
13
- get '/' do
14
- 'Hola mundo!'
15
- end
16
- ```
17
-
18
- Instala la gema:
19
-
20
- ```shell
21
- gem install sinatra
22
- ruby miapp.rb
23
- ```
24
-
25
- Y corre la aplicación:
26
- ```shell
27
- gem install sinatra
28
- ruby miapp.rb
29
- ```
30
-
31
- Ver en [http://localhost:4567](http://localhost:4567).
32
-
33
- El código que cambiaste no tendra efecto hasta que reinicies el servidor.
34
- Por favor reinicia el servidor cada vez que cambies tu código o usa [sinatra/reloader](http://www.sinatrarb.com/contrib/reloader).
35
-
36
- Se recomienda ejecutar `gem install puma`, porque Sinatra lo utilizará si está disponible.
37
-
38
-
39
- ## Tabla de Contenidos
40
-
41
- * [Sinatra](#sinatra)
42
- * [Tabla de Contenidos](#tabla-de-contenidos)
43
- * [Rutas](#rutas)
44
- * [Condiciones](#condiciones)
45
- * [Valores de Retorno](#valores-de-retorno)
46
- * [Comparadores de Rutas Personalizados](#comparadores-de-rutas-personalizados)
47
- * [Archivos Estáticos](#archivos-estáticos)
48
- * [Vistas / Plantillas](#vistas--plantillas)
49
- * [Plantillas Literales](#plantillas-literales)
50
- * [Lenguajes de Plantillas Disponibles](#lenguajes-de-plantillas-disponibles)
51
- * [Plantillas Haml](#plantillas-haml)
52
- * [Plantillas Erb](#plantillas-erb)
53
- * [Plantillas Builder](#plantillas-builder)
54
- * [Plantillas Nokogiri](#plantillas-nokogiri)
55
- * [Plantillas Sass](#plantillas-sass)
56
- * [Plantillas SCSS](#plantillas-scss)
57
- * [Plantillas Less](#plantillas-less)
58
- * [Plantillas Liquid](#plantillas-liquid)
59
- * [Plantillas Markdown](#plantillas-markdown)
60
- * [Plantillas Textile](#plantillas-textile)
61
- * [Plantillas RDoc](#plantillas-rdoc)
62
- * [Plantillas AsciiDoc](#plantillas-asciidoc)
63
- * [Plantillas Radius](#plantillas-radius)
64
- * [Plantillas Markaby](#plantillas-markaby)
65
- * [Plantillas RABL](#plantillas-rabl)
66
- * [Plantillas Slim](#plantillas-slim)
67
- * [Plantillas Creole](#plantillas-creole)
68
- * [Plantillas MediaWiki](#mediawiki-templates)
69
- * [Plantillas CofeeScript](#plantillas-coffeescript)
70
- * [Plantillas Stylus](#plantillas-stylus)
71
- * [Plantillas Yajl](#plantillas-yajl)
72
- * [Plantillas Wlang](#plantillas-wlang)
73
- * [Accediendo Variables en Plantillas](#accediendo-a-variables-en-plantillas)
74
- * [Plantillas con `yield` y `layout` anidado](#plantillas-con-yield-y-layout-anidado)
75
- * [Plantillas Inline](#plantillas-inline)
76
- * [Plantillas Nombradas](#plantillas-nombradas)
77
- * [Asociando Extensiones de Archivo](#asociando-extensiones-de-archivo)
78
- * [Añadiendo Tu Propio Motor de Plantillas](#añadiendo-tu-propio-motor-de-plantillas)
79
- * [Usando Lógica Personalizada para la Búsqueda en Plantillas](#usando-lógica-personalizada-para-la-búsqueda-en-plantillas)
80
- * [Filtros](#filtros)
81
- * [Helpers](#helpers)
82
- * [Usando Sesiones](#usando-sesiones)
83
- * [Secreto de Sesión](#secreto-de-sesión)
84
- * [Configuración de Sesión](#configuración-de-sesión)
85
- * [Escogiendo tu propio Middleware de Sesión](#escogiendo-tu-propio-middleware-de-sesión)
86
- * [Interrupcion](#interrupción)
87
- * [Paso](#paso)
88
- * [Desencadenando Otra Ruta](#desencadenando-otra-ruta)
89
- * [Configurando el Cuerpo, Código de Estado y los Encabezados](#configurando-el-cuerpo-código-de-estado-y-los-encabezados)
90
- * [Streaming De Respuestas](#streaming-de-respuestas)
91
- * [Logging](#logging)
92
- * [Tipos Mime](#tipos-mime)
93
- * [Generando URLs](#generando-urls)
94
- * [Redirección del Navegador](#redirección-del-navegador)
95
- * [Control del Cache](#control-del-cache)
96
- * [Enviando Archivos](#enviando-archivos)
97
- * [Accediendo al Objeto Request](#accediendo-al-objeto-request)
98
- * [Archivos Adjuntos](#archivos-adjuntos)
99
- * [Fecha y Hora](#fecha-y-hora)
100
- * [Buscando los Archivos de las Plantillas](#buscando-los-archivos-de-las-plantillas)
101
- * [Configuración](#configuración)
102
- * [Configurando la Protección Contra Ataques](#configurando-la-protección-contra-ataques)
103
- * [Configuraciones Disponibles](#configuraciones-disponibles)
104
- * [Entornos](#entornos)
105
- * [Manejo de Errores](#manejo-de-errores)
106
- * [Not Found](#not-found)
107
- * [Error](#error)
108
- * [Rack Middleware](#rack-middleware)
109
- * [Pruebas](#pruebas)
110
- * [Sinatra::Base - Middleware, Librerías, y Aplicaciones Modulares](#sinatrabase---middleware-librerías-y-aplicaciones-modulares)
111
- * [Estilo Modular vs Estilo Clásico](#estilo-modular-vs-clásico)
112
- * [Sirviendo una Aplicación Modular](#sirviendo-una-aplicación-modular)
113
- * [Usando una Aplicación de Estilo Clásico con config.ru](#usando-una-aplicación-clásica-con-un-archivo-configru)
114
- * [¿Cuándo usar config.ru?](#cuándo-usar-configru)
115
- * [Utilizando Sinatra como Middleware](#utilizando-sinatra-como-middleware)
116
- * [Creación Dinámica de Aplicaciones](#creación-dinámica-de-aplicaciones)
117
- * [Ámbitos y Ligaduras (Scopes and Binding)](#Ámbitos-y-ligaduras)
118
- * [Alcance de una Aplicación/Clase](#Ámbito-de-aplicaciónclase)
119
- * [Alcance de una Solicitud/Instancia](#Ámbito-de-peticióninstancia)
120
- * [Alcance de Delegación](#Ámbito-de-delegación)
121
- * [Línea de comandos](#línea-de-comandos)
122
- * [Multi-threading](#multi-threading)
123
- * [Requerimientos](#requerimientos)
124
- * [A la Vanguardia](#a-la-vanguardia)
125
- * [Usando bundler](#usando-bundler)
126
- * [Versionado](#versionado)
127
- * [Lecturas Recomendadas](#lecturas-recomendadas)
128
-
129
- ## Rutas
130
-
131
- En Sinatra, una ruta es un método HTTP junto a un patrón de un URL.
132
- Cada ruta está asociada a un bloque:
133
-
134
- ```ruby
135
- get '/' do
136
- .. mostrar algo ..
137
- end
138
-
139
- post '/' do
140
- .. crear algo ..
141
- end
142
-
143
- put '/' do
144
- .. reemplazar algo ..
145
- end
146
-
147
- patch '/' do
148
- .. modificar algo ..
149
- end
150
-
151
- delete '/' do
152
- .. aniquilar algo ..
153
- end
154
-
155
- options '/' do
156
- .. informar algo ..
157
- end
158
-
159
- link '/' do
160
- .. afiliar a algo ..
161
- end
162
-
163
- unlink '/' do
164
- .. separar algo ..
165
- end
166
-
167
- ```
168
-
169
- Las rutas son comparadas en el orden en el que son definidas. La primera ruta
170
- que coincide con la petición es invocada.
171
-
172
- Las rutas con barras al final son distintas a las que no tienen:
173
-
174
-
175
- ```ruby
176
- get '/foo' do
177
- # no es igual que "GET /foo/"
178
- end
179
- ```
180
-
181
- Los patrones de las rutas pueden incluir parámetros nombrados, accesibles a
182
- través del hash `params`:
183
-
184
-
185
- ```ruby
186
- get '/hola/:nombre' do
187
- # coincide con "GET /hola/foo" y "GET /hola/bar"
188
- # params['nombre'] es 'foo' o 'bar'
189
- "Hola #{params['nombre']}!"
190
- end
191
- ```
192
-
193
- También puede acceder a los parámetros nombrados usando parámetros de bloque:
194
-
195
- ```ruby
196
- get '/hola/:nombre' do |n|
197
- # coincide con "GET /hola/foo" y "GET /hola/bar"
198
- # params['nombre'] es 'foo' o 'bar'
199
- # n almacena params['nombre']
200
- "Hola #{n}!"
201
- end
202
- ```
203
-
204
- Los patrones de ruta también pueden incluir parámetros splat (o wildcard),
205
- accesibles a través del arreglo `params['splat']`:
206
-
207
- ```ruby
208
- get '/decir/*/al/*' do
209
- # coincide con /decir/hola/al/mundo
210
- params['splat'] # => ["hola", "mundo"]
211
- end
212
-
213
- get '/descargar/*.*' do
214
- # coincide con /descargar/path/al/archivo.xml
215
- params['splat'] # => ["path/al/archivo", "xml"]
216
- end
217
- ```
218
-
219
- O, con parámetros de bloque:
220
-
221
- ```ruby
222
- get '/descargar/*.*' do |path, ext|
223
- [path, ext] # => ["path/to/file", "xml"]
224
- end
225
- ```
226
-
227
- Rutas con Expresiones Regulares:
228
-
229
- ```ruby
230
- get /\/hola\/([\w]+)/ do
231
- "Hola, #{params['captures'].first}!"
232
- end
233
- ```
234
-
235
- O con un parámetro de bloque:
236
-
237
- ```ruby
238
- get %r{/hola/([\w]+)} do |c|
239
- "Hola, #{c}!"
240
- end
241
- ```
242
-
243
- Los patrones de ruta pueden contener parámetros opcionales:
244
-
245
- ```ruby
246
- get '/posts/:formato?' do
247
- # coincide con "GET /posts/" y además admite cualquier extensión, por
248
- # ejemplo, "GET /posts/json", "GET /posts/xml", etc.
249
- end
250
- ```
251
-
252
- Las rutas también pueden usar parámetros de consulta:
253
-
254
- ```ruby
255
- get '/posts' do
256
- # es igual que "GET /posts?title=foo&author=bar"
257
- title = params['title']
258
- author = params['author']
259
- # usa las variables title y author; la consulta es opcional para la ruta /posts
260
- end
261
- ```
262
-
263
- A propósito, a menos que desactives la protección para el ataque *path
264
- traversal* (ver más [abajo](#configurando-la-protección-contra-ataques)), el path de la petición puede ser modificado
265
- antes de que se compare con los de tus rutas.
266
-
267
- Puedes perzonalizar las opciones de [Mustermann](https://github.com/sinatra/mustermann) usadas para una ruta pasando
268
- el hash `:mustermann_opts`:
269
-
270
- ```ruby
271
- get '\A/posts\z', :mustermann_opts => { :type => :regexp, :check_anchors => false } do
272
- # es exactamente igual a /posts, con anclaje explícito
273
- "¡Si igualas un patrón anclado aplaude!"
274
- end
275
- ```
276
-
277
- ## Condiciones
278
-
279
- Las rutas pueden incluir una variedad de condiciones de selección, como por
280
- ejemplo el user agent:
281
-
282
- ```ruby
283
- get '/foo', :agent => /Songbird (\d\.\d)[\d\/]*?/ do
284
- "Estás usando la versión de Songbird #{params['agent'][0]}"
285
- end
286
-
287
- get '/foo' do
288
- # Coincide con navegadores que no sean songbird
289
- end
290
- ```
291
-
292
- Otras condiciones disponibles son `host_name` y `provides`:
293
-
294
- ```ruby
295
- get '/', :host_name => /^admin\./ do
296
- "Área de Administración, Acceso denegado!"
297
- end
298
-
299
- get '/', :provides => 'html' do
300
- haml :index
301
- end
302
-
303
- get '/', :provides => ['rss', 'atom', 'xml'] do
304
- builder :feed
305
- end
306
- ```
307
-
308
- `provides` busca el encabezado Accept de la solicitud
309
-
310
-
311
- Puede definir sus propias condiciones fácilmente:
312
-
313
- ```ruby
314
- set(:probabilidad) { |valor| condition { rand <= valor } }
315
-
316
- get '/gana_un_auto', :probabilidad => 0.1 do
317
- "Ganaste!"
318
- end
319
-
320
- get '/gana_un_auto' do
321
- "Lo siento, perdiste."
322
- end
323
- ```
324
-
325
- Para una condición que toma multiples valores usa splat:
326
-
327
- ```ruby
328
- set(:autorizar) do |*roles| # <- mira el splat
329
- condition do
330
- unless sesion_iniciada? && roles.any? {|rol| usuario_actual.tiene_rol? rol }
331
- redirect "/iniciar_sesion/", 303
332
- end
333
- end
334
- end
335
-
336
- get "/mi/cuenta/", :autorizar => [:usuario, :administrador] do
337
- "Detalles de mi cuenta"
338
- end
339
-
340
- get "/solo/administradores/", :autorizar => :administrador do
341
- "Únicamente para administradores!"
342
- end
343
- ```
344
-
345
- ## Valores de Retorno
346
-
347
- El valor de retorno de un bloque de ruta determina por lo menos el cuerpo de la respuesta
348
- transmitida al cliente HTTP o por lo menos al siguiente middleware en la pila de Rack.
349
- Lo más común es que sea un string, como en los ejemplos anteriores.
350
- Sin embargo, otros valores también son aceptados.
351
-
352
- Puedes retornar cualquier objeto que sea una respuesta Rack válida,
353
- un objeto que represente el cuerpo de una respuesta Rack o un código
354
- de estado HTTP:
355
-
356
- * Un arreglo con tres elementos: `[estado (Integer), cabeceras (Hash), cuerpo de
357
- la respuesta (responde a #each)]`
358
- * Un arreglo con dos elementos: `[estado (Integer), cuerpo de la respuesta
359
- (responde a #each)]`
360
- * Un objeto que responde a `#each` y que le pasa únicamente strings al bloque
361
- dado
362
- * Un Integer representando el código de estado
363
-
364
- De esa manera, por ejemplo, podemos fácilmente implementar un ejemplo de streaming:
365
-
366
- ```ruby
367
- class Stream
368
- def each
369
- 100.times { |i| yield "#{i}\n" }
370
- end
371
- end
372
-
373
- get('/') { Stream.new }
374
- ```
375
-
376
- También puedes usar el `stream` helper ([descrito abajo](#streaming-de-respuestas))
377
- para reducir el código repetitivo e incrustar la lógica de stream a la ruta
378
-
379
- ## Comparadores de Rutas Personalizados
380
-
381
- Como se mostró anteriormente, Sinatra permite utilizar strings y expresiones
382
- regulares para definir las rutas. Sin embargo, no termina ahí.Puedes
383
- definir tus propios comparadores muy fácilmente:
384
-
385
- ```ruby
386
- class TodoMenosElPatron
387
- Match = Struct.new(:captures)
388
-
389
- def initialize(excepto)
390
- @excepto = excepto
391
- @capturas = Match.new([])
392
- end
393
-
394
- def match(str)
395
- @capturas unless @excepto === str
396
- end
397
- end
398
-
399
- def cualquiera_menos(patron)
400
- TodoMenosElPatron.new(patron)
401
- end
402
-
403
- get cualquiera_menos("/index") do
404
- # ...
405
- end
406
- ```
407
-
408
- Tenga en cuenta que el ejemplo anterior es un poco rebuscado. Un resultado
409
- similar puede conseguirse más sencillamente:
410
-
411
- ```ruby
412
- get // do
413
- pass if request.path_info == "/index"
414
- # ...
415
- end
416
- ```
417
-
418
- O, usando un look ahead negativo:
419
-
420
- ```ruby
421
- get %r{(?!/index)} do
422
- # ...
423
- end
424
- ```
425
-
426
- ## Archivos Estáticos
427
-
428
- Los archivos estáticos son servidos desde el directorio público
429
- `./public`. Puede especificar una ubicación diferente ajustando la
430
- opción `:public_folder`:
431
-
432
- ```ruby
433
- set :public_folder, __dir__ + '/static'
434
- ```
435
-
436
- Note que el nombre del directorio público no está incluido en la URL. Por
437
- ejemplo, el archivo `./public/css/style.css` se accede a través de
438
- `http://ejemplo.com/css/style.css`.
439
-
440
- Use la configuración `:static_cache_control` para agregar el encabezado
441
- `Cache-Control` (Ver mas [abajo](#control-del-cache)).
442
-
443
- ## Vistas / Plantillas
444
-
445
- Cada lenguaje de plantilla se expone a través de un método de renderizado que
446
- lleva su nombre. Estos métodos simplemente devuelven un string:
447
-
448
- ```ruby
449
- get '/' do
450
- erb :index
451
- end
452
- ```
453
-
454
- Renderiza `views/index.erb`.
455
-
456
- En lugar del nombre de la plantilla puedes proporcionar directamente el
457
- contenido de la misma:
458
-
459
- ```ruby
460
- get '/' do
461
- codigo = "<%= Time.now %>"
462
- erb codigo
463
- end
464
- ```
465
-
466
- Los métodos de renderizado, aceptan además un segundo argumento, el hash de
467
- opciones:
468
-
469
- ```ruby
470
- get '/' do
471
- erb :index, :layout => :post
472
- end
473
- ```
474
-
475
- Renderiza `views/index.erb` incrustado en `views/post.erb` (por
476
- defecto, la plantilla `:index` es incrustada en `views/layout.erb` siempre y
477
- cuando este último archivo exista).
478
-
479
- Cualquier opción que Sinatra no entienda le será pasada al motor de renderizado
480
- de la plantilla:
481
-
482
- ```ruby
483
- get '/' do
484
- haml :index, :format => :html5
485
- end
486
- ```
487
-
488
- Además, puede definir las opciones para un lenguaje de plantillas de forma
489
- general:
490
-
491
- ```ruby
492
- set :haml, :format => :html5
493
-
494
- get '/' do
495
- haml :index
496
- end
497
- ```
498
-
499
- Las opciones pasadas al método de renderizado tienen precedencia sobre las
500
- definidas mediante `set`.
501
-
502
- Opciones disponibles:
503
-
504
- <dl>
505
-
506
- <dt>locals</dt>
507
- <dd>
508
- Lista de variables locales pasadas al documento. Resultan muy útiles cuando
509
- se combinan con parciales.
510
- Ejemplo: <tt>erb "<%= foo %>", :locals => {:foo => "bar"}</tt>
511
- </dd>
512
-
513
- <dt>default_encoding</dt>
514
- <dd>
515
- Encoding utilizado cuando el de un string es dudoso. Por defecto toma el
516
- valor de <tt>settings.default_encoding</tt>.
517
- </dd>
518
-
519
- <dt>views</dt>
520
- <dd>
521
- Directorio desde donde se cargan las vistas. Por defecto toma el valor de
522
- <tt>settings.views</tt>.
523
- </dd>
524
-
525
- <dt>layout</dt>
526
- <dd>
527
- Si es <tt>true</tt> o <tt>false</tt> indica que se debe usar, o no, un layout,
528
- respectivamente. También puede ser un Symbol que especifique qué plantilla
529
- usar. Ejemplo: <tt>erb :index, :layout => !request.xhr?</tt>
530
- </dd>
531
-
532
- <dt>content_type</dt>
533
- <dd>
534
- Content-Type que produce la plantilla. El valor por defecto depende de cada
535
- lenguaje de plantillas.
536
- </dd>
537
-
538
- <dt>scope</dt>
539
- <dd>
540
- Ámbito en el que se renderiza la plantilla. Por defecto utiliza la instancia
541
- de la aplicación. Ten en cuenta que si cambiás esta opción las variables de
542
- instancia y los helpers van a dejar de estar disponibles.
543
- </dd>
544
-
545
- <dt>layout_engine</dt>
546
- <dd>
547
- Motor de renderizado de plantillas que usa para el layout. Resulta
548
- conveniente para lenguajes que no soportan layouts. Por defecto toma el valor
549
- del motor usado para renderizar la plantilla.
550
- Ejemplo: <tt>set :rdoc, :layout_engine => :erb</tt>
551
- </dd>
552
-
553
- <dt>layout_options</dt>
554
- <dd>
555
- Opciones especiales usadas únicamente para renderizar el layout. Ejemplo:
556
- <tt>set :rdoc, :layout_options => { :views => 'views/layouts' }</tt>
557
- </dd>
558
- </dl>
559
-
560
- Se asume que las plantillas están ubicadas directamente bajo el directorio `./views`.
561
- Para usar un directorio diferente:
562
-
563
- ```ruby
564
- set :views, settings.root + '/templates'
565
- ```
566
-
567
- Es importante acordarse que siempre tienes que referenciar a las plantillas con
568
- símbolos, incluso cuando se encuentran en un subdirectorio (en este caso
569
- tienes que usar: `:'subdir/plantilla'` o `'subdir/plantilla'.to_sym`). Esto es debido
570
- a que los métodos de renderización van a renderizar directamente cualquier string que
571
- se les pase como argumento.
572
-
573
- ### Plantillas Literales
574
-
575
- ```ruby
576
- get '/' do
577
- haml '%div.titulo Hola Mundo'
578
- end
579
- ```
580
-
581
- Renderiza el string de la plantilla. Opcionalmente puedes especificar
582
- `:path` y `:line` para un backtrace más claro si hay una ruta del sistema
583
- de archivos o una línea asociada con ese string
584
-
585
- ```ruby
586
- get '/' do
587
- haml '%div.titulo Hola Mundo', :path => 'ejemplos/archivo.haml', :line => 3
588
- end
589
- ```
590
-
591
- ### Lenguajes de Plantillas Disponibles
592
-
593
- Algunos lenguajes tienen varias implementaciones. Para especificar que
594
- implementación usar (y para ser thread-safe), deberías requerirla antes de
595
- usarla:
596
-
597
- ```ruby
598
- require 'rdiscount' # o require 'bluecloth'
599
- get('/') { markdown :index }
600
- ```
601
-
602
- #### Plantillas Haml
603
-
604
- <table>
605
- <tr>
606
- <td>Dependencias</td>
607
- <td><a href="http://haml.info/" title="haml">haml</a></td>
608
- </tr>
609
- <tr>
610
- <td>Expresiones de Archivo</td>
611
- <td><tt>.haml</tt></td>
612
- </tr>
613
- <tr>
614
- <td>Ejemplo</td>
615
- <td><tt>haml :index, :format => :html5</tt></td>
616
- </tr>
617
- </table>
618
-
619
- #### Plantillas Erb
620
-
621
- <table>
622
- <tr>
623
- <td>Dependencias</td>
624
- <td>
625
- <a href="http://www.kuwata-lab.com/erubis/" title="erubis">erubis</a>
626
- o erb (incluida en Ruby)
627
- </td>
628
- </tr>
629
- <tr>
630
- <td>Extensiones de Archivo</td>
631
- <td><tt>.erb</tt>, <tt>.rhtml</tt> o <tt>.erubis</tt> (solamente con Erubis)</td>
632
- </tr>
633
- <tr>
634
- <td>Ejemplo</td>
635
- <td><tt>erb :index</tt></td>
636
- </tr>
637
- </table>
638
-
639
- #### Plantillas Builder
640
-
641
- <table>
642
- <tr>
643
- <td>Dependencias</td>
644
- <td>
645
- <a href="https://github.com/jimweirich/builder" title="builder">builder</a>
646
- </td>
647
- </tr>
648
- <tr>
649
- <td>Extensiones de Archivo</td>
650
- <td><tt>.builder</tt></td>
651
- </tr>
652
- <tr>
653
- <td>Ejemplo</td>
654
- <td><tt>builder { |xml| xml.em "hola" }</tt></td>
655
- </tr>
656
- </table>
657
-
658
- También toma un bloque para plantillas inline (ver [ejemplo](#plantillas-inline)).
659
-
660
- #### Plantillas Nokogiri
661
-
662
- <table>
663
- <tr>
664
- <td>Dependencias</td>
665
- <td><a href="http://www.nokogiri.org/" title="nokogiri">nokogiri</a></td>
666
- </tr>
667
- <tr>
668
- <td>Extensiones de Archivo</td>
669
- <td><tt>.nokogiri</tt></td>
670
- </tr>
671
- <tr>
672
- <td>Ejemplo</td>
673
- <td><tt>nokogiri { |xml| xml.em "hola" }</tt></td>
674
- </tr>
675
- </table>
676
-
677
- También toma un bloque para plantillas inline (ver [ejemplo](#plantillas-inline)).
678
-
679
- #### Plantillas Sass
680
-
681
- <table>
682
- <tr>
683
- <td>Dependencias</td>
684
- <td><a href="http://sass-lang.com/" title="sass">sass</a></td>
685
- </tr>
686
- <tr>
687
- <td>Extensiones de Archivo</td>
688
- <td><tt>.sass</tt></td>
689
- </tr>
690
- <tr>
691
- <td>Ejemplo</td>
692
- <td><tt>sass :stylesheet, :style => :expanded</tt></td>
693
- </tr>
694
- </table>
695
-
696
- #### Plantillas SCSS
697
-
698
- <table>
699
- <tr>
700
- <td>Dependencias</td>
701
- <td><a href="http://sass-lang.com/" title="sass">sass</a></td>
702
- </tr>
703
- <tr>
704
- <td>Extensiones de Archivo</td>
705
- <td><tt>.scss</tt></td>
706
- </tr>
707
- <tr>
708
- <td>Ejemplo</td>
709
- <td><tt>scss :stylesheet, :style => :expanded</tt></td>
710
- </tr>
711
- </table>
712
-
713
- #### Plantillas Less
714
-
715
- <table>
716
- <tr>
717
- <td>Dependencias</td>
718
- <td><a href="http://lesscss.org/" title="less">less</a></td>
719
- </tr>
720
- <tr>
721
- <td>Extensiones de Archivo</td>
722
- <td><tt>.less</tt></td>
723
- </tr>
724
- <tr>
725
- <td>Ejemplo</td>
726
- <td><tt>less :stylesheet</tt></td>
727
- </tr>
728
- </table>
729
-
730
- #### Plantillas Liquid
731
-
732
- <table>
733
- <tr>
734
- <td>Dependencias</td>
735
- <td><a href="https://shopify.github.io/liquid/" title="liquid">liquid</a></td>
736
- </tr>
737
- <tr>
738
- <td>Extensiones de Archivo</td>
739
- <td><tt>.liquid</tt></td>
740
- </tr>
741
- <tr>
742
- <td>Ejemplo</td>
743
- <td><tt>liquid :index, :locals => { :clave => 'valor' }</tt></td>
744
- </tr>
745
- </table>
746
-
747
- Como no va a poder llamar a métodos de Ruby (excepto por `yield`) desde una
748
- plantilla Liquid, casi siempre va a querer pasarle locales.
749
-
750
- #### Plantillas Markdown
751
-
752
- <table>
753
- <tr>
754
- <td>Dependencias</td>
755
- <td>
756
- <a href="https://github.com/davidfstr/rdiscount" title="RDiscount">RDiscount</a>,
757
- <a href="https://github.com/vmg/redcarpet" title="RedCarpet">RedCarpet</a>,
758
- <a href="https://github.com/ged/bluecloth" title="bluecloth">BlueCloth</a>,
759
- <a href="http://kramdown.gettalong.org/" title="kramdown">kramdown</a> o
760
- <a href="https://github.com/bhollis/maruku" title="maruku">maruku</a>
761
- </td>
762
- </tr>
763
- <tr>
764
- <td>Extensiones de Archivo</td>
765
- <td><tt>.markdown</tt>, <tt>.mkd</tt> y <tt>.md</tt></td>
766
- </tr>
767
- <tr>
768
- <td>Ejemplo</td>
769
- <td><tt>markdown :index, :layout_engine => :erb</tt></td>
770
- </tr>
771
- </table>
772
-
773
- No es posible llamar métodos desde markdown, ni pasarle locales. Por lo tanto,
774
- generalmente va a usarlo en combinación con otro motor de renderizado:
775
-
776
- ```ruby
777
- erb :resumen, :locals => { :texto => markdown(:introduccion) }
778
- ```
779
-
780
- Tenga en cuenta que también puedes llamar al método `markdown` desde otras
781
- plantillas:
782
-
783
- ```ruby
784
- %h1 Hola Desde Haml!
785
- %p= markdown(:saludos)
786
- ```
787
-
788
- Como no puede utilizar Ruby desde Markdown, no puede usar layouts escritos en
789
- Markdown. De todos modos, es posible usar un motor de renderizado para el
790
- layout distinto al de la plantilla pasando la opción `:layout_engine`.
791
-
792
- #### Plantillas Textile
793
-
794
- <table>
795
- <tr>
796
- <td>Dependencias</td>
797
- <td><a href="http://redcloth.org/" title="RedCloth">RedCloth</a></td>
798
- </tr>
799
- <tr>
800
- <td>Extensiones de Archivo</td>
801
- <td><tt>.textile</tt></td>
802
- </tr>
803
- <tr>
804
- <td>Ejemplo</td>
805
- <td><tt>textile :index, :layout_engine => :erb</tt></td>
806
- </tr>
807
- </table>
808
-
809
- No es posible llamar métodos desde textile, ni pasarle locales. Por lo tanto,
810
- generalmente vas a usarlo en combinación con otro motor de renderizado:
811
-
812
- ```ruby
813
- erb :resumen, :locals => { :texto => textile(:introduccion) }
814
- ```
815
-
816
- Ten en cuenta que también puedes llamar al método `textile` desde otras
817
- plantillas:
818
-
819
- ```ruby
820
- %h1 Hola Desde Haml!
821
- %p= textile(:saludos)
822
- ```
823
-
824
- Como no puedes utilizar Ruby desde Textile, no puedes usar layouts escritos en
825
- Textile. De todos modos, es posible usar un motor de renderizado para el
826
- layout distinto al de la plantilla pasando la opción `:layout_engine`.
827
-
828
- #### Plantillas RDoc
829
-
830
- <table>
831
- <tr>
832
- <td>Dependencias</td>
833
- <td><a href="http://rdoc.sourceforge.net/" title="RDoc">RDoc</a></td>
834
- </tr>
835
- <tr>
836
- <td>Extensiones de Archivo</td>
837
- <td><tt>.rdoc</tt></td>
838
- </tr>
839
- <tr>
840
- <td>Ejemplo</td>
841
- <td><tt>rdoc :README, :layout_engine => :erb</tt></td>
842
- </tr>
843
- </table>
844
-
845
- No es posible llamar métodos desde rdoc, ni pasarle locales. Por lo tanto,
846
- generalmente vas a usarlo en combinación con otro motor de renderizado:
847
-
848
- ```ruby
849
- erb :resumen, :locals => { :texto => rdoc(:introduccion) }
850
- ```
851
-
852
- Ten en cuenta que también puedes llamar al método `rdoc` desde otras
853
- plantillas:
854
-
855
- ```ruby
856
- %h1 Hola Desde Haml!
857
- %p= rdoc(:saludos)
858
- ```
859
-
860
- Como no puedes utilizar Ruby desde RDoc, no puedes usar layouts escritos en RDoc.
861
- De todos modos, es posible usar un motor de renderizado para el layout distinto
862
- al de la plantilla pasando la opción `:layout_engine`.
863
-
864
- #### Plantillas AsciiDoc
865
-
866
- <table>
867
- <tr>
868
- <td>Dependencia</td>
869
- <td><a href="http://asciidoctor.org/" title="Asciidoctor">Asciidoctor</a></td>
870
- </tr>
871
- <tr>
872
- <td>Extensiones de Archivo</td>
873
- <td><tt>.asciidoc</tt>, <tt>.adoc</tt> and <tt>.ad</tt></td>
874
- </tr>
875
- <tr>
876
- <td>Ejemplo</td>
877
- <td><tt>asciidoc :README, :layout_engine => :erb</tt></td>
878
- </tr>
879
- </table>
880
-
881
- Desde que no se puede utilizar métodos de Ruby desde una
882
- plantilla AsciiDoc, casi siempre va a querer pasarle locales.
883
-
884
- #### Plantillas Radius
885
-
886
- <table>
887
- <tr>
888
- <td>Dependencias</td>
889
- <td><a href="https://github.com/jlong/radius" title="Radius">Radius</a></td>
890
- </tr>
891
- <tr>
892
- <td>Extensiones de Archivo</td>
893
- <td><tt>.radius</tt></td>
894
- </tr>
895
- <tr>
896
- <td>Ejemplo</td>
897
- <td><tt>radius :index, :locals => { :clave => 'valor' }</tt></td>
898
- </tr>
899
- </table>
900
-
901
- Desde que no se puede utilizar métodos de Ruby (excepto por `yield`) de una
902
- plantilla Radius, casi siempre se necesita pasar locales.
903
-
904
- #### Plantillas Markaby
905
-
906
- <table>
907
- <tr>
908
- <td>Dependencias</td>
909
- <td><a href="http://markaby.github.io/" title="Markaby">Markaby</a></td>
910
- </tr>
911
- <tr>
912
- <td>Extensiones de Archivo</td>
913
- <td><tt>.mab</tt></td>
914
- </tr>
915
- <tr>
916
- <td>Ejemplo</td>
917
- <td><tt>markaby { h1 "Bienvenido!" }</tt></td>
918
- </tr>
919
- </table>
920
-
921
- También toma un bloque para plantillas inline (ver [ejemplo](#plantillas-inline)).
922
-
923
- #### Plantillas RABL
924
-
925
- <table>
926
- <tr>
927
- <td>Dependencias</td>
928
- <td><a href="https://github.com/nesquena/rabl" title="Rabl">Rabl</a></td>
929
- </tr>
930
- <tr>
931
- <td>Extensiones de Archivo</td>
932
- <td><tt>.rabl</tt></td>
933
- </tr>
934
- <tr>
935
- <td>Ejemplo</td>
936
- <td><tt>rabl :index</tt></td>
937
- </tr>
938
- </table>
939
-
940
- #### Plantillas Slim
941
-
942
- <table>
943
- <tr>
944
- <td>Dependencias</td>
945
- <td><a href="http://slim-lang.com/" title="Slim Lang">Slim Lang</a></td>
946
- </tr>
947
- <tr>
948
- <td>Extensiones de Archivo</td>
949
- <td><tt>.slim</tt></td>
950
- </tr>
951
- <tr>
952
- <td>Ejemplo</td>
953
- <td><tt>slim :index</tt></td>
954
- </tr>
955
- </table>
956
-
957
- #### Plantillas Creole
958
-
959
- <table>
960
- <tr>
961
- <td>Dependencias</td>
962
- <td><a href="https://github.com/minad/creole" title="Creole">Creole</a></td>
963
- </tr>
964
- <tr>
965
- <td>Extensiones de Archivo</td>
966
- <td><tt>.creole</tt></td>
967
- </tr>
968
- <tr>
969
- <td>Ejemplo</td>
970
- <td><tt>creole :wiki, :layout_engine => :erb</tt></td>
971
- </tr>
972
- </table>
973
-
974
- No es posible llamar métodos desde creole, ni pasarle locales. Por lo tanto,
975
- generalmente va a usarlo en combinación con otro motor de renderizado:
976
-
977
- ```ruby
978
- erb :resumen, :locals => { :texto => cerole(:introduccion) }
979
- ```
980
-
981
- Debe tomar en cuenta que también puede llamar al método `creole` desde otras
982
- plantillas:
983
-
984
- ```ruby
985
- %h1 Hola Desde Haml!
986
- %p= creole(:saludos)
987
- ```
988
-
989
- Como no puedes utilizar Ruby desde Creole, no puedes usar layouts escritos en
990
- Creole. De todos modos, es posible usar un motor de renderizado para el layout
991
- distinto al de la plantilla pasando la opción `:layout_engine`.
992
-
993
- #### MediaWiki Templates
994
-
995
- <table>
996
- <tr>
997
- <td>Dependencia</td>
998
- <td><a href="https://github.com/nricciar/wikicloth" title="WikiCloth">WikiCloth</a></td>
999
- </tr>
1000
- <tr>
1001
- <td>Extension de Archivo</td>
1002
- <td><tt>.mediawiki</tt> and <tt>.mw</tt></td>
1003
- </tr>
1004
- <tr>
1005
- <td>Ejemplo</td>
1006
- <td><tt>mediawiki :wiki, :layout_engine => :erb</tt></td>
1007
- </tr>
1008
- </table>
1009
-
1010
- No es posible llamar métodos desde el markup de MediaWiki, ni pasar locales al mismo.
1011
- Por lo tanto usualmente lo usarás en combinación con otro motor de renderizado:
1012
-
1013
- ```ruby
1014
- erb :overview, :locals => { :text => mediawiki(:introduction) }
1015
- ```
1016
-
1017
- Nota que también puedes llamar al método `mediawiki` desde dentro de otras plantillas:
1018
-
1019
- ```ruby
1020
- %h1 Hello From Haml!
1021
- %p= mediawiki(:greetings)
1022
- ```
1023
-
1024
- Debido a que no puedes llamar a Ruby desde MediaWiki, no puedes usar los diseños escritos en MediaWiki.
1025
- De todas maneras, es posible usar otro motor de renderizado para esa plantilla pasando la opción :layout_engine.
1026
-
1027
- #### Plantillas CoffeeScript
1028
-
1029
- <table>
1030
- <tr>
1031
- <td>Dependencias</td>
1032
- <td>
1033
- <a href="https://github.com/josh/ruby-coffee-script" title="Ruby CoffeeScript">
1034
- CoffeeScript
1035
- </a> y un
1036
- <a href="https://github.com/sstephenson/execjs/blob/master/README.md#readme" title="ExecJS">
1037
- mecanismo para ejecutar javascript
1038
- </a>
1039
- </td>
1040
- </tr>
1041
- <tr>
1042
- <td>Extensiones de Archivo</td>
1043
- <td><tt>.coffee</tt></td>
1044
- </tr>
1045
- <tr>
1046
- <td>Ejemplo</td>
1047
- <td><tt>coffee :index</tt></td>
1048
- </tr>
1049
- </table>
1050
-
1051
- #### Plantillas Stylus
1052
-
1053
- <table>
1054
- <tr>
1055
- <td>Dependencias</td>
1056
- <td>
1057
- <a href="https://github.com/forgecrafted/ruby-stylus" title="Ruby Stylus">
1058
- Stylus
1059
- </a> y un
1060
- <a href="https://github.com/sstephenson/execjs/blob/master/README.md#readme" title="ExecJS">
1061
- mecanismo para ejecutar javascript
1062
- </a>
1063
- </td>
1064
- </tr>
1065
- <tr>
1066
- <td>Extensiones de Archivo</td>
1067
- <td><tt>.styl</tt></td>
1068
- </tr>
1069
- <tr>
1070
- <td>Ejemplo</td>
1071
- <td><tt>stylus :index</tt></td>
1072
- </tr>
1073
- </table>
1074
-
1075
- Antes de poder usar las plantillas de Stylus, necesitas cargar `stylus` y `stylus/tilt`:
1076
-
1077
- ```ruby
1078
- require 'sinatra'
1079
- require 'stylus'
1080
- require 'stylus/tilt'
1081
-
1082
- get '/' do
1083
- stylus :example
1084
- end
1085
- ```
1086
-
1087
- #### Plantillas Yajl
1088
-
1089
- <table>
1090
- <tr>
1091
- <td>Dependencias</td>
1092
- <td><a href="https://github.com/brianmario/yajl-ruby" title="yajl-ruby">yajl-ruby</a></td>
1093
- </tr>
1094
- <tr>
1095
- <td>Extensiones de Archivo</td>
1096
- <td><tt>.yajl</tt></td>
1097
- </tr>
1098
- <tr>
1099
- <td>Ejemplo</td>
1100
- <td>
1101
- <tt>
1102
- yajl :index,
1103
- :locals => { :key => 'qux' },
1104
- :callback => 'present',
1105
- :variable => 'resource'
1106
- </tt>
1107
- </td>
1108
- </tr>
1109
- </table>
1110
-
1111
- El contenido de la plantilla se evalúa como código Ruby, y la variable `json` es convertida a JSON mediante `#to_json`.
1112
-
1113
- ```ruby
1114
- json = { :foo => 'bar' }
1115
- json[:baz] = key
1116
- ```
1117
-
1118
- Las opciones `:callback` y `:variable` se pueden utilizar para decorar el objeto renderizado:
1119
-
1120
- ```ruby
1121
- var contenido = {"foo":"bar","baz":"qux"};
1122
- present(contenido);
1123
- ```
1124
-
1125
- #### Plantillas WLang
1126
-
1127
- <table>
1128
- <tr>
1129
- <td>Dependencias</td>
1130
- <td><a href="https://github.com/blambeau/wlang/" title="wlang">wlang</a></td>
1131
- </tr>
1132
- <tr>
1133
- <td>Extensiones de Archivo</td>
1134
- <td><tt>.wlang</tt></td>
1135
- </tr>
1136
- <tr>
1137
- <td>Ejemplo</td>
1138
- <td><tt>wlang :index, :locals => { :clave => 'valor' }</tt></td>
1139
- </tr>
1140
- </table>
1141
-
1142
- Como no vas a poder llamar a métodos de Ruby (excepto por `yield`) desde una
1143
- plantilla WLang, casi siempre vas a querer pasarle locales.
1144
-
1145
- ### Accediendo a Variables en Plantillas
1146
-
1147
- Las plantillas son evaluadas dentro del mismo contexto que los manejadores de
1148
- ruta. Las variables de instancia asignadas en los manejadores de ruta son
1149
- accesibles directamente por las plantillas:
1150
-
1151
- ```ruby
1152
- get '/:id' do
1153
- @foo = Foo.find(params['id'])
1154
- haml '%h1= @foo.nombre'
1155
- end
1156
- ```
1157
-
1158
- O es posible especificar un Hash de variables locales explícitamente:
1159
-
1160
- ```ruby
1161
- get '/:id' do
1162
- foo = Foo.find(params['id'])
1163
- haml '%h1= bar.nombre', :locals => { :bar => foo }
1164
- end
1165
- ```
1166
-
1167
- Esto es usado típicamente cuando se renderizan plantillas como parciales desde
1168
- adentro de otras plantillas.
1169
-
1170
- ### Plantillas con `yield` y `layout` anidado
1171
-
1172
- Un layout es usualmente una plantilla que llama a `yield`.
1173
- Dicha plantilla puede ser usada tanto a travé de la opción `:template`
1174
- como describimos arriba, o puede ser rederizada con un bloque como a
1175
- continuación:
1176
-
1177
- ```ruby
1178
- erb :post, :layout => false do
1179
- erb :index
1180
- end
1181
- ```
1182
- Este código es principalmente equivalente a `erb :index, :layout => :post`.
1183
-
1184
- Pasar bloques a métodos de renderizado es la forma mas útil de crear layouts anidados:
1185
-
1186
- ```ruby
1187
- erb :main_layout, :layout => false do
1188
- erb :admin_layout do
1189
- erb :user
1190
- end
1191
- end
1192
- ```
1193
-
1194
- Esto también se puede hacer en menos líneas de código con:
1195
-
1196
- ```ruby
1197
- erb :admin_layout, :layout => :main_layout do
1198
- erb :user
1199
- end
1200
- ```
1201
-
1202
- Actualmente, los siguientes métodos de renderizado aceptan un bloque: `erb`, `haml`,
1203
- `liquid`, `slim `, `wlang`. También el método general de `render` acepta un bloque.
1204
-
1205
- ### Plantillas Inline
1206
-
1207
- Las plantillas pueden ser definidas al final del archivo fuente:
1208
-
1209
- ```ruby
1210
- require 'sinatra'
1211
-
1212
- get '/' do
1213
- haml :index
1214
- end
1215
-
1216
- __END__
1217
-
1218
- @@ layout
1219
- %html
1220
- = yield
1221
-
1222
- @@ index
1223
- %div.titulo Hola Mundo
1224
- ```
1225
-
1226
- NOTA: Únicamente las plantillas inline definidas en el archivo fuente que
1227
- requiere Sinatra son cargadas automáticamente. Llamá `enable
1228
- :inline_templates` explícitamente si tienes plantillas inline en otros
1229
- archivos fuente.
1230
-
1231
- ### Plantillas Nombradas
1232
-
1233
- Las plantillas también pueden ser definidas usando el método top-level
1234
- `template`:
1235
-
1236
- ```ruby
1237
- template :layout do
1238
- "%html\n =yield\n"
1239
- end
1240
-
1241
- template :index do
1242
- '%div.titulo Hola Mundo!'
1243
- end
1244
-
1245
- get '/' do
1246
- haml :index
1247
- end
1248
- ```
1249
-
1250
- Si existe una plantilla con el nombre "layout", va a ser usada cada vez que
1251
- una plantilla es renderizada.Puedes desactivar los layouts individualmente
1252
- pasando `:layout => false` o globalmente con
1253
- `set :haml, :layout => false`:
1254
-
1255
- ```ruby
1256
- get '/' do
1257
- haml :index, :layout => !request.xhr?
1258
- end
1259
- ```
1260
-
1261
- ### Asociando Extensiones de Archivo
1262
-
1263
- Para asociar una extensión de archivo con un motor de renderizado, usa
1264
- `Tilt.register`. Por ejemplo, si quieres usar la extensión `tt` para
1265
- las plantillas Textile, puedes hacer lo siguiente:
1266
-
1267
- ```ruby
1268
- Tilt.register :tt, Tilt[:textile]
1269
- ```
1270
-
1271
- ### Añadiendo Tu Propio Motor de Plantillas
1272
-
1273
- Primero, registra tu motor con Tilt, y después, creá tu método de renderizado:
1274
-
1275
- ```ruby
1276
- Tilt.register :mipg, MiMotorDePlantilla
1277
-
1278
- helpers do
1279
- def mypg(*args) render(:mypg, *args) end
1280
- end
1281
-
1282
- get '/' do
1283
- mypg :index
1284
- end
1285
- ```
1286
-
1287
- Renderiza `./views/index.mypg`. Mirá https://github.com/rtomayko/tilt
1288
- para aprender más de Tilt.
1289
-
1290
- ### Usando Lógica Personalizada para la Búsqueda en Plantillas
1291
-
1292
- Para implementar tu propio mecanismo de búsqueda de plantillas puedes
1293
- escribir tu propio método `#find_template`
1294
-
1295
- ```ruby
1296
- configure do
1297
- set :views [ './views/a', './views/b' ]
1298
- end
1299
-
1300
- def find_template(views, name, engine, &block)
1301
- Array(views).each do |v|
1302
- super(v, name, engine, &block)
1303
- end
1304
- end
1305
- ```
1306
-
1307
- ## Filtros
1308
-
1309
- Los filtros `before` son evaluados antes de cada petición dentro del mismo
1310
- contexto que las rutas. Pueden modificar la petición y la respuesta. Las
1311
- variables de instancia asignadas en los filtros son accesibles por las rutas y
1312
- las plantillas:
1313
-
1314
- ```ruby
1315
- before do
1316
- @nota = 'Hey!'
1317
- request.path_info = '/foo/bar/baz'
1318
- end
1319
-
1320
- get '/foo/*' do
1321
- @nota #=> 'Hey!'
1322
- params['splat'] #=> 'bar/baz'
1323
- end
1324
- ```
1325
-
1326
- Los filtros `after` son evaluados después de cada petición dentro del mismo
1327
- contexto y también pueden modificar la petición y la respuesta. Las variables
1328
- de instancia asignadas en los filtros `before` y en las rutas son accesibles por
1329
- los filtros `after`:
1330
-
1331
- ```ruby
1332
- after do
1333
- puts response.status
1334
- end
1335
- ```
1336
-
1337
- Nota: A menos que uses el método `body` en lugar de simplemente devolver un
1338
- string desde una ruta, el cuerpo de la respuesta no va a estar disponible en
1339
- un filtro after, debido a que todavía no se ha generado.
1340
-
1341
- Los filtros aceptan un patrón opcional, que cuando está presente causa que los
1342
- mismos sean evaluados únicamente si el path de la petición coincide con ese
1343
- patrón:
1344
-
1345
- ```ruby
1346
- before '/protegido/*' do
1347
- autenticar!
1348
- end
1349
-
1350
- after '/crear/:slug' do |slug|
1351
- session[:ultimo_slug] = slug
1352
- end
1353
- ```
1354
-
1355
- Al igual que las rutas, los filtros también pueden aceptar condiciones:
1356
-
1357
- ```ruby
1358
- before :agent => /Songbird/ do
1359
- # ...
1360
- end
1361
-
1362
- after '/blog/*', :host_name => 'ejemplo.com' do
1363
- # ...
1364
- end
1365
- ```
1366
-
1367
- ## Helpers
1368
-
1369
- Usá el método top-level `helpers` para definir métodos ayudantes (helpers) que
1370
- pueden ser utilizados dentro de los manejadores de rutas y las plantillas:
1371
-
1372
- ```ruby
1373
- helpers do
1374
- def bar(nombre)
1375
- "#{nombre}bar"
1376
- end
1377
- end
1378
-
1379
- get '/:nombre' do
1380
- bar(params['nombre'])
1381
- end
1382
- ```
1383
-
1384
- Por cuestiones organizativas, puede resultar conveniente organizar los métodos
1385
- helpers en distintos módulos:
1386
-
1387
- ```ruby
1388
- module FooUtils
1389
- def foo(nombre) "#{nombre}foo" end
1390
- end
1391
-
1392
- module BarUtils
1393
- def bar(nombre) "#{nombre}bar" end
1394
- end
1395
-
1396
- helpers FooUtils, BarUtils
1397
- ```
1398
-
1399
- El efecto de utilizar `helpers` de esta manera es el mismo que resulta de
1400
- incluir los módulos en la clase de la aplicación.
1401
-
1402
- ### Usando Sesiones
1403
-
1404
- Una sesión es usada para mantener el estado a través de distintas peticiones.
1405
- Cuando están activadas, proporciona un hash de sesión para cada sesión de usuario:
1406
-
1407
- ```ruby
1408
- enable :sessions
1409
-
1410
- get '/' do
1411
- "valor = " << session[:valor].inspect
1412
- end
1413
-
1414
- get '/:valor' do
1415
- session[:valor] = params['valor']
1416
- end
1417
- ```
1418
-
1419
- #### Secreto de Sesión
1420
-
1421
- Para mejorar la seguridad, los datos de la sesión en la cookie se firman con un secreto usando `HMAC-SHA1`. El secreto de esta sesión debería ser de manera óptima
1422
- un valor aleatorio criptográficamente seguro de una longitud adecuada para
1423
- `HMAC-SHA1` que es mayor o igual que 64 bytes (512 bits, 128 hex caracteres).
1424
- Se le aconsejará que no use un secreto que sea inferior a 32
1425
- bytes de aleatoriedad (256 bits, 64 caracteres hexadecimales).
1426
- Por lo tanto, es **muy importante** que no solo invente el secreto,
1427
- sino que use un generador de números aleatorios para crearlo.
1428
- Los humanos somos extremadamente malos generando valores aleatorios
1429
-
1430
- De forma predeterminada, un secreto de sesión aleatorio seguro de 32 bytes se genera para usted por
1431
- Sinatra, pero cambiará con cada reinicio de su aplicación. Si tienes varias
1432
- instancias de tu aplicación y dejas que Sinatra genere la clave, cada instancia
1433
- tendría una clave de sesión diferente y probablemente no es lo que quieres.
1434
-
1435
- Para una mejor seguridad y usabilidad es
1436
- [recomendado](https://12factor.net/config) que genere un secreto de sesión
1437
- aleatorio seguro y se guarde en las variables de entorno en cada host que ejecuta
1438
- su aplicación para que todas las instancias de su aplicación compartan el mismo
1439
- secreto. Debería rotar periódicamente esta sesión secreta a un nuevo valor.
1440
- Aquí hay algunos ejemplos de cómo puede crear un secreto de 64 bytes y configurarlo:
1441
-
1442
- **Generación de Secreto de Sesión**
1443
-
1444
- ```text
1445
- $ ruby -e "require 'securerandom'; puts SecureRandom.hex(64)"
1446
- 99ae8af...snip...ec0f262ac
1447
- ```
1448
-
1449
- **Generación de Secreto de Sesión (Puntos Extras)**
1450
-
1451
- Usa la [gema sysrandom](https://github.com/cryptosphere/sysrandom) para preferir
1452
- el uso de el sistema RNG para generar valores aleatorios en lugar de
1453
- espacio de usuario `OpenSSL` que MRI Ruby tiene por defecto:
1454
-
1455
- ```text
1456
- $ gem install sysrandom
1457
- Building native extensions. This could take a while...
1458
- Successfully installed sysrandom-1.x
1459
- 1 gem installed
1460
-
1461
- $ ruby -e "require 'sysrandom/securerandom'; puts SecureRandom.hex(64)"
1462
- 99ae8af...snip...ec0f262ac
1463
- ```
1464
-
1465
- **Secreto de Sesión en Variable de Entorno**
1466
-
1467
- Establezca una variable de entorno `SESSION_SECRET` para Sinatra en el valor que
1468
- generaste. Haz que este valor sea persistente durante los reinicios de su host. El
1469
- método para hacer esto variará a través de los sistemas operativos, esto es para
1470
- propósitos ilustrativos solamente:
1471
-
1472
-
1473
- ```bash
1474
- # echo "export SESSION_SECRET=99ae8af...snip...ec0f262ac" >> ~/.bashrc
1475
- ```
1476
-
1477
- **Configuración de la Aplicación y su Secreto de Sesión**
1478
-
1479
- Configura tu aplicación a prueba de fallas si la variable de entorno
1480
- `SESSION_SECRET` no esta disponible
1481
-
1482
- Para puntos extras usa la [gema sysrandom](https://github.com/cryptosphere/sysrandom) acá tambien:
1483
-
1484
- ```ruby
1485
- require 'securerandom'
1486
- # -or- require 'sysrandom/securerandom'
1487
- set :session_secret, ENV.fetch('SESSION_SECRET') { SecureRandom.hex(64) }
1488
- ```
1489
-
1490
- #### Configuración de Sesión
1491
-
1492
- Si desea configurarlo más, también puede almacenar un hash con opciones
1493
- en la configuración `sessions`:
1494
-
1495
- ```ruby
1496
- set :sessions, :domain => 'foo.com'
1497
- ```
1498
-
1499
- Para compartir su sesión en otras aplicaciones en subdominios de foo.com, agregue el prefijo
1500
- dominio con un *.* como este en su lugar:
1501
-
1502
- ```ruby
1503
- set :sessions, :domain => '.foo.com'
1504
- ```
1505
-
1506
- #### Escogiendo tu Propio Middleware de Sesión
1507
-
1508
- Tenga en cuenta que `enable :sessions` en realidad almacena todos los datos en una cookie.
1509
- Esto no siempre podria ser lo que quieres (almacenar muchos datos aumentará su
1510
- tráfico, por ejemplo). Puede usar cualquier middleware de sesión proveniente de Rack
1511
- para hacerlo, se puede utilizar uno de los siguientes métodos:
1512
-
1513
- ```ruby
1514
- enable :sessions
1515
- set :session_store, Rack::Session::Pool
1516
- ```
1517
-
1518
- O para configurar sesiones con un hash de opciones:
1519
-
1520
- ```ruby
1521
- set :sessions, :expire_after => 2592000
1522
- set :session_store, Rack::Session::Pool
1523
- ```
1524
-
1525
- Otra opción es **no** llamar a `enable :sessions`, sino
1526
- su middleware de elección como lo haría con cualquier otro middleware.
1527
-
1528
- Es importante tener en cuenta que al usar este método, la protección
1529
- de sesiones **no estará habilitada por defecto**.
1530
-
1531
- También será necesario agregar el middleware de Rack para hacer eso:
1532
-
1533
- ```ruby
1534
- use Rack::Session::Pool, :expire_after => 2592000
1535
- use Rack::Protection::RemoteToken
1536
- use Rack::Protection::SessionHijacking
1537
- ```
1538
-
1539
- Mira '[Configurando la protección contra ataques](#configurando-la-protección-contra-ataques)' para mas información.
1540
-
1541
- ### Interrupción
1542
-
1543
- Para detener inmediatamente una petición dentro de un filtro o una ruta debes usar:
1544
-
1545
- ```ruby
1546
- halt
1547
- ```
1548
-
1549
- También puedes especificar el estado:
1550
-
1551
- ```ruby
1552
- halt 410
1553
- ```
1554
-
1555
- O el cuerpo:
1556
-
1557
- ```ruby
1558
- halt 'esto va a ser el cuerpo'
1559
- ```
1560
-
1561
- O los dos:
1562
-
1563
- ```ruby
1564
- halt 401, 'salí de acá!'
1565
- ```
1566
-
1567
- Con cabeceras:
1568
-
1569
- ```ruby
1570
- halt 402, { 'Content-Type' => 'text/plain' }, 'venganza'
1571
- ```
1572
-
1573
- Obviamente, es posible utilizar `halt` con una plantilla:
1574
-
1575
- ```ruby
1576
- halt erb(:error)
1577
- ```
1578
-
1579
- ### Paso
1580
-
1581
- Una ruta puede pasarle el procesamiento a la siguiente ruta que coincida con
1582
- la petición usando `pass`:
1583
-
1584
- ```ruby
1585
- get '/adivina/:quien' do
1586
- pass unless params['quien'] == 'Franco'
1587
- 'Adivinaste!'
1588
- end
1589
-
1590
- get '/adivina/*' do
1591
- 'Erraste!'
1592
- end
1593
- ```
1594
-
1595
- Se sale inmediatamente del bloque de la ruta y se le pasa el control a la
1596
- siguiente ruta que coincida. Si no coincide ninguna ruta, se devuelve 404.
1597
-
1598
- ### Desencadenando Otra Ruta
1599
-
1600
- A veces, `pass` no es lo que quieres, sino obtener el
1601
- resultado de la llamada a otra ruta. Simplemente use `call` para lograr esto:
1602
-
1603
- ```ruby
1604
- get '/foo' do
1605
- status, headers, body = call env.merge("PATH_INFO" => '/bar')
1606
- [status, headers, body.map(&:upcase)]
1607
- end
1608
-
1609
- get '/bar' do
1610
- "bar"
1611
- end
1612
- ```
1613
-
1614
- Nota que en el ejemplo anterior, es conveniente mover `"bar"` a un
1615
- helper, y llamarlo desde `/foo` y `/bar`. Así, vas a simplificar
1616
- las pruebas y a mejorar el rendimiento.
1617
-
1618
- Si quieres que la petición se envíe a la misma instancia de la aplicación en
1619
- lugar de otra, usá `call!` en lugar de `call`.
1620
-
1621
- En la especificación de Rack puedes encontrar más información sobre
1622
- `call`.
1623
-
1624
- ### Configurando el Cuerpo, Código de Estado y los Encabezados
1625
-
1626
- Es posible, y se recomienda, asignar el código de estado y el cuerpo de una
1627
- respuesta con el valor de retorno de una ruta. Sin embargo, en algunos
1628
- escenarios puede que sea conveniente asignar el cuerpo en un punto arbitrario
1629
- del flujo de ejecución con el método helper `body`. A partir de ahí, puedes usar ese
1630
- mismo método para acceder al cuerpo de la respuesta:
1631
-
1632
- ```ruby
1633
- get '/foo' do
1634
- body "bar"
1635
- end
1636
-
1637
- after do
1638
- puts body
1639
- end
1640
- ```
1641
-
1642
- También es posible pasarle un bloque a `body`, que será ejecutado por el Rack
1643
- handler (puedes usar esto para implementar streaming, mira ["Valores de Retorno"](#valores-de-retorno)).
1644
-
1645
- De manera similar, también puedes asignar el código de estado y encabezados:
1646
-
1647
- ```ruby
1648
- get '/foo' do
1649
- status 418
1650
- headers \
1651
- "Allow" => "BREW, POST, GET, PROPFIND, WHEN",
1652
- "Refresh" => "Refresh: 20; http://www.ietf.org/rfc/rfc2324.txt"
1653
- body "I'm a tea pot!"
1654
- end
1655
- ```
1656
-
1657
- También, al igual que `body`, `status` y `headers` sin agregarles argumentos pueden usarse
1658
- para acceder a sus valores actuales.
1659
-
1660
- ### Streaming De Respuestas
1661
-
1662
- A veces vas a querer empezar a enviar la respuesta a pesar de que todavía no
1663
- terminaste de generar su cuerpo. También es posible que, en algunos casos,
1664
- quieras seguir enviando información hasta que el cliente cierre la conexión.
1665
- Cuando esto ocurra, el helper `stream` te va a ser de gran ayuda:
1666
-
1667
- ```ruby
1668
- get '/' do
1669
- stream do |out|
1670
- out << "Esto va a ser legen -\n"
1671
- sleep 0.5
1672
- out << " (esperalo) \n"
1673
- sleep 1
1674
- out << "- dario!\n"
1675
- end
1676
- end
1677
- ```
1678
-
1679
- Puedes implementar APIs de streaming,
1680
- [Server-Sent Events](https://html.spec.whatwg.org/multipage/server-sent-events.html#server-sent-events) y puede ser usado
1681
- como base para [WebSockets](https://es.wikipedia.org/wiki/WebSockets). También
1682
- puede ser usado para incrementar el throughput si solo una parte del contenido
1683
- depende de un recurso lento.
1684
-
1685
- Hay que tener en cuenta que el comportamiento del streaming, especialmente el
1686
- número de peticiones concurrentes, depende del servidor web utilizado para
1687
- alojar la aplicación. Puede que algunos servidores no soporten streaming
1688
- directamente, así el cuerpo de la respuesta será enviado completamente de una
1689
- vez cuando el bloque pasado a `stream` finalice su ejecución. Si estás usando
1690
- Shotgun, el streaming no va a funcionar.
1691
-
1692
- Cuando se pasa `keep_open` como parámetro, no se va a enviar el mensaje
1693
- `close` al objeto de stream. Permite que tu lo cierres en el punto de ejecución
1694
- que quieras. Nuevamente, hay que tener en cuenta que este comportamiento es
1695
- posible sólo en servidores que soporten eventos, como Rainbows. El
1696
- resto de los servidores van a cerrar el stream de todos modos:
1697
-
1698
- ```ruby
1699
-
1700
- # config.ru
1701
- require 'sinatra/base'
1702
-
1703
- class App < Sinatra::Base
1704
- connections = []
1705
-
1706
- get '/subscribe' do
1707
- # registrar a un cliente interesado en los eventos del servidor
1708
- stream(:keep_open) do |out|
1709
- connections << out
1710
- # purgar conexiones muertas
1711
- connections.reject!(&:closed?)
1712
- end
1713
- end
1714
-
1715
- post '/:message' do
1716
- connections.each do |out|
1717
- # notificar al cliente que ha llegado un nuevo mensaje
1718
- out << params['message'] << "\n"
1719
-
1720
- # indicar al cliente para conectarse de nuevo
1721
- out.close
1722
- end
1723
-
1724
- # reconocer
1725
- "message received"
1726
- end
1727
- end
1728
-
1729
- run App
1730
- ```
1731
-
1732
- ```ruby
1733
- # rainbows.conf
1734
-
1735
- Rainbows! do
1736
- use :EventMachine
1737
- end
1738
- ```
1739
-
1740
- Ejecute:
1741
-
1742
- ```shell
1743
- rainbows -c rainbows.conf
1744
- ```
1745
-
1746
- También es posible que el cliente cierre la conexión cuando intenta
1747
- escribir en el socket. Debido a esto, se recomienda verificar con
1748
- `out.closed?` antes de intentar escribir.
1749
-
1750
- ### Logging
1751
-
1752
- En el ámbito de la petición, el helper `logger` (registrador) expone
1753
- una instancia de `Logger`:
1754
-
1755
- ```ruby
1756
- get '/' do
1757
- logger.info "cargando datos"
1758
- # ...
1759
- end
1760
- ```
1761
-
1762
- Este logger tiene en cuenta la configuración de logueo de tu Rack
1763
- handler. Si el logueo está desactivado, este método va a devolver un
1764
- objeto que se comporta como un logger pero que en realidad no hace
1765
- nada. Así, no vas a tener que preocuparte por esta situación.
1766
-
1767
- Ten en cuenta que el logueo está habilitado por defecto únicamente
1768
- para `Sinatra::Application`. Si heredaste de
1769
- `Sinatra::Base`, probablemente quieras habilitarlo manualmente:
1770
-
1771
- ```ruby
1772
- class MiApp < Sinatra::Base
1773
- configure :production, :development do
1774
- enable :logging
1775
- end
1776
- end
1777
- ```
1778
-
1779
- Para evitar que se inicialice cualquier middleware de logging, configurá
1780
- `logging` a `nil`. Ten en cuenta que, cuando hagas esto, `logger` va a
1781
- devolver `nil`. Un caso común es cuando quieres usar tu propio logger. Sinatra
1782
- va a usar lo que encuentre en `env['rack.logger']`.
1783
-
1784
- ### Tipos Mime
1785
-
1786
- Cuando usás `send_file` o archivos estáticos tal vez tengas tipos mime
1787
- que Sinatra no entiende. Usá `mime_type` para registrarlos a través de la
1788
- extensión de archivo:
1789
-
1790
- ```ruby
1791
- configure do
1792
- mime_type :foo, 'text/foo'
1793
- end
1794
- ```
1795
-
1796
- También lo puedes usar con el helper `content_type`:
1797
-
1798
- ```ruby
1799
- get '/' do
1800
- content_type :foo
1801
- "foo foo foo"
1802
- end
1803
- ```
1804
-
1805
- ### Generando URLs
1806
-
1807
- Para generar URLs deberías usar el método `url`. Por ejemplo, en Haml:
1808
-
1809
- ```ruby
1810
- %a{:href => url('/foo')} foo
1811
- ```
1812
-
1813
- Tiene en cuenta proxies inversos y encaminadores de Rack, si están presentes.
1814
-
1815
- Este método también puede invocarse mediante su alias `to` (mirá un ejemplo
1816
- a continuación).
1817
-
1818
- ### Redirección del Navegador
1819
-
1820
- Puedes redireccionar al navegador con el método `redirect`:
1821
-
1822
- ```ruby
1823
- get '/foo' do
1824
- redirect to('/bar')
1825
- end
1826
- ```
1827
-
1828
- Cualquier parámetro adicional se utiliza de la misma manera que los argumentos
1829
- pasados a `halt`:
1830
-
1831
- ```ruby
1832
- redirect to('/bar'), 303
1833
- redirect 'http://www.google.com/', 'te confundiste de lugar, compañero'
1834
- ```
1835
-
1836
- También puedes redireccionar fácilmente de vuelta hacia la página desde donde
1837
- vino el usuario con `redirect back`:
1838
-
1839
- ```ruby
1840
- get '/foo' do
1841
- "<a href='/bar'>hacer algo</a>"
1842
- end
1843
-
1844
- get '/bar' do
1845
- hacer_algo
1846
- redirect back
1847
- end
1848
- ```
1849
-
1850
- Para pasar argumentos con una redirección, puedes agregarlos a la cadena de
1851
- búsqueda:
1852
-
1853
- ```ruby
1854
- redirect to('/bar?suma=42')
1855
- ```
1856
-
1857
- O usar una sesión:
1858
-
1859
- ```ruby
1860
- enable :sessions
1861
-
1862
- get '/foo' do
1863
- session[:secreto] = 'foo'
1864
- redirect to('/bar')
1865
- end
1866
-
1867
- get '/bar' do
1868
- session[:secreto]
1869
- end
1870
- ```
1871
-
1872
- ### Control del Cache
1873
-
1874
- Asignar tus encabezados correctamente es el cimiento para realizar un cacheo
1875
- HTTP correcto.
1876
-
1877
- Puedes asignar el encabezado Cache-Control fácilmente:
1878
-
1879
- ```ruby
1880
- get '/' do
1881
- cache_control :public
1882
- "cachealo!"
1883
- end
1884
- ```
1885
-
1886
- Pro tip: configurar el cacheo en un filtro `before`:
1887
-
1888
- ```ruby
1889
- before do
1890
- cache_control :public, :must_revalidate, :max_age => 60
1891
- end
1892
- ```
1893
-
1894
- Si estás usando el helper `expires` para definir el encabezado correspondiente,
1895
- `Cache-Control` se va a definir automáticamente:
1896
-
1897
- ```ruby
1898
- before do
1899
- expires 500, :public, :must_revalidate
1900
- end
1901
- ```
1902
-
1903
- Para usar cachés adecuadamente, deberías considerar usar `etag` o
1904
- `last_modified`. Es recomendable que llames a estos asistentes *antes* de hacer
1905
- cualquier trabajo pesado, ya que van a enviar la respuesta inmediatamente si
1906
- el cliente ya tiene la versión actual en su caché:
1907
-
1908
- ```ruby
1909
- get '/articulo/:id' do
1910
- @articulo = Articulo.find params['id']
1911
- last_modified @articulo.updated_at
1912
- etag @articulo.sha1
1913
- erb :articulo
1914
- end
1915
- ```
1916
-
1917
- También es posible usar una
1918
- [weak ETag](https://en.wikipedia.org/wiki/HTTP_ETag#Strong_and_weak_validation):
1919
-
1920
- ```ruby
1921
- etag @articulo.sha1, :weak
1922
- ```
1923
-
1924
- Estos helpers no van a cachear nada por vos, sino que van a facilitar la
1925
- información necesaria para poder hacerlo. Si estás buscando soluciones rápidas
1926
- de cacheo con proxys reversos, mirá
1927
- [rack-cache](https://github.com/rtomayko/rack-cache):
1928
-
1929
- ```ruby
1930
- require "rack/cache"
1931
- require "sinatra"
1932
-
1933
- use Rack::Cache
1934
-
1935
- get '/' do
1936
- cache_control :public, :max_age => 36000
1937
- sleep 5
1938
- "hola"
1939
- end
1940
- ```
1941
-
1942
- Usá la configuración `:static_cache_control` para agregar el encabezado
1943
- `Cache-Control` a archivos estáticos (ver la sección de configuración
1944
- para más detalles).
1945
-
1946
- De acuerdo con la RFC 2616 tu aplicación debería comportarse diferente si a las
1947
- cabeceras If-Match o If-None-Match se le asigna el valor `*` cuando el
1948
- recurso solicitado ya existe. Sinatra asume para peticiones seguras (como get)
1949
- y potentes (como put) que el recurso existe, mientras que para el resto
1950
- (como post) asume que no. Puedes cambiar este comportamiento con la opción
1951
- `:new_resource`:
1952
-
1953
- ```ruby
1954
- get '/crear' do
1955
- etag '', :new_resource => true
1956
- Articulo.create
1957
- erb :nuevo_articulo
1958
- end
1959
- ```
1960
-
1961
- Si quieres seguir usando una weak ETag, indicalo con la opción `:kind`:
1962
-
1963
- ```ruby
1964
- etag '', :new_resource => true, :kind => :weak
1965
- ```
1966
-
1967
- ### Enviando Archivos
1968
-
1969
- Para enviar archivos, puedes usar el método `send_file`:
1970
-
1971
- ```ruby
1972
- get '/' do
1973
- send_file 'foo.png'
1974
- end
1975
- ```
1976
-
1977
- Además acepta un par de opciones:
1978
-
1979
- ```ruby
1980
- send_file 'foo.png', :type => :jpg
1981
- ```
1982
-
1983
- Estas opciones son:
1984
-
1985
- <dl>
1986
- <dt>filename</dt>
1987
- <dd>Nombre del archivo devuelto, por defecto es el nombre real del archivo.</dd>
1988
-
1989
- <dt>last_modified</dt>
1990
- <dd>Valor para el encabezado Last-Modified, por defecto toma el mtime del archivo.</dd>
1991
-
1992
- <dt>type</dt>
1993
- <dd>El Content-Type que se va a utilizar, si no está presente se intenta
1994
- adivinar a partir de la extensión del archivo.</dd>
1995
-
1996
- <dt>disposition</dt>
1997
- <dd>
1998
- Se utiliza para el encabezado Content-Disposition, y puede tomar alguno de los
1999
- siguientes valores: <tt>nil</tt> (por defecto), <tt>:attachment</tt> y <tt>:inline</tt>
2000
- </dd>
2001
-
2002
- <dt>length</dt>
2003
- <dd>Encabezado Content-Length, por defecto toma el tamaño del archivo</dd>
2004
-
2005
- <dt>status</dt>
2006
- <dd>
2007
- Código de estado a enviar. Útil cuando se envía un archivo estático como un error página. Si es compatible con el controlador de Rack, otros medios que no sean la transmisión del proceso de Ruby será utilizado. Si usas este método de ayuda, Sinatra manejará automáticamente las solicitudes de rango.
2008
- </dd>
2009
- </dl>
2010
-
2011
- ### Accediendo al objeto Request
2012
-
2013
- El objeto de la petición entrante puede ser accedido desde el nivel de la
2014
- petición (filtros, rutas y manejadores de errores) a través del método
2015
- `request`:
2016
-
2017
- ```ruby
2018
- # app corriendo en http://ejemplo.com/ejemplo
2019
- get '/foo' do
2020
- t = %w[text/css text/html application/javascript]
2021
- request.accept # ['text/html', '*/*']
2022
- request.accept? 'text/xml' # true
2023
- request.preferred_type(t) # 'text/html'
2024
- request.body # cuerpo de la petición enviado por el cliente (ver más abajo)
2025
- request.scheme # "http"
2026
- request.script_name # "/ejemplo"
2027
- request.path_info # "/foo"
2028
- request.port # 80
2029
- request.request_method # "GET"
2030
- request.query_string # ""
2031
- request.content_length # longitud de request.body
2032
- request.media_type # tipo de medio de request.body
2033
- request.host # "ejemplo.com"
2034
- request.get? # true (hay métodos análogos para los otros verbos)
2035
- request.form_data? # false
2036
- request["UNA_CABECERA"] # valor de la cabecera UNA_CABECERA
2037
- request.referrer # la referencia del cliente o '/'
2038
- request.user_agent # user agent (usado por la condición :agent)
2039
- request.cookies # hash de las cookies del navegador
2040
- request.xhr? # es una petición ajax?
2041
- request.url # "http://ejemplo.com/ejemplo/foo"
2042
- request.path # "/ejemplo/foo"
2043
- request.ip # dirección IP del cliente
2044
- request.secure? # false (sería true sobre ssl)
2045
- request.forwarded? # true (si se está corriendo atrás de un proxy reverso)
2046
- request.env # hash de entorno directamente entregado por Rack
2047
- end
2048
- ```
2049
-
2050
- Algunas opciones, como `script_name` o `path_info` pueden
2051
- también ser escritas:
2052
-
2053
- ```ruby
2054
- before { request.path_info = "/" }
2055
-
2056
- get "/" do
2057
- "todas las peticiones llegan acá"
2058
- end
2059
- ```
2060
-
2061
- El objeto `request.body` es una instancia de IO o StringIO:
2062
-
2063
- ```ruby
2064
- post "/api" do
2065
- request.body.rewind # en caso de que alguien ya lo haya leído
2066
- datos = JSON.parse request.body.read
2067
- "Hola #{datos['nombre']}!"
2068
- end
2069
- ```
2070
-
2071
- ### Archivos Adjuntos
2072
-
2073
- Puedes usar el helper `attachment` para indicarle al navegador que
2074
- almacene la respuesta en el disco en lugar de mostrarla en pantalla:
2075
-
2076
- ```ruby
2077
- get '/' do
2078
- attachment
2079
- "guardalo!"
2080
- end
2081
- ```
2082
-
2083
- También puedes pasarle un nombre de archivo:
2084
-
2085
- ```ruby
2086
- get '/' do
2087
- attachment "info.txt"
2088
- "guardalo!"
2089
- end
2090
- ```
2091
-
2092
- ### Fecha y Hora
2093
-
2094
- Sinatra pone a tu disposición el helper `time_for`, que genera un objeto `Time`
2095
- a partir del valor que recibe como argumento. Este valor puede ser un
2096
- `String`, pero también es capaz de convertir objetos `DateTime`, `Date` y de
2097
- otras clases similares:
2098
-
2099
- ```ruby
2100
- get '/' do
2101
- pass if Time.now > time_for('Dec 23, 2012')
2102
- "todavía hay tiempo"
2103
- end
2104
- ```
2105
-
2106
- Este método es usado internamente por métodos como `expires` y `last_modified`,
2107
- entre otros. Por lo tanto, es posible extender el comportamiento de estos
2108
- métodos sobreescribiendo `time_for` en tu aplicación:
2109
-
2110
- ```ruby
2111
- helpers do
2112
- def time_for(value)
2113
- case value
2114
- when :ayer then Time.now - 24*60*60
2115
- when :mañana then Time.now + 24*60*60
2116
- else super
2117
- end
2118
- end
2119
- end
2120
-
2121
- get '/' do
2122
- last_modified :ayer
2123
- expires :mañana
2124
- "hola"
2125
- end
2126
- ```
2127
-
2128
- ### Buscando los Archivos de las Plantillas
2129
-
2130
- El helper `find_template` se utiliza para encontrar los archivos de las
2131
- plantillas que se van a renderizar:
2132
-
2133
- ```ruby
2134
- find_template settings.views, 'foo', Tilt[:haml] do |archivo|
2135
- puts "podría ser #{archivo}"
2136
- end
2137
- ```
2138
-
2139
- Si bien esto no es muy útil, lo interesante es que puedes sobreescribir este
2140
- método, y así enganchar tu propio mecanismo de búsqueda. Por ejemplo, para
2141
- poder utilizar más de un directorio de vistas:
2142
-
2143
- ```ruby
2144
- set :views, ['vistas', 'plantillas']
2145
-
2146
- helpers do
2147
- def find_template(views, name, engine, &block)
2148
- Array(views).each { |v| super(v, name, engine, &block) }
2149
- end
2150
- end
2151
- ```
2152
-
2153
- Otro ejemplo consiste en usar directorios diferentes para los distintos motores
2154
- de renderizado:
2155
-
2156
- ```ruby
2157
- set :views, :sass => 'vistas/sass', :haml => 'plantillas', :defecto => 'vistas'
2158
-
2159
- helpers do
2160
- def find_template(views, name, engine, &block)
2161
- _, folder = views.detect { |k,v| engine == Tilt[k] }
2162
- folder ||= views[:defecto]
2163
- super(folder, name, engine, &block)
2164
- end
2165
- end
2166
- ```
2167
-
2168
- ¡Es muy fácil convertir estos ejemplos en una extensión y compartirla!
2169
-
2170
- Notá que `find_template` no verifica si un archivo existe realmente, sino
2171
- que llama al bloque que recibe para cada path posible. Esto no representa un
2172
- problema de rendimiento debido a que `render` va a usar `break` ni bien
2173
- encuentre un archivo que exista. Además, las ubicaciones de las plantillas (y
2174
- su contenido) se cachean cuando no estás en el modo de desarrollo. Es bueno
2175
- tener en cuenta lo anterior si escribís un método extraño.
2176
-
2177
- ## Configuración
2178
-
2179
- Ejecutar una vez, en el inicio, en cualquier entorno:
2180
-
2181
- ```ruby
2182
- configure do
2183
- # asignando una opción
2184
- set :opcion, 'valor'
2185
-
2186
- # asignando varias opciones
2187
- set :a => 1, :b => 2
2188
-
2189
- # atajo para `set :opcion, true`
2190
- enable :opcion
2191
-
2192
- # atajo para `set :opcion, false`
2193
- disable :opcion
2194
-
2195
- # también puedes tener configuraciones dinámicas usando bloques
2196
- set(:css_dir) { File.join(views, 'css') }
2197
- end
2198
- ```
2199
-
2200
- Ejecutar únicamente cuando el entorno (la variable de entorno APP_ENV) es
2201
- `:production`:
2202
-
2203
- ```ruby
2204
- configure :production do
2205
- ...
2206
- end
2207
- ```
2208
-
2209
- Ejecutar cuando el entorno es `:production` o `:test`:
2210
-
2211
- ```ruby
2212
- configure :production, :test do
2213
- ...
2214
- end
2215
- ```
2216
-
2217
- Puedes acceder a estas opciones utilizando el método `settings`:
2218
-
2219
- ```ruby
2220
- configure do
2221
- set :foo, 'bar'
2222
- end
2223
-
2224
- get '/' do
2225
- settings.foo? # => true
2226
- settings.foo # => 'bar'
2227
- ...
2228
- end
2229
- ```
2230
-
2231
- ### Configurando la Protección Contra Ataques
2232
-
2233
- Sinatra usa [Rack::Protection](https://github.com/sinatra/sinatra/tree/master/rack-protection#readme)
2234
- para defender a tu aplicación de los ataques más comunes. Si por algún motivo,
2235
- quieres desactivar esta funcionalidad, puedes hacerlo como se indica a
2236
- continuación (ten en cuenta que tu aplicación va a quedar expuesta a un
2237
- montón de vulnerabilidades bien conocidas):
2238
-
2239
- ```ruby
2240
- disable :protection
2241
- ```
2242
-
2243
- También es posible desactivar una única capa de defensa:
2244
-
2245
- ```ruby
2246
- set :protection, :except => :path_traversal
2247
- ```
2248
-
2249
- O varias:
2250
-
2251
- ```ruby
2252
- set :protection, :except => [:path_traversal, :session_hijacking]
2253
- ```
2254
-
2255
- ### Configuraciones Disponibles
2256
-
2257
- <dl>
2258
- <dt>absolute_redirects</dt>
2259
- <dd>
2260
- Si está deshabilitada, Sinatra va a permitir
2261
- redirecciones relativas, sin embargo, como consecuencia
2262
- de esto, va a dejar de cumplir con el RFC 2616 (HTTP
2263
- 1.1), que solamente permite redirecciones absolutas.
2264
- </dd>
2265
- <dd>
2266
- Activalo si tu apliación está corriendo atrás de un proxy
2267
- reverso que no se ha configurado adecuadamente. Notá que
2268
- el helper <tt>url</tt> va a seguir produciendo URLs absolutas, a
2269
- menos que le pasés <tt>false</tt> como segundo parámetro.
2270
- </dd>
2271
- <dd>Deshabilitada por defecto.</dd>
2272
- </dd>
2273
-
2274
- <dt>add_charset</dt>
2275
- <dd>
2276
- Tipos mime a los que el helper <tt>content_type</tt> les
2277
- añade automáticamente el charset. En general, no deberías
2278
- asignar directamente esta opción, sino añadirle los charsets
2279
- que quieras:
2280
- <tt>settings.add_charset &lt;&lt; "application/foobar"</tt>
2281
- </dd>
2282
-
2283
- <dt>app_file</dt>
2284
- <dd>
2285
- Path del archivo principal de la aplicación, se utiliza
2286
- para detectar la raíz del proyecto, el directorio de las
2287
- vistas y el público, así como las plantillas inline.
2288
- </dd>
2289
-
2290
- <dt>bind</dt>
2291
- <dd>
2292
- Dirección IP que utilizará el servidor integrado (por
2293
- defecto: <tt>0.0.0.0</tt> <em>o</em> <tt>localhost</tt>
2294
- si su `environment` está configurado para desarrollo).
2295
- </dd>
2296
-
2297
- <dt>default_encoding</dt>
2298
- <dd>
2299
- Encoding utilizado cuando el mismo se desconoce (por
2300
- defecto <tt>"utf-8"</tt>).
2301
- </dd>
2302
-
2303
- <dt>dump_errors</dt>
2304
- <dd>
2305
- Mostrar errores en el log.
2306
- </dd>
2307
-
2308
- <dt>environment</dt>
2309
- <dd>
2310
- Entorno actual, por defecto toma el valor de
2311
- <tt>ENV['APP_ENV']</tt>, o <tt>"development"</tt> si no
2312
- está disponible.
2313
- </dd>
2314
-
2315
- <dt>logging</dt>
2316
- <dd>
2317
- Define si se utiliza el logger.
2318
- </dd>
2319
-
2320
- <dt>lock</dt>
2321
- <dd>
2322
- Coloca un lock alrededor de cada petición, procesando
2323
- solamente una por proceso.
2324
- </dd>
2325
- <dd>
2326
- Habilitá esta opción si tu aplicación no es thread-safe.
2327
- Se encuentra deshabilitada por defecto.
2328
- </dd>
2329
-
2330
- <dt>method_override</dt>
2331
- <dd>
2332
- Utiliza el parámetro <tt>_method</tt> para permtir
2333
- formularios put/delete en navegadores que no los
2334
- soportan.
2335
- </dd>
2336
-
2337
- <dt>mustermann_opts</dt>
2338
- <dd>
2339
- Un hash predeterminado de opciones para pasar a Mustermann.new
2340
- al compilar las rutas.
2341
- </dd>
2342
-
2343
- <dt>port</dt>
2344
- <dd>
2345
- Puerto en el que escuchará el servidor integrado.
2346
- </dd>
2347
-
2348
- <dt>prefixed_redirects</dt>
2349
- <dd>
2350
- Define si inserta <tt>request.script_name</tt> en las
2351
- redirecciones cuando no se proporciona un path absoluto.
2352
- De esta manera, cuando está habilitada,
2353
- <tt>redirect '/foo'</tt> se comporta de la misma manera
2354
- que <tt>redirect to('/foo')</tt>. Se encuentra
2355
- deshabilitada por defecto.
2356
- </dd>
2357
-
2358
- <dt>protection</dt>
2359
- <dd>
2360
- Define si se habilitan o no las protecciones de ataques web.
2361
- Ver la sección de protección encima.
2362
- </dd>
2363
-
2364
- <dt>public_folder</dt>
2365
- <dd>
2366
- Lugar del directorio desde donde se sirven los archivos
2367
- públicos. Solo se utiliza cuando se sirven archivos
2368
- estáticos (ver la opción <tt>static</tt>). Si no
2369
- está presente, se infiere del valor de la opción
2370
- <tt>app_file</tt>.
2371
- </dd>
2372
-
2373
- <dt>quiet</dt>
2374
- <dd>
2375
- Inhabilita los logs generados por los comandos de inicio y detención de Sinatra.
2376
- <tt> false </tt> por defecto.
2377
- </dd>
2378
-
2379
- <dt>reload_templates</dt>
2380
- <dd>
2381
- Define Si se vuelven a cargar plantillas entre las solicitudes o no. Habilitado en
2382
- modo de desarrollo.
2383
- </dd>
2384
-
2385
- <dt>root</dt>
2386
- <dd>
2387
- Lugar del directorio raíz del proyecto. Si no está
2388
- presente, se infiere del valor de la opción
2389
- <tt>app_file</tt>.
2390
- </dd>
2391
-
2392
- <dt>raise_errors</dt>
2393
- <dd>
2394
- Elevar excepciones (detiene la aplicación). Se
2395
- encuentra activada por defecto cuando el valor de
2396
- <tt>environment</tt> es <tt>"test"</tt>. En caso
2397
- contrario estará desactivada.
2398
- </dd>
2399
-
2400
- <dt>run</dt>
2401
- <dd>
2402
- Cuando está habilitada, Sinatra se va a encargar de
2403
- iniciar el servidor web, no la habilites cuando estés
2404
- usando rackup o algún otro medio.
2405
- </dd>
2406
-
2407
- <dt>running</dt>
2408
- <dd>
2409
- Indica si el servidor integrado está ejecutándose, ¡no
2410
- cambiés esta configuración!.
2411
- </dd>
2412
-
2413
- <dt>server</dt>
2414
- <dd>
2415
- Servidor, o lista de servidores, para usar como servidor
2416
- integrado. El orden indica su prioridad, por defecto depende
2417
- de la implementación de Ruby.
2418
- </dd>
2419
-
2420
- <dt>server_settings</dt>
2421
- <dd>
2422
- Si está utilizando un servidor web WEBrick, presumiblemente para su entorno de desarrollo, puede pasar un hash de opciones a <tt> server_settings </tt>, como <tt> SSLEnable </tt> o <tt> SSLVerifyClient </tt>. Sin embargo, los servidores web como Puma no son compatibles, por lo que puede establecer <tt> server_settings </tt> definiéndolo como un método cuando llame a <tt> configure </tt>.
2423
- </dd>
2424
-
2425
- <dt>sessions</dt>
2426
- <dd>
2427
- Habilita el soporte de sesiones basadas en cookies a
2428
- través de <tt>Rack::Session::Cookie</tt>. Ver la
2429
- sección 'Usando Sesiones' para más información.
2430
- </dd>
2431
-
2432
- <dt>session_store</dt>
2433
- <dd>
2434
- Define el middleware de sesión Rack utilizado. Predeterminado a
2435
- <tt>Rack::Session::Cookie</tt>. Consulte la sección 'Uso de sesiones' para obtener más información.
2436
- información.
2437
- </dd>
2438
-
2439
- <dt>show_exceptions</dt>
2440
- <dd>
2441
- Muestra un stack trace en el navegador cuando ocurre una
2442
- excepción. Se encuentra activada por defecto cuando el
2443
- valor de <tt>environment</tt> es <tt>"development"</tt>.
2444
- En caso contrario estará desactivada.
2445
- </dd>
2446
- <dd>
2447
- También se puede establecer en <tt> :after_handler </tt> para activar la aplicación especificada
2448
- que hara el manejo de errores antes de mostrar un stack trace en el navegador.
2449
- </dd>
2450
-
2451
- <dt>static</dt>
2452
- <dd>
2453
- <dd> Define si Sinatra debe servir los archivos estáticos. </dd>
2454
- <dd> Deshabilitar cuando se utiliza un servidor capaz de hacer esto por su cuenta. </dd>
2455
- <dd> La desactivación aumentará el rendimiento. </dd>
2456
- <dd>
2457
- Habilitado por defecto en estilo clásico, deshabilitado para aplicaciones modulares.
2458
- </dd>
2459
- </dd>
2460
-
2461
- <dt>static_cache_control</dt>
2462
- <dd>
2463
- Cuando Sinatra está sirviendo archivos estáticos, y
2464
- esta opción está habilitada, les va a agregar encabezados
2465
- <tt>Cache-Control</tt> a las respuestas. Para esto
2466
- utiliza el helper <tt>cache_control</tt>. Se encuentra
2467
- deshabilitada por defecto. Notar que es necesario
2468
- utilizar un array cuando se asignan múltiples valores:
2469
- <tt>set :static_cache_control, [:public, :max_age => 300]</tt>.
2470
- </dd>
2471
-
2472
- <dt>threaded</dt>
2473
- <dd>
2474
- Si se establece en <tt> true </tt>, le dirá al servidor que use
2475
- <tt> EventMachine.defer </tt> para procesar la solicitud.
2476
- </dd>
2477
-
2478
- <dt> traps </dt>
2479
- <dd> Define si Sinatra debería manejar las señales del sistema. </dd>
2480
-
2481
- <dt>views</dt>
2482
- <dd>
2483
- Path del directorio de las vistas. Si no está presente,
2484
- se infiere del valor de la opción <tt>app_file</tt>.
2485
- </dd>
2486
- <dt>x_cascade</dt>
2487
- <dd>
2488
- Establece o no el encabezado de X-Cascade si no hay una coincidencia de ruta.
2489
- <tt> verdadero </tt> por defecto.
2490
- </dd>
2491
- </dl>
2492
-
2493
- ## Entornos
2494
-
2495
- Existen tres entornos (`environments`) predefinidos: `development`,
2496
- `production` y `test`. El entorno por defecto es
2497
- `development` y tiene algunas particularidades:
2498
-
2499
- * Se recargan las plantillas entre una petición y la siguiente, a diferencia
2500
- de `production` y `test`, donde se cachean.
2501
- * Se instalan manejadores de errores `not_found` y `error`
2502
- especiales que muestran un stack trace en el navegador cuando son disparados.
2503
-
2504
- Para utilizar alguno de los otros entornos puede asignarse el valor
2505
- correspondiente a la variable de entorno `APP_ENV`:
2506
- ```shell
2507
- APP_ENV=production ruby my_app.rb
2508
- ```
2509
-
2510
- Los métodos `development?`, `test?` y `production?` te permiten conocer el
2511
- entorno actual.
2512
-
2513
- ```ruby
2514
- get '/' do
2515
- if settings.development?
2516
- "development!"
2517
- else
2518
- "not development!"
2519
- end
2520
- end
2521
- ```
2522
-
2523
- ## Manejo de Errores
2524
-
2525
- Los manejadores de errores se ejecutan dentro del mismo contexto que las rutas
2526
- y los filtros `before`, lo que significa que puedes usar, por ejemplo,
2527
- `haml`, `erb`, `halt`, etc.
2528
-
2529
- ### Not Found
2530
-
2531
- Cuando se eleva una excepción `Sinatra::NotFound`, o el código de
2532
- estado de la respuesta es 404, el manejador `not_found` es invocado:
2533
-
2534
- ```ruby
2535
- not_found do
2536
- 'No existo'
2537
- end
2538
- ```
2539
-
2540
- ### Error
2541
-
2542
- El manejador `error` es invocado cada vez que una excepción es elevada
2543
- desde un bloque de ruta o un filtro. El objeto de la excepción se puede
2544
- obtener de la variable Rack `sinatra.error`:
2545
-
2546
- ```ruby
2547
- error do
2548
- 'Disculpá, ocurrió un error horrible - ' + env['sinatra.error'].message
2549
- end
2550
- ```
2551
-
2552
- Errores personalizados:
2553
-
2554
- ```ruby
2555
- error MiErrorPersonalizado do
2556
- 'Lo que pasó fue...' + env['sinatra.error'].message
2557
- end
2558
- ```
2559
-
2560
- Entonces, si pasa esto:
2561
-
2562
- ```ruby
2563
- get '/' do
2564
- raise MiErrorPersonalizado, 'algo malo'
2565
- end
2566
- ```
2567
-
2568
- Obtienes esto:
2569
-
2570
- ```
2571
- Lo que pasó fue... algo malo
2572
- ```
2573
-
2574
- También, puedes instalar un manejador de errores para un código de estado:
2575
-
2576
- ```ruby
2577
- error 403 do
2578
- 'Acceso prohibido'
2579
- end
2580
-
2581
- get '/secreto' do
2582
- 403
2583
- end
2584
- ```
2585
-
2586
- O un rango:
2587
-
2588
- ```ruby
2589
- error 400..510 do
2590
- 'Boom'
2591
- end
2592
- ```
2593
-
2594
- Sinatra instala manejadores `not_found` y `error` especiales
2595
- cuando se ejecuta dentro del entorno de desarrollo "development" y se muestran
2596
- en tu navegador para que tengas información adicional sobre el error.
2597
-
2598
- ## Rack Middleware
2599
-
2600
- Sinatra corre sobre [Rack](http://rack.github.io/), una interfaz minimalista
2601
- que es un estándar para frameworks webs escritos en Ruby. Una de las
2602
- características más interesantes de Rack para los desarrolladores de aplicaciones
2603
- es el soporte de "middleware" -- componentes que se ubican entre el servidor y
2604
- tu aplicación, supervisando y/o manipulando la petición/respuesta HTTP para
2605
- proporcionar varios tipos de funcionalidades comunes.
2606
-
2607
- Sinatra hace muy sencillo construir tuberías de Rack middleware a través del
2608
- método top-level `use`:
2609
-
2610
- ```ruby
2611
- require 'sinatra'
2612
- require 'mi_middleware_personalizado'
2613
-
2614
- use Rack::Lint
2615
- use MiMiddlewarePersonalizado
2616
-
2617
- get '/hola' do
2618
- 'Hola Mundo'
2619
- end
2620
- ```
2621
-
2622
- La semántica de `use` es idéntica a la definida para el DSL
2623
- [Rack::Builder](http://www.rubydoc.info/github/rack/rack/master/Rack/Builder) (más
2624
- frecuentemente usado en archivos rackup). Por ejemplo, el método `use`
2625
- acepta argumentos múltiples/variables así como bloques:
2626
-
2627
- ```ruby
2628
- use Rack::Auth::Basic do |nombre_de_usuario, password|
2629
- nombre_de_usuario == 'admin' && password == 'secreto'
2630
- end
2631
- ```
2632
-
2633
- Rack es distribuido con una variedad de middleware estándar para logging,
2634
- debugging, enrutamiento URL, autenticación y manejo de sesiones. Sinatra
2635
- usa muchos de estos componentes automáticamente de acuerdo a su configuración
2636
- para que usualmente no tengas que usarlas (con `use`) explícitamente.
2637
-
2638
- Puedes encontrar middleware útil en
2639
- [rack](https://github.com/rack/rack/tree/master/lib/rack),
2640
- [rack-contrib](https://github.com/rack/rack-contrib#readme),
2641
- o en la [Rack wiki](https://github.com/rack/rack/wiki/List-of-Middleware).
2642
-
2643
- ## Pruebas
2644
-
2645
- Las pruebas para las aplicaciones Sinatra pueden ser escritas utilizando
2646
- cualquier framework o librería de pruebas basada en Rack. Se recomienda usar
2647
- [Rack::Test](http://www.rubydoc.info/github/brynary/rack-test/master/frames):
2648
-
2649
- ```ruby
2650
- require 'mi_app_sinatra'
2651
- require 'minitest/autorun'
2652
- require 'rack/test'
2653
-
2654
- class MiAppTest < Minitest::Test
2655
- include Rack::Test::Methods
2656
-
2657
- def app
2658
- Sinatra::Application
2659
- end
2660
-
2661
- def test_mi_defecto
2662
- get '/'
2663
- assert_equal 'Hola Mundo!', last_response.body
2664
- end
2665
-
2666
- def test_con_parametros
2667
- get '/saludar', :name => 'Franco'
2668
- assert_equal 'Hola Frank!', last_response.body
2669
- end
2670
-
2671
- def test_con_entorno_rack
2672
- get '/', {}, 'HTTP_USER_AGENT' => 'Songbird'
2673
- assert_equal "Estás usando Songbird!", last_response.body
2674
- end
2675
- end
2676
- ```
2677
-
2678
- Nota: Si está utilizando Sinatra en el estilo modular, reemplace
2679
- `Sinatra::Application` anterior con el nombre de clase de su aplicación.
2680
-
2681
- ## Sinatra::Base - Middleware, Librerías, y Aplicaciones Modulares
2682
-
2683
- Definir tu aplicación en el nivel superior funciona bien para micro-aplicaciones
2684
- pero trae inconvenientes considerables a la hora de construir componentes
2685
- reutilizables como Rack middleware, Rails metal, librerías simples con un
2686
- componente de servidor o incluso extensiones de Sinatra. El DSL de alto nivel
2687
- asume una configuración apropiada para micro-aplicaciones (por ejemplo, un
2688
- único archivo de aplicación, los directorios `./public` y
2689
- `./views`, logging, página con detalles de excepción, etc.). Ahí es
2690
- donde `Sinatra::Base` entra en el juego:
2691
-
2692
- ```ruby
2693
- require 'sinatra/base'
2694
-
2695
- class MiApp < Sinatra::Base
2696
- set :sessions, true
2697
- set :foo, 'bar'
2698
-
2699
- get '/' do
2700
- 'Hola Mundo!'
2701
- end
2702
- end
2703
- ```
2704
-
2705
- Las subclases de `Sinatra::Base` tienen disponibles exactamente los
2706
- mismos métodos que los provistos por el DSL de top-level. La mayoría de las
2707
- aplicaciones top-level se pueden convertir en componentes
2708
- `Sinatra::Base` con dos modificaciones:
2709
-
2710
- * Tu archivo debe requerir `sinatra/base` en lugar de `sinatra`; de otra
2711
- manera, todos los métodos del DSL de sinatra son importados dentro del
2712
- espacio de nombres principal.
2713
- * Poné las rutas, manejadores de errores, filtros y opciones de tu aplicación
2714
- en una subclase de `Sinatra::Base`.
2715
-
2716
- `Sinatra::Base` es una pizarra en blanco. La mayoría de las opciones están
2717
- desactivadas por defecto, incluyendo el servidor incorporado. Mirá
2718
- [Opciones y Configuraciones](http://www.sinatrarb.com/configuration.html)
2719
- para detalles sobre las opciones disponibles y su comportamiento.
2720
- Si quieres un comportamiento más similar
2721
- a cuando defines tu aplicación en el nivel superior (también conocido como Clásico)
2722
- estilo), puede subclase `Sinatra::Aplicación`
2723
-
2724
- ```ruby
2725
- require 'sinatra/base'
2726
-
2727
- class MiAplicacion < Sinatra::Application
2728
- get '/' do
2729
- 'Hola Mundo!'
2730
- end
2731
- end
2732
- ```
2733
-
2734
- ### Estilo Modular vs. Clásico
2735
-
2736
- Contrariamente a la creencia popular, no hay nada de malo con el estilo clásico.
2737
- Si se ajusta a tu aplicación, no es necesario que la cambies a una modular.
2738
-
2739
- La desventaja de usar el estilo clásico en lugar del modular consiste en que
2740
- solamente puedes tener una aplicación Sinatra por proceso Ruby. Si tienes
2741
- planificado usar más, cambiá al estilo modular. Al mismo tiempo, ten en
2742
- cuenta que no hay ninguna razón por la cuál no puedas mezclar los estilos
2743
- clásico y modular.
2744
-
2745
- A continuación se detallan las diferencias (sútiles) entre las configuraciones
2746
- de ambos estilos:
2747
-
2748
- <table>
2749
- <tr>
2750
- <th>Configuración</th>
2751
- <th>Clásica</th>
2752
- <th>Modular</th>
2753
- <th>Modular</th>
2754
- </tr>
2755
-
2756
- <tr>
2757
- <td>app_file</td>
2758
- <td>archivo que carga sinatra</td>
2759
- <td>archivo con la subclase de Sinatra::Base</td>
2760
- <td>archivo con la subclase Sinatra::Application</td>
2761
- </tr>
2762
-
2763
- <tr>
2764
- <td>run</td>
2765
- <td>$0 == app_file</td>
2766
- <td>false</td>
2767
- <td>false</td>
2768
- </tr>
2769
-
2770
- <tr>
2771
- <td>logging</td>
2772
- <td>true</td>
2773
- <td>false</td>
2774
- <td>true</td>
2775
- </tr>
2776
-
2777
- <tr>
2778
- <td>method_override</td>
2779
- <td>true</td>
2780
- <td>false</td>
2781
- <td>true</td>
2782
- </tr>
2783
-
2784
- <tr>
2785
- <td>inline_templates</td>
2786
- <td>true</td>
2787
- <td>false</td>
2788
- <td>true</td>
2789
- </tr>
2790
-
2791
- <tr>
2792
- <td>static</td>
2793
- <td>true</td>
2794
- <td>File.exist?(public_folder)</td>
2795
- <td>true</td>
2796
- </tr>
2797
- </table>
2798
-
2799
- ### Sirviendo una Aplicación Modular
2800
-
2801
- Las dos opciones más comunes para iniciar una aplicación modular son, iniciarla
2802
- activamente con `run!`:
2803
-
2804
- ```ruby
2805
- # mi_app.rb
2806
- require 'sinatra/base'
2807
-
2808
- class MiApp < Sinatra::Base
2809
- # ... código de la app ...
2810
-
2811
- # iniciar el servidor si el archivo fue ejecutado directamente
2812
- run! if app_file == $0
2813
- end
2814
- ```
2815
-
2816
- Iniciar con:
2817
-
2818
- ```shell
2819
- ruby mi_app.rb
2820
- ```
2821
-
2822
- O, con un archivo `config.ru`, que permite usar cualquier handler Rack:
2823
-
2824
- ```ruby
2825
- # config.ru
2826
- require './mi_app'
2827
- run MiApp
2828
- ```
2829
-
2830
- Después ejecutar:
2831
-
2832
- ```shell
2833
- rackup -p 4567
2834
- ```
2835
-
2836
- ### Usando una Aplicación Clásica con un Archivo config.ru
2837
-
2838
- Escribí el archivo de tu aplicación:
2839
-
2840
- ```ruby
2841
- # app.rb
2842
- require 'sinatra'
2843
-
2844
- get '/' do
2845
- 'Hola mundo!'
2846
- end
2847
- ```
2848
-
2849
- Y el `config.ru` correspondiente:
2850
-
2851
- ```ruby
2852
- require './app'
2853
- run Sinatra::Application
2854
- ```
2855
-
2856
- ### ¿Cuándo usar config.ru?
2857
-
2858
- Indicadores de que probablemente quieres usar `config.ru`:
2859
-
2860
- * Quieres realizar el deploy con un handler Rack distinto (Passenger, Unicorn,
2861
- Heroku, ...).
2862
- * Quieres usar más de una subclase de `Sinatra::Base`.
2863
- * Quieres usar Sinatra únicamente para middleware, pero no como un endpoint.
2864
-
2865
- <b>No hay necesidad de utilizar un archivo `config.ru` exclusivamente
2866
- porque tienes una aplicación modular, y no necesitás una aplicación modular para
2867
- iniciarla con `config.ru`.</b>
2868
-
2869
- ### Utilizando Sinatra como Middleware
2870
-
2871
- Sinatra no solo es capaz de usar otro Rack middleware, sino que a su vez,
2872
- cualquier aplicación Sinatra puede ser agregada delante de un endpoint Rack
2873
- como middleware. Este endpoint puede ser otra aplicación Sinatra, o cualquier
2874
- aplicación basada en Rack (Rails/Ramaze/Camping/...):
2875
-
2876
- ```ruby
2877
- require 'sinatra/base'
2878
-
2879
- class PantallaDeLogin < Sinatra::Base
2880
- enable :sessions
2881
-
2882
- get('/login') { haml :login }
2883
-
2884
- post('/login') do
2885
- if params['nombre'] == 'admin' && params['password'] == 'admin'
2886
- session['nombre_de_usuario'] = params['nombre']
2887
- else
2888
- redirect '/login'
2889
- end
2890
- end
2891
- end
2892
-
2893
- class MiApp < Sinatra::Base
2894
- # el middleware se ejecutará antes que los filtros
2895
- use PantallaDeLogin
2896
-
2897
- before do
2898
- unless session['nombre_de_usuario']
2899
- halt "Acceso denegado, por favor <a href='/login'>iniciá sesión</a>."
2900
- end
2901
- end
2902
-
2903
- get('/') { "Hola #{session['nombre_de_usuario']}." }
2904
- end
2905
- ```
2906
-
2907
- ### Creación Dinámica de Aplicaciones
2908
-
2909
- Puede que en algunas ocasiones quieras crear nuevas aplicaciones en
2910
- tiempo de ejecución sin tener que asignarlas a una constante. Para
2911
- esto tienes `Sinatra.new`:
2912
-
2913
- ```ruby
2914
- require 'sinatra/base'
2915
- mi_app = Sinatra.new { get('/') { "hola" } }
2916
- mi_app.run!
2917
- ```
2918
-
2919
- Acepta como argumento opcional una aplicación desde la que se
2920
- heredará:
2921
-
2922
- ```ruby
2923
- # config.ru
2924
- require 'sinatra/base'
2925
-
2926
- controller = Sinatra.new do
2927
- enable :logging
2928
- helpers MisHelpers
2929
- end
2930
-
2931
- map('/a') do
2932
- run Sinatra.new(controller) { get('/') { 'a' } }
2933
- end
2934
-
2935
- map('/b') do
2936
- run Sinatra.new(controller) { get('/') { 'b' } }
2937
- end
2938
- ```
2939
-
2940
- Construir aplicaciones de esta forma resulta especialmente útil para
2941
- testear extensiones Sinatra o para usar Sinatra en tus librerías.
2942
-
2943
- Por otro lado, hace extremadamente sencillo usar Sinatra como
2944
- middleware:
2945
-
2946
- ```ruby
2947
- require 'sinatra/base'
2948
-
2949
- use Sinatra do
2950
- get('/') { ... }
2951
- end
2952
-
2953
- run ProyectoRails::Application
2954
- ```
2955
-
2956
- ## Ámbitos y Ligaduras
2957
-
2958
- El ámbito en el que te encuentras determina que métodos y variables están
2959
- disponibles.
2960
-
2961
- ### Ámbito de Aplicación/Clase
2962
-
2963
- Cada aplicación Sinatra es una subclase de `Sinatra::Base`. Si estás
2964
- usando el DSL de top-level (`require 'sinatra'`), entonces esta clase es
2965
- `Sinatra::Application`, de otra manera es la subclase que creaste
2966
- explícitamente. Al nivel de la clase tienes métodos como `get` o `before`, pero
2967
- no puedes acceder a los objetos `request` o `session`, ya que hay una única
2968
- clase de la aplicación para todas las peticiones.
2969
-
2970
- Las opciones creadas utilizando `set` son métodos al nivel de la clase:
2971
-
2972
- ```ruby
2973
- class MiApp < Sinatra::Base
2974
- # Ey, estoy en el ámbito de la aplicación!
2975
- set :foo, 42
2976
- foo # => 42
2977
-
2978
- get '/foo' do
2979
- # Hey, ya no estoy en el ámbito de la aplicación!
2980
- end
2981
- end
2982
- ```
2983
-
2984
- Tienes la ligadura al ámbito de la aplicación dentro de:
2985
-
2986
- * El cuerpo de la clase de tu aplicación
2987
- * Métodos definidos por extensiones
2988
- * El bloque pasado a `helpers`
2989
- * Procs/bloques usados como el valor para `set`
2990
- * El bloque pasado a `Sinatra.new`
2991
-
2992
- Este ámbito puede alcanzarse de las siguientes maneras:
2993
-
2994
- * A través del objeto pasado a los bloques de configuración (`configure { |c| ...}`)
2995
- * Llamando a `settings` desde dentro del ámbito de la petición
2996
-
2997
- ### Ámbito de Petición/Instancia
2998
-
2999
- Para cada petición entrante, una nueva instancia de la clase de tu aplicación
3000
- es creada y todos los bloques de rutas son ejecutados en ese ámbito. Desde este
3001
- ámbito puedes acceder a los objetos `request` y `session` o llamar a los métodos
3002
- de renderización como `erb` o `haml`. Puedes acceder al ámbito de la aplicación
3003
- desde el ámbito de la petición utilizando `settings`:
3004
-
3005
- ```ruby
3006
- class MiApp < Sinatra::Base
3007
- # Ey, estoy en el ámbito de la aplicación!
3008
- get '/definir_ruta/:nombre' do
3009
- # Ámbito de petición para '/definir_ruta/:nombre'
3010
- @valor = 42
3011
-
3012
- settings.get("/#{params['nombre']}") do
3013
- # Ámbito de petición para "/#{params['nombre']}"
3014
- @valor # => nil (no es la misma petición)
3015
- end
3016
-
3017
- "Ruta definida!"
3018
- end
3019
- end
3020
- ```
3021
-
3022
- Tienes la ligadura al ámbito de la petición dentro de:
3023
-
3024
- * bloques pasados a get, head, post, put, delete, options, patch, link y unlink
3025
- * filtros before/after
3026
- * métodos helpers
3027
- * plantillas/vistas
3028
-
3029
- ### Ámbito de Delegación
3030
-
3031
- El ámbito de delegación solo reenvía métodos al ámbito de clase. De cualquier
3032
- manera, no se comporta 100% como el ámbito de clase porque no tienes la ligadura
3033
- de la clase: únicamente métodos marcados explícitamente para delegación están
3034
- disponibles y no compartís variables/estado con el ámbito de clase (léase:
3035
- tienes un `self` diferente). Puedes agregar delegaciones de método llamando a
3036
- `Sinatra::Delegator.delegate :nombre_del_metodo`.
3037
-
3038
- Tienes és la ligadura al ámbito de delegación dentro de:
3039
-
3040
- * La ligadura del top-level, si hiciste `require "sinatra"`
3041
- * Un objeto extendido con el mixin `Sinatra::Delegator`
3042
-
3043
- Hechale un vistazo al código: acá está el
3044
- [Sinatra::Delegator mixin](https://github.com/sinatra/sinatra/blob/ca06364/lib/sinatra/base.rb#L1609-1633)
3045
- que [extiende el objeto main](https://github.com/sinatra/sinatra/blob/ca06364/lib/sinatra/main.rb#L28-30).
3046
-
3047
- ## Línea de Comandos
3048
-
3049
- Las aplicaciones Sinatra pueden ser ejecutadas directamente:
3050
-
3051
- ```shell
3052
- ruby myapp.rb [-h] [-x] [-q] [-e ENVIRONMENT] [-p PORT] [-o HOST] [-s HANDLER]
3053
- ```
3054
-
3055
- Las opciones son:
3056
-
3057
- ```
3058
- -h # ayuda
3059
- -p # asigna el puerto (4567 es usado por defecto)
3060
- -o # asigna el host (0.0.0.0 es usado por defecto)
3061
- -e # asigna el entorno (development es usado por defecto)
3062
- -s # especifica el servidor/manejador rack (puma es usado por defecto)
3063
- -q # activar el modo silecioso para el servidor (está desactivado por defecto)
3064
- -x # activa el mutex lock (está desactivado por defecto)
3065
- ```
3066
-
3067
- ### Multi-threading
3068
-
3069
- _Basado en [esta respuesta en StackOverflow](http://stackoverflow.com/questions/6278817/is-sinatra-multi-threaded/6282999#6282999) escrita por Konstantin_
3070
-
3071
- Sinatra no impone ningún modelo de concurrencia, sino que lo deja en manos del
3072
- handler Rack que se esté usando (Puma o WEBrick). Sinatra en sí mismo es
3073
- thread-safe, así que no hay problema en que el Rack handler use un modelo de
3074
- concurrencia basado en hilos.
3075
-
3076
- Esto significa que, cuando estemos arrancando el servidor, tendríamos que
3077
- especificar la opción adecuada para el handler Rack específico. En este ejemplo
3078
- vemos cómo arrancar un servidor Rainbows multihilo:
3079
-
3080
- ```ruby
3081
- # config.ru
3082
-
3083
- require 'sinatra/base'
3084
-
3085
- class App < Sinatra::Base
3086
- get '/' do
3087
- "¡Hola, Mundo!"
3088
- end
3089
- end
3090
-
3091
- run App
3092
- ```
3093
-
3094
- ```ruby
3095
- # rainbows.conf
3096
-
3097
- # El configurador de Rainbows está basado en Unicorn.
3098
-
3099
- Rainbows! do
3100
- use :ThreadSpawn
3101
- end
3102
- ```
3103
-
3104
- Para arrancar el servidor, el comando sería:
3105
-
3106
- ```shell
3107
- rainbows -c rainbows.conf
3108
- ```
3109
-
3110
- ## Requerimientos
3111
-
3112
- Las siguientes versiones de Ruby son soportadas oficialmente:
3113
-
3114
- <dl>
3115
- <dt>Ruby 2.3</dt>
3116
- <dd>
3117
- 2.3 Es totalmente compatible y recomendado. Actualmente no hay planes
3118
- soltar el apoyo oficial para ello.
3119
- </dd>
3120
-
3121
- <dt>Rubinius</dt>
3122
- <dd>
3123
- Rubinius es oficialmente compatible (Rubinius> = 2.x). Se recomienda instalar la gema puma
3124
- <tt>gem install puma</tt>.
3125
- </dd>
3126
-
3127
- <dt>JRuby</dt>
3128
- <dd>
3129
- La última versión estable de JRuby es oficialmente compatible. No lo es
3130
- recomienda usar extensiones C con JRuby. Se recomienda instalar la gema trinidad
3131
- <tt> gem install trinidad </tt>.
3132
- </dd>
3133
- </dl>
3134
-
3135
- Las versiones de Ruby anteriores a 2.2.2 ya no son compatibles con Sinatra 2.0 .
3136
-
3137
- Siempre le prestamos atención a las nuevas versiones de Ruby.
3138
-
3139
- Las siguientes implementaciones de Ruby no se encuentran soportadas
3140
- oficialmente. De cualquier manera, pueden ejecutar Sinatra:
3141
-
3142
- * Versiones anteriores de JRuby y Rubinius
3143
- * Ruby Enterprise Edition
3144
- * MacRuby, Maglev e IronRuby
3145
- * Ruby 1.9.0 y 1.9.1 (pero no te recomendamos que los uses)
3146
-
3147
- No ser soportada oficialmente, significa que si las cosas se rompen
3148
- ahí y no en una plataforma soportada, asumimos que no es nuestro problema sino
3149
- el suyo.
3150
-
3151
- También ejecutamos nuestro CI contra ruby-head (futuras versiones de MRI), pero
3152
- no puede garantizar nada, ya que se mueve constantemente. Esperar próxima
3153
- 2.x versiones para ser totalmente compatibles.
3154
-
3155
- Sinatra debería trabajar en cualquier sistema operativo compatible la implementación de Ruby
3156
- elegida
3157
-
3158
- Si ejecuta MacRuby, debe `gem install control_tower`.
3159
-
3160
- Sinatra actualmente no funciona con Cardinal, SmallRuby, BlueRuby o cualquier
3161
- versión de Ruby anterior a 2.2.
3162
-
3163
- ## A la Vanguardia
3164
-
3165
- Si quieres usar el código de Sinatra más reciente, sientete libre de ejecutar
3166
- tu aplicación sobre la rama master, en general es bastante estable.
3167
-
3168
- También liberamos prereleases de vez en cuando, así, puedes hacer:
3169
-
3170
- ```shell
3171
- gem install sinatra --pre
3172
- ```
3173
-
3174
- Para obtener algunas de las últimas características.
3175
-
3176
- ### Usando Bundler
3177
-
3178
- Esta es la manera recomendada para ejecutar tu aplicación sobre la última
3179
- versión de Sinatra usando [Bundler](http://bundler.io).
3180
-
3181
- Primero, instala Bundler si no lo hiciste todavía:
3182
-
3183
- ```shell
3184
- gem install bundler
3185
- ```
3186
-
3187
- Después, en el directorio de tu proyecto, creá un archivo `Gemfile`:
3188
-
3189
- ```ruby
3190
- source :rubygems
3191
- gem 'sinatra', :git => "git://github.com/sinatra/sinatra.git"
3192
-
3193
- # otras dependencias
3194
- gem 'haml' # por ejemplo, si usás haml
3195
- ```
3196
-
3197
- Ten en cuenta que tienes que listar todas las dependencias directas de tu
3198
- aplicación. No es necesario listar las dependencias de Sinatra (Rack y Tilt)
3199
- porque Bundler las agrega directamente.
3200
-
3201
- Ahora puedes arrancar tu aplicación así:
3202
-
3203
- ```shell
3204
- bundle exec ruby miapp.rb
3205
- ```
3206
-
3207
- ## Versionado
3208
-
3209
- Sinatra utiliza el [Versionado Semántico](http://semver.org/),
3210
- siguiendo las especificaciones SemVer y SemVerTag.
3211
-
3212
- ## Lecturas Recomendadas
3213
-
3214
- * [Sito web del proyecto](http://www.sinatrarb.com/) - Documentación
3215
- adicional, noticias, y enlaces a otros recursos.
3216
- * [Contribuyendo](http://www.sinatrarb.com/contributing) - ¿Encontraste un
3217
- error?. ¿Necesitas ayuda?. ¿Tienes un parche?.
3218
- * [Seguimiento de problemas](https://github.com/sinatra/sinatra/issues)
3219
- * [Twitter](https://twitter.com/sinatra)
3220
- * [Lista de Correo](http://groups.google.com/group/sinatrarb/topics)
3221
- * [IRC: #sinatra](irc://chat.freenode.net/#sinatra) en http://freenode.net
3222
- * [Sinatra & Friends](https://sinatrarb.slack.com) en Slack y revisa
3223
- [acá](https://sinatra-slack.herokuapp.com/) Para una invitación.
3224
- * [Sinatra Book](https://github.com/sinatra/sinatra-book/) Tutorial (en inglés).
3225
- * [Sinatra Recipes](http://recipes.sinatrarb.com/) Recetas contribuidas
3226
- por la comunidad (en inglés).
3227
- * Documentación de la API para la
3228
- [última versión liberada](http://www.rubydoc.info/gems/sinatra) o para la
3229
- [rama de desarrollo actual](http://www.rubydoc.info/github/sinatra/sinatra)
3230
- en http://www.rubydoc.info/
3231
- * [Servidor de CI](https://travis-ci.org/sinatra/sinatra)