ASCIIcasts - Full Episode Feed

Gráficas

Thu, 29 Jul 2010 07:51:51 +0000

Una buena forma de mostrar resúmenes o estadísticas, si tenemos una aplicación que contiene muchos datos, es mostrar una gráfica con dichos datos. A continuación se muestra una captura de pantalla de la interfaz administrativa de una aplicación de comercio electrónico. Cada pedido tiene un número de pedido, una fecha de compra, un campo que indica si el ítem ha sido enviado y su coste total. Este sistema contiene cientos de pedidos a lo largo de decenas de páginas, lo que hace que sea tedioso calcular a mano cualquier dato estadístico acerca de dichos datos.

Si tuviésemos una gráfica en la parte de superior de la página que mostrase un resumen de los pedidos a lo largo del tiempo nos sería mucho más fácil detectar tendencias en los datos de ventas. Eso es precisamente lo que haremos en este episodio.

Highcharts

Hay muchas librerías de gráficas disponibles pero la que vamos a usar es Highcharts. Se trata de una solución de cliente y utiliza JavaScript y SVG o VML, por lo que no hay dependencias de plugins como Flash o generadores de imágenes en el lado del servidor como ImageMagick. Como veremos, Highcharts puede generar gráficas atractivas con sólo unas líneas de JavaScript.

Hay que tener en cuenta, antes de considerar el uso de Highcharts para nuestros proyectos, que es gratuita sólo para proyectos no comerciales. Si este no es nuestro caso, veremos algunas alternativas más adelante.

Una vez que hayamos descargado Highcharts tendremos que extraer el fichero highcharts.js en el directorio /public/javascripts de nuestra aplicación. También tendremos que añadir la última versión de la librería jQuery y la versión compatible con jQuery de rails.js , que es necesaria porque se trata de una aplicación Rails 3. Hay más detalles de todo esto en el Episodio 205 [ verlo, leerlo].

Con estos archivos en su sitio ya podemos añadir la siguiente línea a la sección <head> del fichero de layout de nuestra aplicación, para que sean correctamente referenciados.

/app/views/layouts/applications.html.erb

<%= javascript_include_tag "jquery-1.4.2.min", "rails", "highcharts" %>

Highcharts depende de jQuery o MooTools, así que tendremos que incluir una de estas dos librerías antes de cargar el fichero highcharts.js.

Creación de una gráfica

Una vez que hemos instalado Highcharts podemos empezar añadiendo una gráfica a nuestra página de pedidos. Lo que queremos es añadir una gráfica de línea sencilla que muestre los ingresos obtenidos por día. Lo primero que tenemos que hacer es añadir un elemento vacío en la página de pedidos donde queremos que aparezca la gráfica.

/app/views/orders/index.html.erb

<%= will_paginate(@orders) %>

<div id="orders_chart" style="width: 560px; height: 300px;"></div>

<table class="pretty">
  <!-- Orders table code here -->
</table>

Tenemos que dar un id para poder identificarlo y para poder especificar un ancho y un alto. Por lo general definiríamos el estilo de un elemento en un fichero CSS separado, pero por comodidad lo hemos incluido aquí en el marcado HTML.

A continuación tenemos que añadir el JavaScript para generar la gráfica. Una vez más, en una aplicación de producción tendríamos que crear un fichero separado en lugar de embeberlo pero aquí seguiremos el enfoque más fácil. Nótese que si tuviésemos que extraer el JavaScript a su propio archivo esto tendría el efecto (no deseado) de que el código para generar la gráfica sería más complejo porque vamos a generar JavaScript dinámicamente con ERb. En una aplicación de producción haríamos esto realizando peticiones AJAX según cargue la página, pero con el código en línea que vamos a usar en nuestro ejemplo esto no será un problema.

Queremos que la gráfica sea sólo generada cuando el DOM de la página haya terminado de cargar por lo que rodearemos nuestro código de la función $ de jQuery de forma que el script no sea ejecutado hasta entonces. Dentro de la función crearemos el código necesario para generar una gráfica básica.

/app/views/orders/index.html.erb

<script type="text/javascript" charset="utf-8">
  $(function () {
    new Highcharts.Chart({
      chart: { renderTo: 'orders_chart' }
    });
  });
</script>

Hemos creado la gráfica con un nuevo objeto Highcharts.Chart y le hemos pasado un hash de opciones. Hay múltiples opciones que se le pueden pasar, merece la pena mirar la referencia de la web Highcharts para ver qué es lo que podemos usar.

Para empezar vamos a añadir la opción chart. Esta opción tiene a su vez una opción renderTo que recibe el id de una capa, por lo que le pasaremos el identificador de nuestra capa orders_chart.

Si ahora recargamos la página de pedidos deberíamos ver en la parte superior una gráfica vacía, lo que nos indica que estamos en el buen camino.

Ahora le vamos añadir más opciones a la gráfica y por supuesto algunos datos que dibujar. Vamos a añadir una opción title que tiene su propia opción text para establecer el título de la gráfica, una opción xAxis que tiene su opción type puesta a 'datetime' porque nuestra gráfica mostrará fechas en su eje X, una opción yAxis con el título 'Dollars' y por último los datos propiamente dichos.

Una gráfica puede visualizar varias series de datos por lo que tendremos que pasarle un array de hashes a la opción series. Cada uno de estos hashes puede contener cualquier número de puntos por lo que su valor es un array. En el código de abajo hemos creado una serie de datos con cinco valores para probar que nuestra gráfica funciona antes de añadir los datos de verdad.

/app/views/orders/index.html.erb

$(function () {
  new Highcharts.Chart({
    chart: { renderTo: 'orders_chart' },
    title: { text: 'Orders by Day' },
    xAxis: { type: 'datetime' },
    yAxis: {
      title: { text: 'Dollars'}
    },
    series: [{
      data: [1, 2, 5, 7, 3]
    }]
  });
});

Si recargamos la página veremos que ahora se dibuja la gráfica con sus cinco puntos de datos obtenidos del array. Todavía tenemos que trabajar en la línea temporal del eje X pero por ahora estamos avanzando adecuadamente.

En la opción series podemos activar un par de opciones para especificar el punto de inicio y el intervalo entre puntos en el eje X. La primera es pointInterval que recibe un número que representa el tiempo entre fechas en milisegundos. Utilizaremos esta opción para que entre cada punto haya un día, y utilizaremos un poco de código ERb para calcular el número de milisegundos que hay en un día. El código Ruby 1.day nos dará el número de segundos que hay en un día, que tenemos que multiplicar por 1000 para obtener el valor en milisegundos que Highcharts necesita.

La segunda opción es pointStart, que define la fecha y hora del primer punto. Esta opción requiere, igual que antes, un número de milisegundos y si bien en una aplicación "de verdad" utilizaríamos algo más dinámico para definir la fecha de comienzo aquí utilizaremos una fecha de hace tres semanas, nuevamente utilizando ERb para recuperar ese valor en segundos y multiplicándolo por 1000.

/app/views/orders/index.html.erb

$(function () {
  new Highcharts.Chart({
    chart: { renderTo: 'orders_chart' },
    title: { text: 'Orders by Day' },
    xAxis: { type: 'datetime' },
    yAxis: {
      title: { text: 'Dollars' }
    },
    series: [{
      pointInterval: <%= 1.day * 1000 %>,
      pointStart: <%= 3.weeks.ago.at_midnight.to_i * 1000 %>,
      data: [1, 2, 5, 7, 3]
    }]
  });
});

Si ahora recargamos la página de pedidos el eje X ya muestra las fechas.

Inclusión de datos reales

Una vez que tenemos la gráfica configurada a nuestro gusto podemos reemplazar los datos de prueba con datos reales obtenidos de nuestra tabla de pedidos. Primero veremos la manera ineficiente de hacerlo porque es más fácil escribir el código de esta manera y luego veremos cómo optimizarlo todo al final del episodio.

Necesitaremos la suma del todal de los pedidos de cada día, así que tendremos que escribir un método de clase en el modelo Order para recuperar todas las compras de un día determinado y calcular la suma del atributo total_price de cada una de ellas.

/app/models/order.rb

class Order < ActiveRecord::Base
  def self.total_on(date)
    where("date(purchased_at) = ?",date).sum(:total_price)
  end
end

Ahora ya podemos usar este método para recuperar los datos de cada uno de los días que aparece en la gráfica y podemos reemplazar los datos de prueba con el siguiente código:

/app/views/orders/index.html.erb

series: [{
  pointInterval: <%= 1.day * 1000 %>,
  pointStart: <%= 3.weeks.ago.at_midnight.to_i * 1000 %>,
  data: <%= (3.weeks.ago.to_date..Date.today).map { |date| Order.total_on(date).to_f}.inspect %>
 }]

En el código ERb anterior creamos un rango de fechas entre hoy y tres semanas antes y luego usamos el método map para iterar sobre ese rango y recuperar el total de los pedidos de cada día. Aplicamos inspect sobre el resultado para convertirlo a algo que pueda usarse desde JavaScript.

Si recargamos la página otra vez veremos que ya no salen nuestros datos de prueba y que ahora aparecen los datos reales de las últimas tres semanas, con un punto para cada día y los ingresos totales de los pedidos de cada día en dólares.

Tooltips

Aunque nuestra gráfica tiene buen aspecto la información que aparece cuando ponemos el ratón sobre uno de los puntos es mejorable. Podemos hacerlo añadiendo la opción tooltip al código de la gráfica.

/app/views/orders/index.html.erb

$(function () {
  new Highcharts.Chart({
    chart: { renderTo: 'orders_chart' },
    title: { text: 'Orders by Day' },
    xAxis: { type: 'datetime' },
    yAxis: {
      title: { text: 'Dollars' }
    },
    tooltip: {
      formatter: function () {
        return Highcharts.dateFormat("%B %e %Y", this.x) + ': ' +
          '$' + Highcharts.numberFormat(this.y, 2);
      }
    },    
    series: [{
      pointInterval: <%= 1.day * 1000 %>,
      pointStart: <%= 3.weeks.ago.at_midnight.to_i * 1000 %>,
      data: <%= (3.weeks.ago.to_date..Date.today).map { |date| Order.total_on(date).to_f}.inspect %>
    }]
  });
});

Esta opción tiene su propia opción formatter que recibe una función como argumento, la cual debe devolver una cadena que es lo que aparecerá como texto del tooltip. Para esto se pueden utilizar algunos formateadores que proporciona Highcharts, por ejemplo en el código anterior hemos usado dos: uno para formatear la fecha del eje X y otro para el valor numérico del eje Y.

Si volvemos a recargar la página y ponemos el ratón sobre uno de los puntos veremos nuestro tooltip pulcramente formateado.

Visualización de múltiples series

Con esta gráfica de nuestros pedidos es fácil ver tendencias en los datos. En la gráfica anterior puede verse que ha habido un incremento de órdenes desde el 19 de Julio. Para determinar qué es lo que ha causado este alza en las ventas podemos reemplazar la serie que muestra las ventas totales por dos que muestren las ventas de descargas (las que tienen un valor shipping a false) y las ventas físicas.

Vamos a tener que distinguir los pedidos que fueron enviados de los que fueron descargados así que lo primero que haremos será añadir dos ámbitos a nuestra clase Order para que podamos recuperar fácilmente cada tipo de pedido.

/app/models/order.rb

class Order < ActiveRecord::Base
  scope :shipping, where(:shipping => true)
  scope :download, where(:shipping => false)

  def self.total_on(date)
    where("date(purchased_at) = ?",date).sum(:total_price)
  end
end

De vuelta en el código JavaScript de la vista de pedidos tenemos que añadir otra opción series de forma que se dibujen dos conjuntos de datos. Para distinguir las dos series les hemos dado a cada una de ellas un nombre diferente.

/app/views/orders/index.html.erb

$(function () {
  new Highcharts.Chart({
    chart: { renderTo: 'orders_chart' },
    title: { text: 'Orders by Day' },
    xAxis: { type: 'datetime' },
    yAxis: {
      title: { text: 'Dollars' }
    },
    tooltip: {
      formatter: function () {
        return Highcharts.dateFormat("%B %e %Y", this.x) + ': ' +
          '$' + Highcharts.numberFormat(this.y, 2);
      }
    },    
    series: [{
      name: "Shipping",
      pointInterval: <%= 1.day * 1000 %>,
      pointStart: <%= 3.weeks.ago.at_midnight.to_i * 1000 %>,
      data: <%= (3.weeks.ago.to_date..Date.today).map { |date| Order.shipping.total_on(date).to_f}.inspect %>
    },
    {
      name: "Download",
      pointInterval: <%= 1.day * 1000 %>,
      pointStart: <%= 3.weeks.ago.at_midnight.to_i * 1000 %>,
      data: <%= (3.weeks.ago.to_date..Date.today).map { |date| Order.download.total_on(date).to_f}.inspect %>
    }]
  });
});

Ahora tenemos dos series y hemos usado el correspondiente ámbito en cada uno de ellos para recuperar los datos relevantes para cada día. Lá gráfica ahora mostrará ambas series, con sus nombres en la leyenda inferior.

Ahora podemos ver los totales de ventas físicas y descargadas y podemos ver que el pico de pedidos de los últimos días se corresponde con un incremento en las ventas tanto físicas como de descargas. Obsérvese que cuando un gráfico muestra más de una serie podemos hacer clic en la leyenda para ocultar o mostrar dicha serie.

Eliminando la duplicación

Al añadir una segunda serie a la gráfica hemos introducido cierta duplicidad en el código JavaScript con el problema de que si quisiéramos añadir más series tendríamos que repetirnos todavía más. Podemos atajar este problema utilizando un poco de código Ruby para generar dinámicamente el código JavaScript de cada serie.

/app/views/orders/index.html.erb

$(function () {
  new Highcharts.Chart({
    chart: { renderTo: 'orders_chart' },
    title: { text: 'Orders by Day' },
    xAxis: { type: 'datetime' },
    yAxis: {
      title: { text: 'Dollars' }
    },
    tooltip: {
      formatter: function () {
        return Highcharts.dateFormat("%B %e %Y", this.x) + ': ' +
          '$' + Highcharts.numberFormat(this.y, 2);
      }
    },    
    series: [
      <% { "Download" => Order.download, "Shipping" => Order.shipping }.each do |name, order| %>
    {
      name: "<%= name %>",
      pointInterval: <%= 1.day * 1000 %>,
      pointStart: <%= 3.weeks.ago.at_midnight.to_i * 1000 %>,
      data: <%= (3.weeks.ago.to_date..Date.today).map { |date| order.total_on(date).to_f}.inspect %>
    },
    <% end %>]
  });
});

En lugar de definir cada serie por separado ahora tenemos un hash que define el nombre de cada serie y el código que hay que usar para recuperar los pedidos de cada serie. Luego podemos iterar por ese hash y generar el JavaScript de la serie correspondiente.

Optimización de la consulta

La gráfica ya muestra la información que queremos pero el SQL que se está usando para recuperar los datos es bastante ineficiente. El log de desarrollo nos revela que se hace una consulta separada para cada nodo de la gráfica.

  SQL (0.6ms)  SELECT SUM("orders"."total_price") AS sum_id FROM "orders" WHERE ("orders"."shipping" = 't') AND (date(purchased_at) = '2010-07-18')
  SQL (0.6ms)  SELECT SUM("orders"."total_price") AS sum_id FROM "orders" WHERE ("orders"."shipping" = 't') AND (date(purchased_at) = '2010-07-19')
  SQL (0.6ms)  SELECT SUM("orders"."total_price") AS sum_id FROM "orders" WHERE ("orders"."shipping" = 't') AND (date(purchased_at) = '2010-07-20')
  SQL (0.6ms)  SELECT SUM("orders"."total_price") AS sum_id FROM "orders" WHERE ("orders"."shipping" = 't') AND (date(purchased_at) = '2010-07-21')
  SQL (0.7ms)  SELECT SUM("orders"."total_price") AS sum_id FROM "orders" WHERE ("orders"."shipping" = 't') AND (date(purchased_at) = '2010-07-22')

Podemos mejorar esto de forma que se lance una única llamada para cada serie utilizando los métodos group y select. Queremos recuperar los pedidos del modelo Order y agruparlos por su purchase_date y para cada grupo de órdenes devuelto queremos la fecha y el precio total. El siguiente código hace eso:

Order.group("date(purchased_at)").select("purchased_at, sum(total_price) as total_price")

Podemos comprobarlo en la consola y recuperar el total_price del primer ítem devuelto por la consulta.

> Order.group("date(purchased_at)").select("purchased_at, sum(total_price) as total_price").first.total_price.to_f
 => 403.0

Pero hay un ligero problema con este enfoque. Si no hay pedidos en un día determinado tendremos un punto ausente en los datos devueltos por lo que el resto de puntos posteriores estarán desplazados un día en la gráfica. Tenemos que tener en cuenta esta posibilidad, lo que va a complicar el código. Para organizarlo lo mejor posible, vamos a llevar esto a un método helper.

/app/views/orders/index.html.erb

$(function () {
  new Highcharts.Chart({
    chart: { renderTo: 'orders_chart' },
    title: { text: 'Orders by Day' },
    xAxis: { type: 'datetime' },
    yAxis: {
      title: { text: 'Dollars' }
    },
    tooltip: {
      formatter: function () {
        return Highcharts.dateFormat("%B %e %Y", this.x) + ': ' +
          '$' + Highcharts.numberFormat(this.y, 2);
      }
    },    
    series: [
      <% { "Both" => Order, "Download" => Order.download, "Shipping" => Order.shipping }.each do |name, order| %>
    {
      name: "<%= name %>",
      pointInterval: <%= 1.day * 1000 %>,
      pointStart: <%= 3.weeks.ago.at_midnight.to_i * 1000 %>,
      data: <%= orders_chart_series(orders, 3.weeks.ago) %>
    },
    <% end %>]
  });
});

Hemos reemplazado el código que recupera los datos por una llamada a un método llamado orders_chart_series que recibe como argumentos el ámbito relevante del modelo Order y la fecha de inicio de la serie. Vamos a escribir este nuevo método en el módulo OrdersHelper.

/app/helpers/orders_helper.rb

module OrdersHelper
  def orders_chart_series(orders, start_time)
    orders_by_day = orders.where(:purchased_at => start_time.beginning_of_day..Time.zone.now.end_of_day).
                    group("date(purchased_at)").
                    select("purchased_at, sum(total_price) as total_price")
    (start_time.to_date..Date.today).map do |date|
      order = orders_by_day.detect { |order| order.purchased_at.to_date == date }
      order && order.total_price.to_f || 0
    end.inspect
  end
end

En el método orders_chart_series pasamos el ámbito orders y recuperamos los pedidos que entran dentro del rango de fechas entre start_time y la fecha de hoy. Después agrupamos los resultados por día y escogemos la fecha y el total de pedidos de dicho día. Por último iteramos sobre el rango de fechas para recuperar el total de pedidos de cada día, introduciendo un 0 si no se hicieron pedidos ese día.

Si recargamos la página y miramos el log de desarrollo veremos que ahora hemos reducido a dos el número de consultas a la base de datos.

  Order Load (2.6ms)  SELECT purchased_at, sum(total_price) as total_price FROM "orders" WHERE ("orders"."shipping" = 'f') AND ("orders"."purchased_at" BETWEEN '2010-07-01 00:00:00.000000' AND '2010-07-22 23:59:59.999999') GROUP BY date(purchased_at)
  Order Load (1.5ms)  SELECT purchased_at, sum(total_price) as total_price FROM "orders" WHERE ("orders"."shipping" = 't') AND ("orders"."purchased_at" BETWEEN '2010-07-01 00:00:00.000000' AND '2010-07-22 23:59:59.999999') GROUP BY date(purchased_at)

Alternativas

Highcharts es una librería de gráficas excelente pero puede que no sea exactamente lo que estamos buscando, por lo que finalizaremos este episodio recorriendo algunas alternativas.

La primera de ellas es Flot. También utiliza JavaScript y puede usarse para generar gráficos bastante bonitos.

Otra librería basada en JavaScript es gRraphaël. Es muy útil para generar diagramas de barra o tarta, por lo que se recomienda echarle un vistazo si tenemos que generar este tipo de gráficas.

Y por último tenemos Bluff. Está basada en la librería Gruff de Ruby. Es una solución muy bonita y sencilla, por lo que si buscamos una solución ligera podría interesarnos.

Y eso es todo por este episodio. Si necesitamos mostrar gráficas en nuestra aplicación tenemos muchas opciones donde escoger.

Rack y Rails 3

Thu, 29 Jul 2010 07:48:39 +0000

En el episodio 203 [verlo, leerlo] le dimos un repaso al sistema de rutas de Rails 3, pero se nos quedaron en el tintero algunas funcionalidades avanzadas que pueden sacar todo el partido a la flexibilidad del enrutador de Rails 3. Veremos algunas de ellas en este episodio.

Rutas para aplicaciones Rack

Comenzaremos con un ejemplo sencillo. Nuestra aplicación de ejemplo tiene una ruta que apunta su URL raíz a la acción index del controlador HomeController’s index.

/config/routes.rb

Store::Application.routes.draw do |map|
  root :to => "home#index"
end

Lo importante aquí es saber que la cadena "home#index" es una abreviatura y por debajo dicha cadena se convierte a:

HomeController.action(:index)

El método action devuelve una aplicación Rack, y por tanto es fácil obtener una aplicación Rack a partir de cualquier controlador Rails. Como demostración, vamos a crear una aplicación Rack sencilla pasándole el hash de entorno a un nuevo objeto proc, devolviendo un array con un código de estado, un hash de cabeceras vacío y el contenido.

/config.routes.rb

Store::Application.routes.draw do |map|
  root :to => proc { |env| [200, {}, ["Welcome"]] }
end

Si visitamos la URL raíz de nuestra aplicación veremos dicha respuesta.

Toda esta flexibilidad hace que sea muy fácil integrar cualquier aplicación basada en Rack dentro de una aplicación Rails. Veámoslo con Sinatra.

Primero tenemos que añadir una referencia a la gema Sinatra en el fichero Gemfile de nuestra aplicación.

/Gemfile

gem 'sinatra'

Nos aseguraremos de que la gema está instalada ejecutando

bundle install

Ya podemos escribir nuestra aplicación Sinatra. La vamos a poner en el directorio /lib, y la llamaremos home_app.rb. Tenemos que crear una clase que herede de Sinatra::Base con un método get para la URL raíz que devuelve una cadena.

/lib/home_app.rb

class HomeApp < Sinatra::Base
  get "/" do
    "Hello from Sinatra"
  end
end

Ahora ya podemos actualizar el fichero de rutas para que la ruta raíz apunte a nuestra aplicación Rack HomeApp.

/config/routes.rb

Store::Application.routes.draw do |map|
  root :to => HomeApp
end

Si recargamos la portada de la aplicación ahora veremos la respuesta de la aplicación Sinatra.

Redirecciones

Uno de los beneficios de la integración de Rack con Rails es el nuevo método redirect, que veremos a continuación cómo funciona. Supongamos que nuestra aplicación tiene una ruta para mostra una página de información con la URL /about, que está mapeada a la acción about del controlador InfoController.

/config/routes.rb

Store::Application.routes.draw do |map|
  root :to => HomeApp
  match "/about" => "info#about" 
end

Si por ejemplo queremos cambiar la URL de /about a /aboutus podríamos cambiar fácilmente la ruta, pero entonces tendríamos que ver qué hacemos con la URL antigua que ya no mapea a ninguna acción. Pero ahora con Rails 3 podemos hacer redirecciones fácilmente con el método redirect.

/config/routes.rb

Store::Application.routes.draw do |map|
  root :to => HomeApp
  match "/about" => redirect("/aboutus")
  match "/aboutus" => "info#about" 
end

Con esta redirección la antigua ruta redirigirá a la nueva, por tanto si visitamos la URL /about seremos redirigidos a /aboutus.

Veamos a continuación un ejemplo del uso de redirect un poco más complicado. Supongamos que tenemos un controlador ProductsController y queremos tener una URL de atajo de la forma /p/:id para cada producto. Para eso podemos modificar las rutas de esta forma:

/config/routes.rb

Store::Application.routes.draw do |map|
  get "info/about"

  root :to => HomeApp
  match "/about" => redirect("/aboutus")
  match "/aboutus" => "info#about" 
  
  resources :products
  match "/p/:id" => redirect("/products/%{id}")
end

La ruta abreviada de un producto es la última ruta del archivo. Redirige la URL abreviada a la URL normal de un producto utilizando otra vez el método redirect pero esta vez lo hace a una URL dinámica. Para poder poner el id del producto en la URL redirigida tenemos que usar un signo de porcentaje seguido del parámetro id rodeado de llaves.

Si ahora visitamos la URL http://localhost:3000/p/1 seremos redirigidos a la página de ese producto.

Aunque no lo veremos por ahora, si necesitamos más control sobre la redirección le podemos pasar un bloque al método redirect. Los detalles sobre cómo hacerlo están en el sitio de rails.info.

Rails Metal

En el episodio 150 repasamos Rails Metal [verlo, leero] y creamos una página que listaba los procesos en ejecución en un momento dado. En Rails 3 la técnica es bastante diferente pero es mucho más fácil de usar gracias a la integración de Rack. Primero tenemos que crear la nueva ruta y hacer que apunte a la nueva aplicación Rack que bautizaremos como ProcessesApp.

/config/routes.rb

match "/processes" => ProcessesApp

Crearemos la aplicación en el directorio /lib, donde editaremos el fichero processes_app.rb. La clase tendrá un método de clase llamado call que recibe un hash de entorno, en el cual ejecutaremos el mismo comando que en el episodio 150 y devolveremos el resultado.

/lib/processes_app.rb

class ProcessesApp
  def self.call(env)
    [200, {}, [`ps -axcr -o "pid,pcpu, pmem, time, comm"`]]
  end
end

Si vamos a la página de procesos en el navegador, veremos el listado de procesos, y se puede comprobar que la página se recarga muy rápidamente porque estamos usando una sencilla aplicación Rack.

La clase ProcessApp no tiene nada de especial (en realidad se trata de una aplicación Rack sencilla), pero queda claro que con unas pocas líneas de código hemos reproducido el comportamiento del episodio 150 de una manera mucho más fácil.

No tenemos control alguno sobre el aspecto de la página de procesos porque la respuesta no pasa por ninguna plantilla. Sin embargo podemos expandir nuestra aplicación Rack para que incluya el comportamiento de un controlador Rails, lo que permitiría usar plantillas y hacer que la página fuese menos plana.

Para que la página de procesos pueda mostrar una plantilla erb en lugar de la salida en crudo del comando ps tan sólo tenemos que asegurarnos de que la clase ProcessesApp herede de ActionController::Metal, con lo que adquirirá ciertos comportamientos de los controladores de nuestra aplicación Rails, pero lo hará a un nivel tan bajo que tenemos también que incluir ActionController::Rendering para tener todo lo que nos hace falta.

Dado que el código que estamos usando funciona a un nivel más bajo que un controlador Rails normal tenemos que especificar la ubicación de las vistas invocando al método de Rails append_view_path y pasándole el path al directorio views de nuestra aplicación, con lo que nuestro controlador busque sus plantillas en el mismo lugar que un controlador normal.

Queremos que el controlador tenga una acción index por lo que hemos cambiado el método self.call por un método index que hace la misma llamada a ps pero asignando la salida a una variable de instancia. Después el método llama a render para mostrar la plantilla. Al contrario que en un controlador Rails normal la plantilla se muestra automáticamente.

/lib/processes_app.rb

class ProcessesApp < ActionController::Metal
  include ActionController::Rendering
  
  append_view_path "#{Rails.root}/app/views"
  
  def index
    @processes = `ps -axcr -o "pid,pcpu, pmem, time, comm"`
    render
  end
end

Ahora tenemos que crear la plantilla. En el directorio views de nuestra aplicación crearemos el directorio process_app en el que pondremos nuestra nueva plantilla, en la que podemos escribir el código que queramos en este archivo como haríamos con una plantilla erb normal.

/app/views/processes_app/index.html.erb

<h1>Processes</h1>
<pre><%= @processes %></pre>

Ya casi hemos terminado. Lo único que tenemos que hacer es modificar la ruta para que apunte a esta acción específica.

/config/routes.rb

match "/processes" => ProcessesApp.action(:index)

Si reiniciamos el servidor y visitamos otra vez la página de procesos veremos que ya se usa nuestra plantilla.

Tal y como acabamos de ver, Rails 3 es muy modular y nos permite poner en nuestras aplicaciones Rack justo sólo la funcionalidad que queramos. Hay que tener en cuenta que escribir un controlador de esta manera sólo nos ahorrará un par de milisegundos en el mejor de los casos, por lo que lo mejor es crear primero un controlador Rails normal y luego hacer pruebas de rendimiento antes de escribir una aplicación Rack tal y como hemos hecho en este episodio.

Subdominios con Rails 3

Tue, 27 Jul 2010 09:49:06 +0000

Ya han pasado casi dos años desde que tratamos de los subdominios por última vez. En Rails 3 se ha añadido soporte para los subdominios y en este episodio veremos qué cosas nuevas podemos hacer.

Vamos a trabajar con la misma aplicación del episodio dedicado a los subdominios: se trata de un sencilla aplicación que soporta múltiples blogs. Debajo se muestra la portada en la que aparece un listado de todos los blogs. Cada blog tiene varios artículos asociados.

Si hacemos clic en el enlace para editar un blog veremos que cada uno de ellos tiene dos atributos: name y subdomain. Queremos utilizar el atributo subdomain como subdominio de la URL de dicho blog.

Configuración de subdominios en el entorno de desarrollo

Lo primero que tenemos que resolver es cómo encontrar una forma de gestionar los subdominios en el entorno de desarrollo. La URL de nuestra aplicación es http://localhost:3000 que no permite subdominios, por lo que tendremos que usar algún método alternativo.

Una forma de hacerlo podría ser configurando nuestra aplicación para utilizar Passenger. Podríamos entonces darle un dominio de tipo http://blog.local y editar el fichero /etc/hosts para configurar subdominios de esta manera:

/etc/hosts

127.0.0.1 personal.blog.local company.blog.local

Lo ideal sería poder utilizar un carácter comodín que casase con cualquier subdominio de forma que no tuviésemos que estar continuamente cambiando este archivo durante el desarrollo de nuestra aplicación, pero por desgracia esto no es posible así que tenemos que buscar otra posibilidad.

Una buena solución es la que que ha presentado Tim Pope en su blog. Ha comprado el dominio smackaho.st y ha hecho que sea comodín de localhost. Uno de los comentaristas en ese blog ha hecho algo parecido con un dominio similar, llamado lvh.me, y éste es el dominio que vamos a usar.

Si abrimos http://lvh.me:3000/ veremos la página de nuestra aplicación porque el dominio lvh.me resuelve a la dirección IP 127.0.0.1. La diferencia es que ahora podemos añadir delante cualquier subdominio a la URL y este seguirá apuntando a la misma aplicación.

Como ya podemos usar subdominios en nuestra aplicación, ya podemos configurar sus rutas para que el subdominio personal vaya a la acción show del blog correspondiente. Este es el aspecto de nuestro fichero de rutas:

/config/routes.rb

Bloggit::Application.routes.draw do |map|
  resources :comments
  resources :articles
  resources :blogs
  root :to => "blogs#index"
end

Ahora mismo la ruta raíz va a la acción blogs/index. Queremos que esto ocurra sólo si no se ha especificado ningún subdominio, si lo hubiera habría que mostrar la acción blogs/show. Esto en Rails 3 puede hacerse añadiendo una restricción.

/config/routes.rb

Bloggit::Application.routes.draw do |map|
  resources :comments
  resources :articles
  resources :blogs
  match '/' => 'blogs#show', :constraints => { :subdomain => /.+/ }
  root :to => "blogs#index"
end

Esta funcionalidad (que ya viene incorporada en Rails 3) habría requerido el uso de un plugin si nuestra aplicación utilizase Rails 2. La opcíon :subdomain recibe o bien una cadena o una expresión regular, que es lo que hemos usado nosotros, para aceptar cualquier subdominio que tenga al menos una letra. Obsérvese que es importante que la ruta raíz aparezca después de la ruta de subdominio o de lo contrario la ruta raíz tendrá preferencia sobre las rutas de subdominios, por las que nunca pasaremos. Como regla general cuanto más específica es una ruta debería aparecer más arriba en la lista de rutas.

Si ahora visitamos el subdominio personal veremos un error que era de esperar porque estamos en la acción show de BlogsController a la que no le hemos pasado un id.

Esto es fácil de arreglar. Tan sólo tenemos que modificar la acción show de forma que encuentre un blog por su identificador de subdominio en lugar de por su id.

/app/controllers/blogs_controller.rb

def show
  @blog = Blog.find_by_subdomain!(request.subdomain)
end

Si ahora recargamos la página veremos lo artículos de nuestro blog “Personal” .

Si quitamos el subdominio veremos otra vez la página de inicio que teníamos antes.

Aún nos queda un pequeño problema con las rutas. Si visitamos http://www.lvh.me:3000 nuestra aplicación buscará un blog con el subdominio www cuando claramente debería redirigirnos a la portada de los blogs. Podríamos intentar arreglar esto haciendo algo astuto con la expresión regular del archivo de rutas, pero para tener más flexibilidad y control sobre los subodminios lo haremos en código Ruby, porque en Rails 3 podemos escribir una clase que gestione las restricciones de las rutas.

En primer lugar vamos a modificar el archivo de rutas para que utilice una nueva clase llamada Subdomain. Lo haremos utilizando el método constraints y pasándole la clase como argumento.

/config/routes.rb

Bloggit::Application.routes.draw do |map|
  resources :comments
  resources :articles
  resources :blogs
  constraints(Subdomain) do
    match '/' => 'blogs#show'  
  end
  root :to => "blogs#index"
end

A continuación tenemos que crear la clase Subdomain que pondremos en el directorio lib. Esta clase tendrá que tener un método de clase llamado matches? que reciba un objeto de tipo request como parámetro. Este objeto es el mismo objeto al que tenemos acceso en nuestros controladores y vistas y por tanto podemos invocar los mismos métodos que estamos acostumbrados a utilizar. El método tiene que devolver un valor booleano cuyo valor dependa de si la ruta dada casa con la petición. En nuestro caso queremos que el método devuelva true si la petición tiene un subdominio siempre que dicho subdominio no sea www. Nuestra clase, por tanto, tendrá este aspecto:

/lib/subdomain.rb

class Subdomain
  def self.matches?(request)
    request.subdomain.present? && request.subdomain != 'www'
  end
end

Si visitamos http://www.lvh.me:3000 veremos la portada tal y como queríamos.

Para arreglar los enlaces

A continuación vamos a corregir los enlaces a cada blog que aparecen en la portada para que apunten al subdominio correspondiente en lugar de a la acción show de dicho blog (lo que dará un error porque dicha acción ahora espera recibir un subdominio)

En el código de la vista de la acción index tenemos un enlace estándar a cada blog rodeado por etiquetas h2.

/app/views/blogs/index.html.erb

<% title "Blogs" %>

<% for blog in @blogs %>
  <div>
    <h2><%= link_to blog.name, blog %></h2>
    <div class="actions">
      <%= link_to "Edit", edit_blog_path(blog) %> | 
      <%= link_to "Destroy", blog, :confirm => 'Are you sure?', :method => :delete %>
    </div>
<% end %>

Queremos cambiar dicho enlace para que apunte a la URL raíz con el subdominio apropiado. Por desgracia a root_url no le podemos pasar la opción subdomain como sí que podríamos hacer con subdomain_fu. En su lugar tendremos que crear el nombre de host partiendo de cero e incluyendo el subdominio. Esto lo haremos a partir del atributo subdomain del blog y el dominio y puerto de la petición actual.

/app/views/blogs/index.html.erb

<h2><%= link_to blog.name, root_url(:host => blog.subdomain + '.' + request.domain + request.port_string) %></h2>

Si ahora recargamos la portada veremos que los enlaces de los blogs ahora muestran correctamente el subdominio.

Limpieza del código que cambia el subdominio

Todo funciona correctamente ahora pero el código que crea el enlace al otro subdominio podría ser un poco más claro, lo que nos interesará especialmente si vamos a tener que usarlo mucho. Lo haremos moviéndolo a su propio helper, que llamaremos with_subdomain y que recibirá un argumento subdomain. Primero cambiaremos el código en la vista para que invoque al método que estamos a punto de escribir.

/app/views/blogs/index.html.erb

<h2><%= link_to blog.name, root_url(:host => with_subdomain(blog.subdomain)) %></h2>

Pondremos el método helper en su propio módulo, en fichero llamado url_helper.rb.

/app/helpers/url_helper.rb

module UrlHelper
  def with_subdomain(subdomain)
    subdomain = (subdomain || "")
    subdomain += "." unless subdomain.empty?
    [subdomain, request.domain, request.port_string].join
  end
end

El código del módulo primero asigna subdomain a una cadena vacía si el valor pasado es nil y le añade un punto en caso contrario. Finalmente une esta variable subdomain, con el dominio y el puerto de la petición actual y devuelve dicho valor.

Vamos a añadir este módulo a ApplicationController para que todos los controladores de nuestra aplicación puedan utilizarlo.

/app/controllers/application_controller.rb

class ApplicationController < ActionController::Base
  include UrlHelper
  protect_from_forgery
  layout 'application'
end

Aunque hemos limpiado el código de la vista, aún podríamos mejorarlo aún más si pudiésemos añadir la opción :subdomain al método root_url, y esto sólo es posible hacerlo si reescribimos el método url_for. Tan sólo tenemos que añadir el siguiente método a nuestro módulo UrlHelper.

/app/helpers/url_helper.rb

def url_for(options = nil)
  if options.kind_of?(Hash) && options.has_key?(:subdomain)
    options[:host] = with_subdomain(options.delete(:subdomain))
  end
  super
end

Nuestra versión redefinida de url_for comprueba si en el hash de opciones aparece una clave llamada :subdomain y, de ser así, pone la opción :host al valor que devuelva la función with_subdomain para dicho subdominio. Finalmente, llama a super para que se ejecute el código por defecto del método y se genere correctamente el resto de la URL. No nos hace falta pasar por alias_method_chain, bastará con llamar a super.

Ya podemos actualizar el código de nuestra vista para que utilice la opción :subdomain.

/app/views/blogs/index.html.erb

<h2><%= link_to blog.name, root_url(:subdomain => blog.subdomain) %></h2>

Si recargamos la portada y hacemos clic en uno de los enlaces de los blogs, el enlace sigue dirigiendo a la URL correcta, con su subdominio.

Sería conveniente poder tener en cada blog un enlace de vuelta a la página principal, podemos hacerlo llamando a root_url con :subdomain a false.

/app/views/blogs/show.html.erb

<p><%= link_to "All Blogs", root_url(:subdomain => false) %></p>

Con esto tendremos el enlace que nos llevará de vuelta a la portada.

Cómo gestionar diferentes dominios de nivel superior

Una cosa que aún no hemos visto es cómo gestionar nombres de dominio que tengan más de dos partes. Así, si bien nuestro código de subdominios funcionará para dominios .com, no lo hará con dominios que terminen en .co.uk. Para poder trabajar con estos dominios tendremos que cambiar nuestra aplicación y donde quiera que se llame a request.domain o request.subdomain tendremos que especificar el número de puntos que contiene el dominio (sin subdominios). Rails por defecto asume el valor 1, pero tendremos que pasar el valor 2 para dominios como .co.uk.

Tenemos que hacer cambios en dos sitios de nuestra aplicación: en el método UrlHelper y en la clase Subdomain que estamos usando en nuestras rutas.

/app/helpers/url_helper.rb

def with_subdomain(subdomain)
  subdomain = (subdomain || "")
  subdomain += "." unless subdomain.empty?
  [subdomain, request.domain(2), request.port_string].join
end

/lib/subdomains.rb

class Subdomain
  def self.matches?(request)
    request.subdomain(2).present? && request.subdomain(2) != "www"
  end
end

Obviamente no nos interesa que el valor esté grabado a fuego, tendremos que hacerlo dinámico de forma que en desarrollo pueda valer 1 (para dominios como lvh.me) mientras que en producción utilizaríamos el valor 2. Este valor se puede poner en un archivo externo de configuración que sería cargado por el entorno.

Cookies

Hay un aspecto último que nos hemos dejado para el final de este episodio. Si miramos las cookies de nuestro navegador y filtramos por el nombre de dominio que hemos venido usando para nuestra aplicación veremos que se guarda una cookie de sesión diferente para cada subdominio que hemos visitado. No queremos que esto ocurra, porque esto significa que los subdominios no comparten la sesión.

En el episodio 123 se presentó una solución a este problema pero existe una forma mejor de hacerlo en Rails 3. Sólo tenemos que añadir la opción :domain en el fichero /config/initializers/session_store.rb de nuestra aplicación en el método Rails.application.config.session_store dándole el valor :all.

/config/initializers/sesion_store.rb

Rails.application.config.session_store :cookie_store, :key => '_bloggit_session', :domain => :all

De todas formas, esto todavía no funcionará. La opción :domain ha sido añadida posteriormente a Rails 3.0 beta 4, que es la última versión de Rails a fecha de escritura de este artículo. Tendremos que pasar a Edge Rails o bien esperar a la siguiente versión candidata para que tener esta funcionalidad. Una vez que tengamos una versión de Rails que soporte esta opción nuestra aplicación podrá compartir sesiones a lo largo de múltiples subodminos. La opción :all asume que nuestra aplicación tiene sólo un punto en su dominio de nivel superior. De no ser así podemos especificar un nombre de dominio que será utilizado como base para la sesión.

Con esto cerramos este episodio. La gestión de subdominios sin tener que usar plugins adicionales es una gran mejora a Rails que seguramente tendrá muchos usos en nuestras aplicaciones.

PDFKit

Tue, 27 Jul 2010 09:44:00 +0000

Existen varias librerías para generar archivos PDF en Ruby. Una de las más populares es Prawn, que es una excelente manera de generar PDFs desde cero con Ruby y que ya estudiamos en el Episodio 153 [verlo, leero]. Sin embargo hay situaciones en las que nos sería mucho más fácil generar un PDF a partir de un documento HTML ya existente, que es el caso que veremos en este episodio.

La generación de PDFs a partir de HTML no es una idea precisamente nueva pero hasta ahora las soluciones disponibles costaban dinero, pero ha habido mucha actividad en este campo a partir de una solución propuesta por Jared Pace con su nueva librería PDFKit. La gema depende de wkhtmltopdf, una herramienta que utiliza el motor de WebKit para generar documentos PDF, así que para instalar PDFKit tenemos primero que instalar wkhtmltopdf. PDFKit ya viene con wkhtmltopdf así que, dependiendo de nuestro entorno, puede que esto no sea necesario.

La gema de PDFKit se instala de la forma habitual:

$ gem install pdfkit

Tras su instalación PDFKit puede generar un archivo PDF si se le pasa un archivo HTML o la dirección de una página web. La gema también viene con un middleware de Rack que se puede usar para generar PDFs a partir de cualquier página de un sitio simplemente añadiendo .pdf a la URL. Este es el enfoque que usaremos en nuestra aplicación.

Creación de PDFs de facturas

La aplicación que vamos a usar para demostrar el uso de PDFKit es la misma con la que trabajamos en el episodio sobre Prawn. Debajo se muestra la página de pedido de una aplicación sencilla de comercio electrónico. Queremos añadir un enlace a esta página que permita descargar la versión en PDF del pedido, y para eso es para lo que vamos a usar PDFKit.

Lo primero que haremos será añadir una referencia a PDFKit en nuestra aplicación. Dado que estamos con una aplicación Rails 3 podemos modificar el archivo Gemfile:

/Gemfile

gem "pdfkit"

Y después, para asegurarnos de que la gema está instalada:

$ bundle install

A continuación tenemos que añadir el middleware. En una aplicación Rails 3 esto hay que hacerlo en el fichero /config/application.rb (si estuviéramos con una aplicación Rails 2 iría en el fichero de configuración environment.rb). Modificaremos el entorno para que la aplicación utilice el middleware de PDFKit.

/config/application.rb

require File.expand_path('../boot', __FILE__)

require 'rails/all'

# Auto-require default libraries and those for the current Rails environment.
Bundler.require :default, Rails.env

module Store
  class Application < Rails::Application
    config.secret_token = '6f22fa632e18b338b4babfa5fca632f5454fc97317cb52f372fa0f0fdd7f4d5bd95a060ff412c7230627b5c17906c9762c09208624bc1ab97f8d5344d8d4f467'
    config.filter_parameters << :password
    config.middleware.use "PDFKit::Middleware"
  end
end

Podemos ejecutar rake middleware para ver qué middlewares están siendo utilizados por nuestra aplicación, con lo que podemos comprobar si aparece el de PDFKit:

$ rake middleware
(in /Users/eifion/rails/apps_for_asciicasts/ep220/store)
use ActionDispatch::Static
use Rack::Lock
use ActiveSupport::Cache::Strategy::LocalCache
use Rack::Runtime
use Rails::Rack::Logger
use ActionDispatch::ShowExceptions
use ActionDispatch::RemoteIp
use Rack::Sendfile
use ActionDispatch::Callbacks
use ActiveRecord::ConnectionAdapters::ConnectionManagement
use ActiveRecord::QueryCache
use ActionDispatch::Cookies
use ActionDispatch::Session::CookieStore
use ActionDispatch::Flash
use ActionDispatch::ParamsParser
use Rack::MethodOverride
use ActionDispatch::Head
use PDFKit::Middleware
run Store::Application.routes

Como en el listado aparece PDFKit::Middleware podemos continuar. Ya es posible añadir la extensión .pdf a cualquier URL de nuestra aplicación para obtener una versión en PDF de la misma. Si hacemos así para una de las facturas de la aplicación veremos su versión en PDF:

Y eso es todo. Prácticamente sin tener que hacer nada hemos creado una versión PDF del pedido. Podría tener mejor aspecto, pero ya tenemos una base sobre la que trabajar.

Personalizando el aspecto de la factura en PDF

Lo primero que haremos con la factura es quitar el fondo azul de la versión en PDF. Tenemos que ser capaces de distinguir la versión PDF de forma que podamos aplicar diferentes reglas de estilo y esto puede hacerse modificando la llamada al middleware para que PDFKit utilice el tipo de medio impreso.

/config/application.rb

config.middleware.use "PDFKit::Middleware", :print_media_type => true

El fichero de layout de nuestra aplicación tenemos una etiqueta stylesheet_link_tag que incluye la hoja de estilos application.css. Por defecto, esta hoja tiene el tipo de medio screen lo que significa que con el cambio que acabamos de hacer al middleware ninguno de los estilos de esa hoja será aplicado en la versión en PDF. Vamos a modificar la etiqueta stylesheet_link_tag para que se corresponda con el tipo de medio all, con lo o ue los estilos se aplicarán tanto a versión de pantalla (HTML) como a la de impresión (PDF).

/application/views/layouts/application.html.erb

<%= stylesheet_link_tag "application", :media => 'all' %>

Podríamos haber creado una hoja de estilos completamente separada para la hoja de impresión pero en vez de eso vamos a incluir las reglas que aplican para la versión de impresión en la misma hoja de estilos. Al final del archivo CSS podemos añadir una regla de tipo de medio, y las reglas definidas en dicha sección sólo serán aplicables a la vista en PDF. Por tanto para eliminar el fondo azul de nuestra vista de impresión podemos añadir la siguiente regla CSS al final de la hoja de estilos de nuestra aplicación.

/public/stylesheets/application.css

@media print {
	body { background-color: #FFF; }
  #container {
		width: auto;
		margin: 0;
		padding: 0;
		border: none;
	}
}

Cuando recarguemos la vista de página de nuestro pedido veremos que el fondo azul habrá desaparecido.

El PDF que tenemos ahora es muy parecido al que creamos en el episodio sobre Prawn, pero hemos tenido que escribir mucho menos código para conseguir el mismo resultado. Prawn tiene sus ventajas, porque nos da mucho más control sobre la forma en que la se genera el fichero PDF, especialmente en documentos con varias páginas. Con PDFKit si la tabla del pedido ocupase varias páginas tendríamos problemas para controlar la forma en la que se muestran en cada página las cabeceras y pies.

Control de saltos de página

Dicho esto, con PDFKit sí que podemos tener cierto control sobre los saltos de página. Si añadimos unos párrafos de texto al principio del pedido (para que la tabla quede más abajo) veremos que la tabla ahora aparece en dos páginas distintas.

Podemos evitar este problema modificando la hoja de estilos de impresión para que se inserte un salto de página justo antes de la tabla y que siempre aparezca en la parte de arriba de la página, con la propiedad page-break-before.

/public/stylesheets/application.css

@media print {
	body { background-color: #FFF; }
  #container {
		width: auto;
		margin: 0;
		padding: 0;
		border: none;
	}
	
	#line_items {
		page-break-before: always;
	}
}

Si recargamos el documento PDF de nuevo, la tabla volverá a aparecer en su propia página.

A pesar de tener este control básico de los saltos de página con PDFKit, si nuestros documentos son más complicados deberemos quedarnos con Prawn.

Hay todavía un último cambio que queremos hacer antes de acabar este episodio. Se trata de añadir un enlace de la versión PDF en la página HTML de la factura. Primero añadiremos un enlace al archivo PDF al final de la página.

/app/views/orders/show.html.erb

<p><%= link_to "Download Invoice (PDF)", order_path(@order, :format => "pdf") %></p>

Con esto veremos un enlace en el pedido en HTML a la versión PDF, pero este enlace también aparecerá en la versión PDF (cosa que no queremos) Podemos ocultar este enlace en el PDF dando un identificador al elemento de párrafo que contiene el enlace:

/app/views/orders/show.html.erb

<p id="pdf_link"><%= link_to "Download Invoice (PDF)", order_path(@order, :format => "pdf") %></p>

Y modificando después la hoja de estilos para que oculte dicho enlace en la versión impresa.

/public/stylesheets/application.css

@media print {
	body { background-color: #FFF; }
  #container {
		width: auto;
		margin: 0;
		padding: 0;
		border: none;
	}
	
	#line_items {
		page-break-before: always;
	}
	
	#pdf_link {
		display: none;
	}
}

Ahora tendremos un enlace al PDF en la versión HTML de la factura, pero dicho no enlace no aparecerá en el PDF.

Una alternativa

Antes de cerrar este episodio mencionaremos una alternativa a PDFKit, Wicked PDF. Este plugin tiene un enfoque distinto del de PDFKit, aunque también usa wkhtmltopdf. Wicked PDF no es un middlware sino que es un renderer de Rails. Wicked PDF nos da más control sobre qué acciones pueden mostrarse como PDFs, por lo que es una opción que merece la pena tener en cuenta.

Y eso es todo por este episodio. Ya hemos cubierto dos maneras muy distintas de generar documentos PDF en nuestras aplicaciones Rails, cada una de ellas con sus ventajas y desventajas. Si bien PDFKit nos da la facilidad de generar PDFs a partir del HTML, con Prawn tendremos más control sobre los archivos generales. Hay que considerar bien ambos enfoques.

Active Model

Fri, 23 Jul 2010 21:27:33 +0000

El episodio 193 [verlo, leerlo] trataba de los modelos sin tablas. En ese episodio creamos un modelo que utilizaba algunas de las características de ActiveRecord pero que no tenía una base de datos por detrás. Podría decirse que esta técnica era un hack, dado que no era algo para lo que ActiveRecord estuviera diseñado pero ahora en Rails 3.0 tenemos una nueva funcionalidad llamada ActiveModel con la que se pueden hacer fácilmente este tipo de cosas.

Antes de entrar en detalle con ActiveModel vamos a describir la sección de la aplicación que vamos a modificar:

En la captura de pantalla anterior vemos un formulario de contacto que ha sido creado utilizando el andamiaje de Rails. La aplicación tiene un modelo llamado Message y que ActiveRecord se encarga de guardar en la base de datos. Vamos a cambiar este comportamiento para que tan sólo envíe el correo electrónico sin almacenar nada en ninguna tabla.

Por supuesto, siempre que pensemos acometer este tipo de soluciones es buena idea plantearnos nuestros requerimientos y asegurarnos de que realmente no nos interesa almacenar estos datos en la base de datos porque por lo general sí que nos interesa hacerlo: en primer lugar la base de datos puede actuar de copia de respaldo y hace que sea más fácil pasar el envío de mensajes a una cola de tareas en un proceso background. Como no vamos a necesitar nada de esto en nuestro ejemplo, vamos a seguir adelante y haremos que este sea un modelo sin tabla.

El código de la clase Message tiene el siguiente aspecto:

/app/models/message.rb

class Message < ActiveRecord::Base
 validates_presence_of :name
 validates_format_of :email, :with => /^[-a-z0-9_+\.]+\@([-a-z0-9]+\.)+[a-z0-9]{2,4}$/i
 validates_length_of :content, :maximum => 500
end

Como es de esperar de una clase de modelo, Message hereda de ActiveRecord::Base, herencia que tendremos que romper porque no queremos que este modelo esté respaldado por una base de datos. En cuanto lo hagamos el formulario dejará de funcionar porque es ActiveRecord quien está haciendo las validaciones. Por suerte podemos recuperar esta funcionalidad utilizando ActiveModel.

Si echamos un vistazo al código fuente de Rails 3 veremos que hay un par de directorios, activerecord y activemodel. El equipo de Rails ha extraído de ActiveRecord todo lo que no era específico del soporte de base de datos y lo ha puesto en ActiveModel, cuyas funcionalidades están muy bien probadas y es ideal para ser usado fuera de ActiveRecord (si bien ActiveRecord se apoya en ActiveModel para todo lo que no tiene que ver con la base de datos).

Si echamos un vistazo al directorio que contiene el código de ActiveModel podemos ver toda la funcionalidad que suministra.

Tal y como puede verse del listado anterior ActiveModel incluye entre otras cosas el código para gestionar callbacks, serialización y validación. Esto último es justamente lo que estábamos buscando.

En el código para las validaciones aparece el siguiente comentario al principio, de donde podemos ver que es muy fácil añadir validaciones a cualquier modelo. Lo único que tenemos que hacer es incluir el módulo Validations y proporcionar métodos de acceso para los atributos sobre los que vamos a aplicar validadores.

  # == Validaciones de ActiveModel
  #   
  # Suministra un marco completo de validación a tus objetos
  # 
  # Una implementación mínima sería
  # 
  #   class Person
  #     include ActiveModel::Validations
  # 
  #     attr_accessor :first_name, :last_name
  #
  #     validates_each :first_name, :last_name do |record, attr, value|
  #       record.errors.add attr, 'starts with z.' if value.to_s[0] == ?z
  #     end
  #   end
  #

Una vez que sabemos esto podemos aplicarlo a nuestro modelo Message.

/app/models/message.rb

class Message
  include ActiveModel::Validations
  
  attr_accessor :name, :email, :content
 
  validates_presence_of :name
  validates_format_of :email, :with => /^[-a-z0-9_+\.]+\@([-a-z0-9]+\.)+[a-z0-9]{2,4}$/i
  validates_length_of :content, :maximum => 500
end

Pero con esto no es suficiente para que nuestro modelo se comporte como espera el controlador, aún tenemos dos problemas en el método create. Primero, la llamada a Message.new no funciona porque el modelo Message ya no tiene un inicializador que reciba el hash de atributos como argumento. Y en segundo lugar el método save no funcionará porque no tenemos un servidor de base de datos en el que almacenar el nuevo mensaje.

/apps/controllers/messages_controller.rb

class MessagesController < ApplicationController
  def new
    @message = Message.new
  end

  def create
    @message = Message.new(params[:message])
    if @message.save
      # TODO send message here
      flash[:notice] = "Message sent! Thank you for contacting us."
      redirect_to root_url
    else
      render :action => 'new'
    end
  end
end

Vamos a empezar corrigiendo el segundo de estos problemas. Si bien no podemos guardar el mensaje sí que podemos comprobar si es válido, así que vamos a cambiar @message.save con @message.valid?.

/app/controllers/messages_controllers.rb

def create
  @message = Message.new(params[:message])
  if @message.valid?
    # TODO send message here
    flash[:notice] = "Message sent! Thank you for contacting us."
    redirect_to root_url
  else
    render :action => 'new'
  end
end

Y para arreglar el primer problema, vamos a escribir un método initialize en el modelo Message que recibirá un hash como parámetro. Este método recorrerá cada elemento de este hash y asignará su valor al atributo correspondiente, utilizando el método send.

/app/models/message.rb

class Message
  include ActiveModel::Validations
  
  attr_accessor :name, :email, :content
 
  validates_presence_of :name
  validates_format_of :email, :with => /^[-a-z0-9_+\.]+\@([-a-z0-9]+\.)+[a-z0-9]{2,4}$/i
  validates_length_of :content, :maximum => 500
  
  def initialize(attributes = {})
    attributes.each do |name, value|
      send("#{name}=", value)
    end
  end
end

Si recargamos el formulario veremos que aún nos falta un poco más para terminar.

Esta vez el error viene provocado porque al modelo Message le falta el método to_key. El error ha sido devuelto por el método form_for, así que esto parece indicar que Rails espera que nuestro modelo tenga cierta funcionalidad que aún no soporta. Añadámosla ahora.

En vez de tener que adivinar todo lo que Rails espera que nuestro modelo tenga, podemos usar una herramienta de chequeo incluida con ActiveModel que nos permite comprobar si nuestro modelo cumple con todo lo que Rails espera de él. Si incluimos el módulo ActiveModel::Lint::Tests en un test del modelo, comprobará que éste tiene toda la funcionalidad necesaria.

El código fuente del módulo Lint::Tests muestra los métodos a los que el método tiene que responder para que todo funcione como debería (incluyendo to_key). Por tanto podemos hacer que nuestro modelo funcione incluyendo un par de módulos de ActiveModel. El primero de ellos es Conversion, y es el que proporciona el método to_key y algunos más. El otro módulo se llama Naming pero en este caso en lugar de incluirlo en nuestra clase tendremos que usar extend porque incluye algunos métodos de clase.

Además de incluir el módulo Conversion tenemos que definir el método persisted? en nuestro modelo, que tiene que devolver false dado que no estamos guardando nuestro modelo en la base datos. Con estos cambios, este es el aspecto que tiene nuestro modelo Message:

/app/models/message.rb

class Message
  include ActiveModel::Validations
  include ActiveModel::Conversion
  extend ActiveModel::Naming
  
  attr_accessor :name, :email, :content
 
  validates_presence_of :name
  validates_format_of :email, :with => /^[-a-z0-9_+\.]+\@([-a-z0-9]+\.)+[a-z0-9]{2,4}$/i
  validates_length_of :content, :maximum => 500
  
  def initialize(attributes = {})
    attributes.each do |name, value|
      send("#{name}=", value)
    end
  end
  
  def persisted?
    false
  end
end

Si recargamos el formulario volverá a funcionar de nuevo, lo que significa que el modelo Message ya satisface todos lo que Rails 3 requiere de un modelo. Si intentamos enviar el formulario veremos que los validadores ya están funcionando:

En este episodio hemos visto sólo un poco de todo lo que ActiveModel nos ofrece, pero debería ser suficiente para despertar nuestro interés y darnos una razón para examinar su documentación y aprender todo lo que puede hacer. El código está bien documentado y estructurado, así que si vemos algo que nos parece interesante seguro que encontraremos suficiente información en los comentarios del archivo como para poder ponernos manos a la obra.

Cómo escribir nuestros propios generadores en Rails 3

Fri, 23 Jul 2010 21:11:38 +0000

En el episodio 216 [verlo, leerlo] vimos que en Rails 3 los generadores son mucho más modulares y personalizables que en Rails 2. Pero hay veces, sin embargo, que nos interesaría escribir un generador desde cero porque los que vienen con Rails no se ajustan a nuestras necesidades. Ya vimos cómo escribir nuestros propios generadores en el episodio 58, pero han sido tantos los cambios que vamos a darles otro repaso, viendo cómo escribir el mismo generador de ese episodio en Rails 3.

Empecemos

Como la forma más sencilla de escribir un generador es desde dentro de una aplicación Rails 3, vamos a crear una. Se acaba de liberar la beta 4 de Rails 3.0, y la sintaxis para generar una nueva aplicación ha cambiado, así que para crear la aplicación de tareas sobre la que vamos a desarrollar nuestro generador en lugar de ejecutar

$ rails todo

tenemos que ejecutar

$ rails new todo

Una vez que hemos creado nuestra nueva aplicación empezaremos el desarrollo de nuestro generador usando uno de los generadores incluidos. El comando rails g generator creará los ficheros básicos que hacen falta. Podemos ver qué parámetros acepta este comando:

$ rails g generator --help

Este generador es bastante sencillo, y sólo hace falta pasarle el nombre del nuevo generador que queremos crear. Como queremos que genere un fichero de layout de la aplicación, lo bautizaremos como layout.

$ rails g generator layout
      create  lib/generators/layout
      create  lib/generators/layout/layout_generator.rb
      create  lib/generators/layout/USAGE
      create  lib/generators/layout/templates

El generador creará una serie de archivos dentro del directorio /lib lo que quiere decir que nuestro generador sólo podrá ser usado en esta aplicación. Para poder usarlo en cualquier otra aplicación tendremos que hacer algunas cosas más que veremos más adelante.

El fichero del generador así generado (valga la redundancia) es bastante sencillo y tan sólo contiene una clase. En dicha clase hay una línea de código que le dice al generador que mire en el directorio de plantillas en busca de ficheros adicionales.

/lib/generators/layout/layout_generator.rb

class LayoutGenerator < Rails::Generators::NamedBase
  source_root File.expand_path('../templates', __FILE__)
end

El generador generator también crea un archivo llamado USAGE donde podemos definir la documentación de nuestro generador. Dicha documentación se mostrará cuando se ejecute la opción --help de nuestro generador.

La clase creada por el generador hereda de Rails::Generators::NamedBase. Esto significa que hará falta proporcionar un nombre cuando se ejecute el generador de la misma manera que tuvimos que poner un nombre cuando ejecutamos generator. Podemos ver esto ejecutando nuestro nuevo generador con la opción --help.

$ rails g layout --help
Usage:
  rails generate layout NAME [options]

Runtime options:
  -f, [--force]    # Overwrite files that already exist
  -p, [--pretend]  # Run but do not make any changes
  -s, [--skip]     # Skip files that already exist
  -q, [--quiet]    # Supress status output

Description:
    Explain the generator

Example:
    rails generate layout Thing

    This will create:
        what/will/it/create

Nótese que los contenidos del fichero USAGE se muestran al final.

Queremos que la opción NAME sea opcional y que por defecto tenga el valor de application. Podemos hacerlo haciendo que la clase herede de Rails::Generators::Base, en lugar de NamedBase. Esto hará que todos los argumentos sean opcionales y por tanto tendremos más flexibilidad a la hora de personalizar nuestro generador.

Podemos definir qué argumentos recibe el generador utilizando el método argument. Si definimos nuestros propios argumentos en lugar de usar la opción NAME podremos definir un valor por defecto para cada argumento. Añadiremos un argumento layout_name cuyo valor por defecto será application.

/lib/generators/layout/layout_generator.rb

class LayoutGenerator < Rails::Generators::Base
  source_root File.expand_path('../templates', __FILE__)
  argument :layout_name, :type => :string, :default => "application"
end

Si ejecutamos una vez más el comando de generador con la opción --help veremos que ahora aparece nuestro nuevo argumento. Además lo hace entre corchetes, y esto significa que es un parámetro opcional.

$ rails g layout --help
Usage:
  rails generate layout [LAYOUT_NAME] [options]

En Rails 3 los generadores se basan en la librería Thor, que es similar a rake. Muchos de los metodos accesibles desde nuestra clase del generador son definidos en la propia librería Thor así que podemos echar un vistazo a la documentación y el código fuente de Thor si queremos profundizar más acerca de dichos métodos.

Creando los ficheros que utilizará el generador

Recordemos que queríamos que nuestro generador crease dos archivos: un archivo de layout de la apliccaion y una hoja de estilos. Para esto crearemos dos archivos en el directorio templates del generador y haremos que cuando el generador se ejecute los copie a los directorios correspondientes en nuestra aplicación.

¿Y cómo definimos el comportamiento del generador? La forma de hacerlo es, por así decirlo, bastante inusual. Cualquier método público que sea definido en la clase del generador será invocado cuando se ejecute el generador. Por tanto, podremos definir un método llamado generate_layout que será ejecutado automáticamente. Se trata de un concepto un poco extraño pero resulta ser una buena forma de organizar el código del generador.

Lo primero que hará nuestro generador será copiar una hoja de estilos desde el directorio templates al directorio /public/stylesheets de nuestra aplicación y para esto podemos usar el método copy_file.

/lib/generators/layout/layout_generator.rb

class LayoutGenerator < Rails::Generators::Base
  source_root File.expand_path('../templates', __FILE__)
  argument :layout_name, :type => :string, :default => "application"
  
  def generate_layout
    copy_file "stylesheet.css", "public/stylesheets/#{layout_name.underscore}.css"
  end
  
end

El método copy_file recibe dos argumentos. El primero es el nombre del fichero del directorio templates que deberá copiarse y el segundo es el path de destino. Obsérvese que el nombre del fichero de destino se basa en el argumento layout_name que se pasó al generador. El método argument crea un método layout_name qu epodemos usar, pero dado que el nombre recibido podría contener mayúsculas y minúsculas tendremos que invocar el método underscore para asegurarnos que está en un formato apto para nombres de fichero.

Por último, tenemos que crear el fichero stylesheet.css en el directorio templates y pegar la hoja de estilos por defecto que queremos que tengan nuestras aplicaciones.

Si ahora ejecutamos nuestro generador sin argumentos debería crear un archivo application.css.

$ rails g layout
      create  public/stylesheets/application.css

A continuación tenemos que hacer lo mismo con el archivo de layout. Vamos a crear un método auxiliar llamado file_name porque nos va a hacer falta obtener el nombre de layout con guiones bajos en varios sitios. Como mencionábamos antes, cualquier método público definidio en la clase del generador será ejecutado así que tenemos que asegurarnos de que este método sea privado.

Lo siguiente que tenemos que hacer en nuestro generador es crear el propio fichero de layout. Podríamos otra vez ejecutar copy_file pero esto efectuaría una simple copia del fichero de la plantilla, y queremos poder pasar este archivo por ERb de forma que sea modificado cuando se ejecute el generador.

En su lugar podemos usar el método template, que recibe argumentos similares a copy_file, pero ejecutará cualquier código erb que exista en la plantilla antes de copiarlo al directorio de destino.

/lib/generators/layout/layout_generator.rb

class LayoutGenerator < Rails::Generators::Base
  source_root File.expand_path('../templates', __FILE__)
  argument :layout_name, :type => :string, :default => "application"
  
  def generate_layout
    copy_file "stylesheet.css", "public/stylesheets/#{file_name}.css"
    template "layout.html.erb", "app/views/layouts/#{file_name}.html.erb"
  end
  
  private
  def file_name
    layout_name.underscore
  end
  
end

A continuación crearemos la plantilla propiamente dicha

/lib/generators/layout/templates/layout.html.erb

<!DOCTYPE html>
<html>
  <head>
    <title>Untitled</title>
    <%%= stylesheet_link_tag "<%= file_name %>" %>
    <%%= javascript_include_tag :defaults %>
    <%%= csrf_meta_tag %>
    <%%= yield(:head) %>
  </head>
  <body>
    <div id="container">
      <%% flash.each do |name, msg| %>
        <%%= content_tag :div, msg, :id => "flash_#{name}" %>
      <%% end %>
      <%%= yield %>
    </div>
  </body>
</html>

Lo primero que notamos es que, como estamos usando el método template, se ejecutarán todas las etiquetas erb del código. Si queremos que el fichero generado contenga erb tendremos que escapar el signo de porcentaje al comienzo de la etiqueta erb tal y como hemos hecho en el código anterior.

Por tanto, para incluir contenido dinámico en la plantilla podemos usar código erb normal. Podemos acceder métodos del fichero del generador (aunque sean privados) y podemos llamar a file_name para poner el nombre correcto del archivo de la hoja de estilos en la llamada a stylesheet_link_tag.

Podemos ejecutar una vez más el generador para comprobar que todo funciona correctamente, esta vez pasando un archivo de layout.

$ rails g layout admin
      create  public/stylesheets/admin.css
      create  app/views/layouts/admin.html.erb

Esta vez el generador ha creado dos archivos, cada uno de ellos con un nombre basado en el parámetro recibido, así que todo parece estar funcionando. Si miramos el fichero generado veremos que se llamó al método file_name cuando se generó el archivo por lo que le método stylesheet_link_tag tiene el argumento correto. Las otras etiquetas erb que estaban escapadas sí que aparecen tal cual en el fichero generado.

/app/views/layouts/admin.html.erb

<head>
  <title>Untitled</title>
  <%= stylesheet_link_tag "admin" %>
  <%= javascript_include_tag :defaults %>
  <%= csrf_meta_tag %>
  <%= yield(:head) %>
</head>

Opciones opcionales

Hay una última funcionalidad que queremos añadir al generador: la posibilidad de pasarle una opción que haga que no se genere el fichero con la hoja de estilos. Podemos hacerlo utilizando el método class_option.

/lib/generators/layout/layout_generator.rb

class LayoutGenerator < Rails::Generators::Base
  source_root File.expand_path('../templates', __FILE__)
  argument :layout_name, :type => :string, :default => "application"
  class_option :stylesheet, :type => :boolean, :default => true, :description => "Include stylesheet file"
  
  def generate_layout
    copy_file "stylesheet.css", "public/stylesheets/#{file_name}.css" if options.stylesheet?
    template "layout.html.erb", "app/views/layouts/#{file_name}.html.erb"
  end
  
  private
  def file_name
    layout_name.underscore
  end
  
end

Hemos llamado a nuestra opción stylesheet, de tipo boolean y valor por defecto true. También le hemos dado una descripción. En la línea copy_file ahora podemos añadir una sentencia if para que la hoja de estilos se copie sólo si dicha opción está a true. Igualmente, en el fichero de plantilla para el layout sólo queremos que aparezca la línea stylesheet_link_tag si dicha opción está también a true.

/lib/generators/layout/templates/layout.html.erb

<!DOCTYPE html>
<html>
  <head>
    <title>Untitled</title>
    <%- if options.stylesheet? -%>
    <%%= stylesheet_link_tag "<%= file_name %>" %>
    <%- end -%>
    <%%= javascript_include_tag :defaults %>
    <%%= csrf_meta_tag %>
    <%%= yield(:head) %>
  </head>
  <body>
    <div id="container">
      <%% flash.each do |name, msg| %>
        <%%= content_tag :div, msg, :id => "flash_#{name}" %>
      <%% end %>
      <%%= yield %>
    </div>
  </body>
</html>

Si vemos la documentación de ayuda del generador una vez más, veremos que ahora aparece la opción stylesheet.

$ rails g layout --help
Usage:
  rails generate layout [LAYOUT_NAME] [options]

Options:
  [--stylesheet]  # Indicates when to generate stylesheet
                  # Default: true

Ahora podemos generar un layout sin una hoja de estilos utilizando la opción --skip-stylesheet (o --no-stylesheet). En tal caso sólo se generará el archivo de layout.

$ rails g layout foo --skip-stylesheet
      create  app/views/layouts/foo.html.erb

Y con esto terminamos este episodio dedicado a la escritura de generadores en Rails 3. Siempre que en nuestras aplicaciones acabemos generando el mismo código (o similar) podemos utilizar un generador. Para compartir con otros nuestros generadores tan sólo tenemos que crear un plugin o gema y ponerlo en un directorio lib/generators. Cualquiera que incluya dicha gema o plugin tendrá disponible ese generador.

Fomularios con múltiples pasos

Sun, 20 Jun 2010 19:39:33 +0000

Un formulario multipaso, también conocido como wizard o asistente, es un formulario que debido a su tamaño ha sido dividido en una serie de páginas o pantallas por las cuales los usuarios deben navegar hasta completarlo. Este enfoque tiene sus detractores: hay quien prefiere mostrar el formulario completo o quienes prefieren dividir dicho formulario en diferentes recursos y modelos. Pero hay casos en los que son la mejor solución, por ejemplo un formulario de declaración de impuestos que necesita que el usuario introduzca muchos datos y donde el camino de pasos a seguir no es lineal sino que depende de los datos introducidos.

Un formulario multipaso debe recordar los datos introducidos de un paso a otro de forma que si el usuario se mueve adelante y atrás a lo largo de sus páginas no debería perder la información que ha introducido. Si tan sólo queremos separar un formulario largo para simplificar la interfaz de usuario podríamos usar una combinación de JavaScript y CSS para mostrar y ocultar las diferentes partes del formulario según se pulsen los botones “anterior” y “siguiente”. En el sitio de desarrolladores de Apple se puede encontrar un ejemplo de esto . Si nos hace falta algo más dinámico y orientado al servidor no nos quedará más remedio que pasar por Rails. En este episodio veremos cómo se hace.

Un formulario de pedido multipaso

Como demostración de formulario multipaso vamos a añadir un proceso de compra a una aplicación de tienda. Los usuarios rellenarán primero los datos de envío, luego la dirección de facturación y por último, en el tercer paso, verán un resumen del pedido para su confirmación.

Como no tenemos todavía un modelo para el pedido ni su controlador usaremos uno de los nifty generators de Ryan Bates para crear un andamiaje para el formulario del pedido. Nótese que esta aplicación está escrita con Rails 2, por lo que usaremos script/generate. Para los propósitos de nuestro ejemplo, el pedido tendrá dos datos (en el mundo real un modelo para un pedido tendría muchos más atributos). También crearemos las acciones index, show y new de este controlador.

$ script/generate nifty_scaffold order shipping_name:string billing_name:string index show new

A continuación migraremos la base de datos para crear la nueva tabla.

$ rake db:migrate

El formulario de pedido que se generará tendrá todos los campos amontonados en una sóla página, por lo que lo primero que tenemos que hacer es separarlo en múltiples pasos.

Empezaremos moviendo cada uno de los tres elementos de párrafo y sus campos de formulario en sus propios parciales.

/app/views/orders/new.html.erb

<% title "New Order" %>

<% form_for @order do |f| %>
  <%= f.error_messages %>
  <p>
    <%= f.label :shipping_name %><br />
    <%= f.text_field :shipping_name %>
  </p>
  <p>
    <%= f.label :billing_name %><br />
    <%= f.text_field :billing_name %>
  </p>
  <p><%= f.submit "Submit" %></p>
<% end %>

<p><%= link_to "Back to List", orders_path %></p>

Antes de hacerlo tendremos que añadir una cabecera a cada sección y modificar la sección final para que muestre un resumen del pedido.

/app/views/orders/new.html.erb

<% title "New Order" %>

<% form_for @order do |f| %>
  <%= f.error_messages %>
  <h2>Shipping Information</h2>
  <p>
    <%= f.label :shipping_name %><br />
    <%= f.text_field :shipping_name %>
  </p>
  <h2>Billing Information</h2>
  <p>
    <%= f.label :billing_name %><br />
    <%= f.text_field :billing_name %>
  </p>
  <h2>Confirm Information</h2>
  <p>
    <strong>Shipping Name:</strong>
    <%= h @order.shipping_name %>
  </p>
  <p>
    <strong>Billing Name:</strong>
    <%= h @order.billing_name %>
  </p>
  <p><%= f.submit "Submit" %></p>
<% end %>

<p><%= link_to "Back to List", orders_path %></p>

Con esto podemos empezar a mover cada seccion a su propio parcial. Crearemos tres nuevos parciales llamados shipping_step, billing_step y confirmation_step, copiando lo que haga falta del formulario. Después de esto nuestro formulario de nuevo pedido tendrá este aspecto:

/app/views/orders/new.html.erb

<% title "New Order" %>

<% form_for @order do |f| %>
  <%= f.error_messages %>
  <%= render 'shipping_step', :f => f %>
  <%= render 'billing_step', :f => f %>
  <%= render 'confirmation_step', :f => f %>
  <p><%= f.submit "Submit" %></p>
<% end %>

<p><%= link_to "Back to List", orders_path %></p>

Y los tres parciales serán así:

/app/views/orders/_billing_step.html.erb

<h2>Billing Information</h2>
<p>
  <%= f.label :billing_name %><br />
  <%= f.text_field :billing_name %>
</p>

/app/views/orders/_shipping_step.html.erb

<h2>Shipping Information</h2>
<p>
  <%= f.label :shipping_name %><br />
  <%= f.text_field :shipping_name %>
</p>

/app/views/orders/confirmation_step.html.erb

<h2>Confirm Information</h2>
<p>
  <strong>Shipping Name:</strong>
  <%= h @order.shipping_name %>
</p>
<p>
  <strong>Billing Name:</strong>
  <%= h @order.billing_name %>
</p>

También tendremos qie modificar el modelo Order para que sepa acerca de cada uno de los pasos y pueda identificar cuál es el paso actual. Una posibilidad sería utilizar un plugin de máquina de estados, pero dado que este ejemplo es muy sencillo podemos escribir el código desde cero.

El modelo Order tendrá que saber cuáles son los pasos y el orden en que deberían aparecer, para eso escribiremos un méotod steps que devolverá la lista de pasos. Esta lista no será más que un array pero en el caso de formularios más complejos podríamos hacer que este método fuese más dinámico y controlase casos en los que la lista de pasos cambiase dependiendo de algún dato.

Para obtener y cambiar el paso actual de un pedido crearemos un método de escritura llamado current_step y su correspondiente método de acceso que devolverá el paso actual (o el primero si es que hemos empezado). Tras estos cambios, el modelo Order tiene lo siguiente:

/app/models/order.rb

class Order < ActiveRecord::Base
  attr_accessible :shipping_name, :billing_name
  attr_writer :current_step
  
  def current_step
    @current_step || steps.first
  end
  
  def steps
    %w[shipping billing confirmation]
  end
end

Ahora que sabemos en qué paso estamos, podemos utilizar dicha información para cambiar el parcial que se muestra modificando el formulario de nuevo pedido:

/app/views/orders/new.html.erb

<% title "New Order" %>

<% form_for @order do |f| %>
  <%= f.error_messages %>
  <%= render "#{@order.current_step}_step", :f => f %>
  <p><%= f.submit "Submit" %></p>
<% end %>

<p><%= link_to "Back to List", orders_path %></p>

Si ahora recargamos el formulario veremos que se muestra tan sólo el primer paso.

Movimiento por los pasos

Si ahora pulsamos el botón de envío el formulario invocará la acción create, creando un nuevo pedido. No queremos que sea esto lo que ocurra sino que se muestre el siguente paso del formulario, así que tenemos que cambiar el comportamiento del controlador.

Podemos enfocar este problema de distintas maneras. Por ejemplo podríamos crear una acción separada para cada uno de los pasos y utilizar create para el paso inicial y las acciones edit y update para los otros pasos, lo que significaría que tendríamos en la base de datos un modelo a medio completar o podríamos usar solo las acciones new y create, guardando los datos de entrada del usuario en la sesión. Esta técnica no está libre de problemas, los veremos (y sus alternativas) poco a poco.

La solución más sencilla parasaría por modificar la acción create. Lo primero que haremos será cambiarlo de forma que no guarde el pedido sino que en su lugar muestre el primer paso del formulario.

/app/controllers/orders_controller.rb

def create
  @order = Order.new(params[:order])
  @order.next_step
  render 'new'
end

En el controlador, invocaremos el método next_step sobre Order:

/app/models/order.rb

def next_step
  self.current_step = steps[steps.index(current_step)+1]
end

Cuando ahora pulsemos el botón de envío iremos del primer al segundo paso pero si volvemos a pulsar en el botón permaneceremos en el segundo paso, porque no estamos guardando el paso en el que estamos cuando se envía el formulario. En la acción create tenemos que establecer el paso actual en el modelo Order y luego guardar ese valor. Esto lo haremos recuperando el paso actual de la sesión, pasando al siguiente y guardando el valor de nuevo en la sesión.

/app/controllers/orders_controller.rb

def create
  @order = Order.new(params[:order])
  @order.current_step = session[:order_step]
  @order.next_step
  session[:order_step] = @order.current_step
  render 'new'
end

Si ahora volvemos al formulario veremos que recorre las página como debería y vuelve al primer paso cuando se pulsa el botón en el último paso, lo que no es precisamente lo que queremos pero ya lo corregiremos más adelante.

Antes de eso vamos a implementar la forma de volver al paso anterior. Ahora mismo podemos movernos hacia adelante pero no hacia atrás, para hacer cambios en los campos que ya hemos completado. Vamos a añadirle otro botón al formulario para poder hacerlo.

/app/views/orders/new.html.erb

<% title "New Order" %>

<% form_for @order do |f| %>
  <%= f.error_messages %>
  <%= render "#{@order.current_step}_step", :f => f %>
  <p><%= f.submit "Continue" %></p>
  <p><%= f.submit "Back", :name => "previous_button" %></p>
<% end %>

<p><%= link_to "Back to List", orders_path %></p>

Nótese que al botón para volver atrás le hemos dato un atributo name para poder determinar qué botón se ha pulsado cuando se envíe el formulario. Ya podemos modificar el controlador para que se comporte adecuadamente según el botón que se haya pulsado.

/app/controllers/orders_controller.rb

def create
  @order = Order.new(params[:order])
  @order.current_step = session[:order_step]
  if params[:back_button]
    @order.previous_step
  else
    @order.next_step
  end
  session[:order_step] = @order.current_step
  render 'new'
end

Para que esto funcione necesitamos un método previous_step en el modelo Order que será muy parecido al método next_step que escribimos antes.

/app/models/order.rb

def previous_step
  self.current_step = steps[steps.index(current_step)-1]
end

Con estos botones ya podemos movernos a lo largo de todos los pasos en ambas direcciones.

Como no tiene sentido tener un botón para volver atrás en la primera pantalla tendremos que ocultarlo si la orden está en el primer paso.

/app/views/orders/new.html.erb

<% title "New Order" %>

<% form_for @order do |f| %>
  <%= f.error_messages %>
  <%= render "#{@order.current_step}_step", :f => f %>
  <p><%= f.submit "Continue" %></p>
  <p><%= f.submit "Back", :name => "previous_button" unless @order.first_step? %></p>
<% end %>

<p><%= link_to "Back to List", orders_path %></p>

Para esto tenemos que añadirle al modelo Order el método first_step?.

/app/models/order.rb

def first_step?
  current_step == steps.first
end

Si ahora recargamos el formulario veremos que en el primer paso ya no aparece el botón para volver atrás.

Cómo hacer que los campos recuerden sus valores

Ya podemos movernos por los pasos de nuestro formulario pero si introducimos un valor en uno de los campos y abandonamos dicho paso el valor no será recuperado si posteriormente regresamos al paso. Nuevamente, podemos resolver este problema utilizando la sesión. Si bien no es recomendable guardar objetos complejos en variables de sesión, sí que podemos hacerlo con objetos sencillos como hashes y listas.

El primer paso es crear una nueva variable de sesión en la acción new llamada order_params y darle un valor vacío a no ser que ya exista.

/app/controllers/orders_controller.rb

def new
  session[:order_params] ||= {}
  @order = Order.new
end

En la acción create mezclamos los valores de los parámetros del pedido con los valores que tiene la variable de sesión. Nótese que estamos efectuando una copia en profundidad (deep merge) por si hay valores anidados en los parámetros, y además sólo lo haremos si existen dichos parámetros A partir de este hash combinado ya podemos crear nuestro objeto Order.

/app/controllers/orders_controller.rb

def create
  session[:order_params].deep_merge!(params[:order]) if params[:order]
  @order = Order.new(session[:order_params])
  @order.current_step = session[:order_step]
  if params[:back_button]
    @order.previous_step
  else
    @order.next_step
  end
  session[:order_step] = @order.current_step
  render 'new'
end

Si ahora rellenamos el formulario veremos los valores que introducimos en el paso final, lo que muestra que se han guardado.

Todavía nos queda un pequeño problema. Si cambiamos de paso mientras el formulario está a medio rellenar luego volvemos la información que habíamos introducido se perderá. Esto se puede resolver copiando a la acción new las dos líneas de la acción create que recuperan la información del pedido y el paso actual desde las variables de sesión.

/app/controllers/orders_controller.rb

def new
  session[:order_params] ||= {}
  @order = Order.new(session[:order_params])
  @order.current_step = session[:order_step]
end

Ya podemos volver al formulario, y veremos que los datos que vayamos introduciendo seguirán estando ahí. Y no sólo eso, además iremos al último paso en el que estábamos.

Almacenamiento del Pedido

Por último haremos que el formulario sea totalmente funcional haciendo que guarde el pedido cuando se finalice el último paso. Para ello vamos a modificar el controlador de forma que guarde el pedido sólo si el paso en el que estamos es el último y si el botón pulsado no era el de “paso anterior”. También tendremos que cambiar el comportamiento de la respuesta de forma que si se guarda el pedido la aplicación redirige a la acción show del pedido y muestra un mensaje informativo.

/app/controllers/orders_controller.rb

class OrdersController < ApplicationController
  def index
    @orders = Order.all
  end
  
  def show
    @order = Order.find(params[:id])
  end
  
  def new
    session[:order_params] ||= {}
    @order = Order.new(session[:order_params])
    @order.current_step = session[:order_step]
  end
  
  def create
    session[:order_params].deep_merge!(params[:order]) if params[:order]
    @order = Order.new(session[:order_params])
    @order.current_step = session[:order_step]
    if params[:back_button]
      @order.previous_step
    elsif @order.last_step?
      @order.save
    else
      @order.next_step
    end
    session[:order_step] = @order.current_step
    
    if @order.new_record?
      render 'new'
    else
      flash[:notice] = "Order saved."
      redirect_to @order
    end
  end
end

Para que esto funcione tendremos que añadir el método last_step al modelo Order.

/app/models/order.rb

def last_step?
  current_step == steps.last
end

Cuando ahora rellenemos el último paso se guardará el pedido y seremos redirigidos a la página del nuevo pedido.

Pero aún no hemos terminado. Si intentamos crear un nuevo pedido el formulario nos llevará directamente al último paso y veremos los detalles del pedido anterior. Una vez más, tenemos que cambiar el controlador para que la información del pedido que estamos guardando en la sesión se elimine una vez que el pedido haya sido creado correctamente. Lo haremos poniendo a nil las variables de sesión order_step y order_params.

/app/controllers/orders_controller.rb

def create
  session[:order_params].deep_merge!(params[:order]) if params[:order]
  @order = Order.new(session[:order_params])
  @order.current_step = session[:order_step]
  if params[:back_button]
    @order.previous_step
  elsif @order.last_step?
    @order.save
  else
    @order.next_step
  end
  session[:order_step] = @order.current_step
    
  if @order.new_record?
    render 'new'
  else
    session[:order_step] = session[:order_params] = nil
    flash[:notice] = "Order saved."
    redirect_to @order
  end
end

Validaciones

Lo último que nos queda por ver es cómo hacer las validaciones del formulario. Pondremos una validación que compruebe la presencia de los atributos shipping_name y billing_name.

/app/models/order.rb

validates_presence_of :shipping_name
validates_presence_of :billing_name

Queremos que los errores de validación de cada atributo sólo aparezcan en su paso apropiado, lo que haremos añadiendo una condición en los validadores.

/app/models/order.rb

validates_presence_of :shipping_name, :if => lambda { |o| o.current_step == "shipping" }
validates_presence_of :billing_name, :if => lambda { |o| o.current_step == "billing" }

Claro está, sólo queremos que el formulario cambie al paso siguiente (o anterior) si el pedido es válido, así que tenemos que modificar la acción create del controlador para que compruebe que el pedido es válido, cosa que haremos poniendo una sentencia if al código que cambia el paso y almacena el registro.

/app/controllers/orders_controller.rb

def create
  session[:order_params].deep_merge!(params[:order]) if params[:order]
  @order = Order.new(session[:order_params])
  @order.current_step = session[:order_step]
  if @order.valid?
    if params[:back_button]
      @order.previous_step
    elsif @order.last_step?
      @order.save
    else
      @order.next_step
    end
    session[:order_step] = @order.current_step
  end
  if @order.new_record?
    render 'new'
  else
    session[:order_step] = session[:order_params] = nil
    flash[:notice] = "Order saved."
    redirect_to @order
  end
end

Si ahora creamos un nuevo pedido e intentamos enviar el primer paso veremos que aparece el error de un campo pero no del otro.

Igualmente si intentamos movernos al siguiente paso y dejamos su campo vacío, sólo veremos el error correspondente.

Podemos organizar un poco la validación cambiando las expresiones lambda por métodos llamados shipping? y billing?.

/app/models/order.rb

class Order < ActiveRecord::Base
  attr_accessible :shipping_name, :billing_name
  attr_writer :current_step

  validates_presence_of :shipping_name, :if => :shipping?
  validates_presence_of :billing_name, :if => :billing?

  # other methods omittted.
    
  def shipping?
    current_step == "shipping"
  end
  
  def billing?
    current_step == "billing"
  end
end

También resulta útil tener un método que valide todos los pasos a la vez. Podemos escribir un método llamado all_valid? que recorra los pasos y compruebe que sean válidos.

/app/models/order.rb

def all_valid?
  steps.all? do |step|
    self.current_step = step
    valid?
  end
end

De esta forma si alguna vez hacemos cambios en las validaciones o en la forma en que funcionan los pasos podremos asegurarnos de que no hemos invalidado ninguno de ellos. Podemos usar este nuevo método en el controlador para garantizar qué sólo se guarde el pedido si todos sus pasos son válidos.

/app/controllers/orders_controller.rb

def create
  session[:order_params].deep_merge!(params[:order]) if params[:order]
  @order = Order.new(session[:order_params])
  @order.current_step = session[:order_step]
  if @order.valid?
    if params[:back_button]
      @order.previous_step
    elsif @order.last_step?
      @order.save if @order.all_valid?
    else
      @order.next_step
    end
    session[:order_step] = @order.current_step
  end
  if @order.new_record?
    render 'new'
  else
    session[:order_step] = session[:order_params] = nil
    flash[:notice] = "Order saved."
    redirect_to @order
  end
end

Lo más útil del método all_valid? es que si uno de los pasos no valida entonces se convierte en el paso actual por lo que al usuario se le mostrará el primer paso que no ha validado.

Y eso es todo por este episodio. Tenemos que tener siempre en mente que estamos almacenando los parámetros del pedido en la sesión, esto quiere decir que si un usuario tiene múltiples ventanas o pestañas abiertas estas compartirán la información de sesión. Si quisiéramos tratar las ventanas o pestañas de forma indepnediente tendríamos que almacenar los parámetros del pedido en la base de datos y guardar el modelo al principio, utilizando la acción update para ir grabando cada paso. Alternativamente se podrían guardar los parámetros como campos ocultos en el formulario.

Por último, si le echamos un vistazo a la acción create veremos que es bastante más larga y complicada de lo que debería ser. Si bien para nuestros propósitos esto está bien así, si quisiéramos usar esta técnica para una aplicación de producción tendríamos que refactorizarla un poco.

Generadores en Rails 3

Thu, 17 Jun 2010 18:29:24 +0000

A los que hayan usado Rails alguna vez les resultarán familiares los generadores y habrán utilizado el comando script/generate para crear modelos, controladores, andamiajes, etcétera. En Rails 3 los generadores han sido reescritos en su totalidad, siendo muy diferentes de los de la versión 2. De entrada ahora son mucho más modulares y esto quiere decir que son más fáciles de adaptar según nuestras preferencias.

Si en el directorio raíz de una aplicación Rails 3 ejecutamos rails g veremos la lista de los generadores disponibles en esa aplicación. Si no hemos creado nuestros propios generadores tan sólo veremos los que vienen incluidos en Rails 3: controller, generator, helper, integration_test, mailer, metal, migration, model, observer, performance_test, plugin, resource, scaffold, scaffold_controller, session_migration y stylesheets. En su mayoría estos generadores se comportan igual que sus equivalentes en Rails 2.

Para ver la ayuda acerca de un generador en concreto podemos ejecutar el generador con la opción --help. Si lo hacemos con el generador de andamiajes veremos que hay muchas opciones disponibles que nos dan bastante flexibilidad para personalizar el comportamiento del generador.

$ rails g scaffold --help
Usage:
  rails generate scaffold NAME [field:type field:type] [options]

Options:
  -c, --scaffold-controller=NAME  # Scaffold controller to be invoked
                                  # Default: scaffold_controller
      [--singleton]               # Supply to create a singleton controller
      [--force-plural]            # Forces the use of a plural ModelName
  -y, [--stylesheets]             # Indicates when to generate stylesheets
                                  # Default: true
  -o, --orm=NAME                  # Orm to be invoked
                                  # Default: active_record

ScaffoldController options:
  -e, [--template-engine=NAME]  # Template engine to be invoked
                                # Default: erb
      [--helper]                # Indicates when to generate helper
                                # Default: true
  -t, [--test-framework=NAME]   # Test framework to be invoked
                                # Default: test_unit

Runtime options:
  -f, [--force]    # Overwrite files that already exist
  -p, [--pretend]  # Run but do not make any changes
  -q, [--quiet]    # Supress status output
  -s, [--skip]     # Skip files that already exist

TestUnit options:
  -r, [--fixture-replacement=NAME]  # Fixture replacement to be invoked
      [--fixture]                   # Indicates when to generate fixture
                                    # Default: true

ActiveRecord options:
  [--parent=PARENT]  # The parent class for the generated model
  [--timestamps]     # Indicates when to generate timestamps
                     # Default: true
  [--migration]      # Indicates when to generate migration
                     # Default: true

Nótese que algunas opciones vienen con valores por defecto. Por ejemplo la opción --stylesheets por defecto vale true. Pero, ¿y si no queremos que las hojas de estilo sean generadas automáticamente? Pues bien, cuando tenemos una opción booleana cuyo valor por defecto es true podemos poner el prefijo --no para desactivar dicha opción. A continuación crearemos un andamiaje llamado project, pero sin hoja de estilos esta vez.

$ rails g scaffold project name:string --no-stylesheets
      invoke  active_record
      create    db/migrate/20100602201538_create_projects.rb
      create    app/models/project.rb
      invoke    test_unit
      create      test/unit/project_test.rb
      create      test/fixtures/projects.yml
       route  resources :projects
      invoke  scaffold_controller
      create    app/controllers/projects_controller.rb
      invoke    erb
      create      app/views/projects
      create      app/views/projects/index.html.erb
      create      app/views/projects/edit.html.erb
      create      app/views/projects/show.html.erb
      create      app/views/projects/new.html.erb
      create      app/views/projects/_form.html.erb
      invoke    test_unit
      create      test/functional/projects_controller_test.rb
      invoke    helper
      create      app/helpers/projects_helper.rb
      invoke      test_unit
      create        test/unit/helpers/projects_helper_test.rb

Si inspeccionamos la salida del comando veremos que no se han generado hojas de estilo porque hemos desactivado la opción.

La salida del generador muestra (además del listado de los archivos que se han creado) una serie de llamadas a invoke. Estas líneas indican cuándo se están invocando otros generadores. Esto quiere decir que el generador de andamiajes no hace mucho por sí solo, sino que delega en otros generadores como el generador active_record que crea el archivo del modelo y la migración. El generador active_record llama a otro generador test_unit, para crear un fichero de tests unitarios. Este patrón se repite más abajo cuando el generador scaffold_controller invoca los generadores erb, test_unit y helper para crear el resto de archivos conectados con un controlador y sus vistas. Esto hace que este sistema sea muy modular y podamos reemplazar lo que nos interese: si por ejemplo nos interesa utilizar Haml en lugar de erb en las vistas, o Shoulda o RSpec en lugar de Test::Unit podríamos utilizar otros generadores para generar el andamiaje.

Con esto ya podemos repasar otra vez la lista de opciones que nos muestra el generador de andamiajes. Todo debería empezar a adquirir más sentido. Por ejemplo la opción --orm nos permite cambiar el mapeo objeto-relacional que generará nuestros modelos (podríamos usar DataMapper en lugar de ActiveRecord). Más abajo en la lista de opciones hay una lista de opciones de ActiveRecord que sólo aplican a la versión de ActiveRecord del generador así como las opciones de los generadores de Test::Unit y ScaffoldController.

Cambio de las opciones por defecto

Aunque poder pasar a los generadores opciones como --no-stylesheets es bastante útil, sería mucho más útil si pudiéramos cambiar el valor por defecto de estas opciones, y eso en Rails 3 lo podemos hacer (a nivel de aplicación) modificando el archivo config/application.rb., que es generado automáticamente cuando se crea la aplicación Rails, y que viene con la siguiente sección comentada:

/config/application.rb

# Configure generators values. Many other options are available, be sure to check the documentation.
# config.generators do |g|
#   g.orm             :active_record
#   g.template_engine :erb
#   g.test_framework  :test_unit, :fixture => true
# end

Si quitamos los comentarios de esta sección podemos cambiar las opciones por defecto de los generadores en nuestra aplicación. Las opciones que se muestran coinciden con los valores por defecto. Por ejemplo para desactivar la generación de hojas de estilo por defecto podríamos escribir:

/config/application.rb

# Configure generators values. Many other options are available, be sure to check the documentation.
config.generators do |g|
  g.stylesheets false
end

Si ahora ejecutamos el comando help en el generador de andamiajes veremos que la nueva opción por defecto entra en acción y la opción --stylesheets ya no tendrá true como valor por defecto.

$ rails g scaffold --help
Usage:
  rails generate scaffold NAME [field:type field:type] [options]

Options:
  -y, [--stylesheets]             # Indicates when to generate stylesheets
  -c, --scaffold-controller=NAME  # Scaffold controller to be invoked
                                  # Default: scaffold_controller
      [--singleton]               # Supply to create a singleton controller
      [--force-plural]            # Forces the use of a plural ModelName
  -o, --orm=NAME                  # Orm to be invoked
                                  # Default: active_record

Hagamos algo un poco más a la aventura, cambiemos el framework de pruebas para que sea Shoulda en lugar de Test::Unit, y vamos a cambiar las fixturas por Factory Girl usando la opción fixture-replacement.

Por supuesto antes de hacer esto tenemos que detallar cuáles son las gemas relevantes en el fichero Gemfile de la aplicación. Tan sólo necesitaremos estas gemas en el entorno de test, así que las agruparemos.

/Gemfile

group :test do
  gem "shoulda"
  gem "factory_girl"
end

Por desgracia estas dos gemas no incluyen oficialmente generadores para Rails 3 pero podemos utilizar otra gema llamada rails3-generators que sí que proporciona generadores adaptados a Rails 3 de muchos plugins y gemas, incluyendo Shoulda y Factory Girl. Vamos a añadir dicha gema también al fichero Gemfile pero sólo lo haremos en el entorno de desarrollo.

/Gemfile

gem "rails3-generators", :group => :development

Con esto, sólo tenemos que ejecutar

bundle install

para instalar las gemas. Una vez que se hayan instalado las gemas podemos ejecutar rails g para ver una lista de los generadores que hay disponibles. Al final de la lista ahora deberían aparecer los nuevos generadores definidos en la gema rails3-generators.

Con estos nuevos generadores podemos modificar la configuración de application.rb y poner los valores por defecto de las opciones test_framework y fixture_replacement.

/config/application.rb

# Configure generators values. Many other options are available, be sure to check the documentation.
config.generators do |g|
  g.stylesheets false
  g.test_framework :shoulda
  g.fixture_replacement :factory_girl
end

Ahora cuando ejecutemos la ayuda del generador de andamiajes otra vez veremos que habrá cambiado para mostrar las opciones por defecto de framework de pruebas.

$ rails g scaffold --help
Usage:
  rails generate scaffold NAME [field:type field:type] [options]
  ...

ActiveRecord options:
  [--parent=PARENT]      # The parent class for the generated model
  [--migration]          # Indicates when to generate migration
                         # Default: true
  [--timestamps]         # Indicates when to generate timestamps
                         # Default: true
  [--textframework=NAME] # Test framework to be invoked
                         # Default: shoulda

Shoulda options:
  [--fixture-replacement=NAME]  # Fixture replacement to be invoked
                                # Default: factory_girl
  [--dir=DIR]                   # The directory where the model tests should go
                                # Default: test/unit

Podemos probar todo esto generando un nuevo andamiaje para un modelo llamado task.

$ rails g scaffold task project_id:integer name:string
      invoke  active_record
      create    db/migrate/20100604202823_create_tasks.rb
      create    app/models/task.rb
      invoke    shoulda
      create      test/unit/task_test.rb
      invoke      factory_girl
      create        test/factories/tasks.rb
       route  resources :tasks
      invoke  scaffold_controller
      create    app/controllers/tasks_controller.rb
      invoke    erb
      create      app/views/tasks
      create      app/views/tasks/index.html.erb
      create      app/views/tasks/edit.html.erb
      create      app/views/tasks/show.html.erb
      create      app/views/tasks/new.html.erb
      create      app/views/tasks/_form.html.erb
       error    shoulda [not found]
      invoke    helper
      create      app/helpers/tasks_helper.rb
       error      shoulda [not found]

Al principio vemos que se invocan correctamente los generadores de shoulda y factory_girl pero que más abajo, no se pudo encontrar un generador de Shoulda para erb o el fichero helper. Si vemos otra vez la lista de helpers comprobaremos que sólo tenemos generadores Shoulda para los modelos y los controladores.

$ rails g
  ...
Shoulda:
  shoulda:controller
  shoulda:model

¿Qué podemos hacer aquí? Bueno, si examinamos la página de las Guías Rails sobre generadores veremos que es posibile añadir generadores de respaldo por si no se encuentran ciertos generadores. Nuevamente, lo único que hay que hacer es modificar el bloque de configuración en application.rb.

/config/application.rb

# Configure generators values. Many other options are available, be sure to check the documentation.
config.generators do |g|
  g.stylesheets false
  g.test_framework :shoulda
  g.fallbacks[:shoulda] = :test_unit 
  g.fixture_replacement :factory_girl
end

Ahora ya podemos generar andamiajes con Shoulda y los generadores utilizarán los generadores correspondientes a Test::Unit si no se puede encontrar un generador adecuado de Shoulda.

Personalización de las plantillas

Lo último que nos queda por ver en este episodio es cómo personalizar las plantillas generadas. Debajo se muestra la vista generada para la acción index del controlador que acabamos de generar.

/app/views/tasks/index.html.erb

<h1>Listing tasks</h1>

<table>
  <tr>
    <th></th>
    <th></th>
    <th></th>
  </tr>

<% @tasks.each do |task| %>
  <tr>
    <td><%= link_to 'Show', task %></td>
    <td><%= link_to 'Edit', edit_task_path(task) %></td>
    <td><%= link_to 'Destroy', task, :confirm => 'Are you sure?', :method => :delete %></td>
  </tr>
<% end %>
</table>

<br />

<%= link_to 'New Task', new_task_path %>

Supongamos que queremos eliminar la etiqueta br al final de la plantilla y poner el enlace del final en su párrafo. ¿Cómo podemos cambiar la plantilla de forma que estos cambios ocurran en todas las vistas generadas?

Podemos crear nuestras propias plantillas en un directorio llamado templates dentro del directorio lib. Los generadores mirarán ahí en busca de plantillas en lugar de utilizar las incluidas por defecto. Para determinar qué plantilla tenemos que redefinir tendremos que mirar el código fuente del generador. El código de los generadores está en el directorio railties/lib/rails/generators y las plantillas por defecto están en el directorio erb/scaffold/templates/. Podemos copiar los contenidos de index.html.erb de ese directorio para cambiarlo según nos convenga.

Tenemos que crear una estructura de directorios similar por lo que nuestra plantilla de índice personalizada tendría que estar en /lib/templates/erb/scaffold/index.html.erb. Ahí podemos poner la plantilla por defecto sobre la que hacer nuestros cambios. Una vez que los hayamos hecho si creamos un nuevo andamiaje, por ejemplo para un modelo llamado Category veremos que la vista de índice ya incorpora nuestra propia plantilla.

rails g scaffold category name:string

/app/views/categories/index.html.erb

<h1>Listing categories</h1>

<table>
  <tr>
    <th>Name</th>
    <th></th>
    <th></th>
    <th></th>
  </tr>

<% @categories.each do |category| %>
  <tr>
    <td><%= category.name %></td>
    <td><%= link_to 'Show', category %></td>
    <td><%= link_to 'Edit', edit_category_path(category) %></td>
    <td><%= link_to 'Destroy', category, :confirm => 'Are you sure?', :method => :delete %></td>
  </tr>
<% end %>
</table>

<p><%= link_to 'New Category', new_category_path %></p>

Y eso es todo por este episodio. En Rails 3 se han introducido muchas mejoras en los generadores que los hacen mucho más fáciles de personalizar.

Consultas avanzadas con Rails 3

Sat, 29 May 2010 08:36:39 +0000

En este episodio trataremos el uso de consultas avanzadas con Rails 3. En el episodio 202 [verlo, leerlo] vimos las novedadades de ActiveRecord en Rails 3; en esta ocasión continuaremos a partir de ahí y veremos algunos usos más avanzados.

Uso de métodos de clase en lugar de ámbitos

En la aplicación de ejemplo que vamos a usar tenemos dos modelos: Product y Category, donde un producto pertenece a una categoría. El modelo de producto tiene dos ámbitos con nombre: discontinued, que devuelve todos aquellos productos cuyo atributo discontinued tiene el valor true, y price, que devuelve todos los productos cuyo precio es inferior a un argumento dado.

/app/models/product.rb

class Product < ActiveRecord::Base
  belongs_to :category
  scope :discontinued, where(:discontinued => true)
  scope :cheaper_than, lambda { |price| where("price < ?", price) }
end

En el segundo ámbito estamos usando una función lambda. Si algunas vez tenemos que usar una de estas en un ámbito con nombre deberíamos considerar utilizar en su lugar un método de clase, sobre todo si estamos pasando un gran número de parámetros o si el contenido del ámbito es complejo. Nuestro caso es muy sencillo pero de todas formas lo vamos a poner como método de clase:

/app/models/product.rb

class Product < ActiveRecord::Base
  belongs_to :category
  scope :discontinued, where(:discontinued => true)
  
  def self.cheaper_than(price)
    where("price < ?", price)
  end
end

El comportamiento del método de clase será exactamente el mismo que el del ámbito. Esto también se podía hacer también con Rails 2, pero el comportamiento en Rails 3 es mucho mejor, incluso podemos reutilizar este método en otro ámbito. Por ejemplo si queremos crear un ámbito llamado cheap que devuelva los productos cuyo precio sea inferior a 5€ podemos escribirlo así:

/app/models/products.rb

scope :cheap, cheaper_than(5)

Hay que tener, sin embargo, cuidado con una trampa. Si usamos un método de clase en un ámbito tenemos que declarar el ámbito después de que se haya definido el método de clase lo que quiere decir que tendremos que poner el ámbito un poco más abajo de lo que es habitual en el fichero de la clase.

Podemos ver la consulta SQL que genera nuestro ámbito con la consola de Rails.

ruby-1.8.7-p249 > Product.cheap.to_sql
 => "SELECT    \"products\".* FROM      \"products\" WHERE    (price < 5)"

Si aplicamos el ámbito veremos el listado de productos baratos.

>Product.cheap
 => [#<Product id: 1, name: "Top", price: 4.99, discontinued: nil, category_id: 3, created_at: "2010-05-24 21:01:59", updated_at: "2010-05-24 21:01:59">, #<Product id: 2, name: "Milk", price: 2.99, discontinued: nil, category_id: 2, created_at: "2010-05-24 21:02:38", updated_at: "2010-05-24 21:02:38">]

Asociaciones

Aprovechando que estamos en la consola veamos otro truco que tiene que ver con el uso de ámbitos sobre asociaciones. Antes decíamos que en nuestra aplicación un producto pertenece a una categoría. Esto quiere decir que podemos usar joins para devolver una consulta SQL que devuelve un inner join sobre la tabla de productos y categorías.

ruby-1.8.7-p249 > Category.joins(:products).to_sql
 => "SELECT     \"categories\".* FROM       \"categories\" INNER JOIN \"products\" ON \"products\".\"category_id\" = \"categories\".\"id\""

Queremos encontrar todas las categorías con poductos que pertenecen a un cierto ámbito, por ejemplo todas las categorías que contienen productos que cuestan menos de cinco euros. Podemos emplear dos métodos distintos para hacerlo. El primero sería usar merge de esta manera:

> Category.joins(:products).merge(Product.cheap)
 => [#<Category id: 3, name: "Games", created_at: "2010-05-24 21:00:57", updated_at: "2010-05-25 18:30:18">, #<Category id: 2, name: "Groceries", created_at: "2010-05-24 21:00:50", updated_at: "2010-05-25 18:30:39">]

O podríamos utilizar el símbolo & que es un alias de lo mismo y por tanto devolverá los mismos resultados:

> Category.joins(:products) & Product.cheap
 => [#<Category id: 3, name: "Games", created_at: "2010-05-24 21:00:57", updated_at: "2010-05-25 18:30:18">, #<Category id: 2, name: "Groceries", created_at: "2010-05-24 21:00:50", updated_at: "2010-05-25 18:30:39">]

Con estos métodos podemos encadenar otras consultas incluso aunque no sean sobre los mismo modelos, y esto es lo que nos permitirá encontrar las categorías con productos que cuestan menos de cinco euros. Si llamamos to_sql en las consultas veremos que se ha hecho un inner join y se ha añadido al final la clásula WHERE del ámbito.

> (Category.joins(:products) & Product.cheap).to_sql
 => "SELECT     \"categories\".* FROM       \"categories\" INNER JOIN \"products\" ON \"products\".\"category_id\" = \"categories\".\"id\" WHERE     (price < 5)"

Esta técnica es bastante potente si se utiliza para definir un ámbito. Podemos usarla, por ejemplo, para crear un ámbito en el modelo Category que encuentre las categorías que tengan productos baratos.

/app/models/category.rb

class Category < ActiveRecord::Base
  has_many :products
  scope :with_cheap_products, joins(:products) & Product.cheap
end

Este nuevo ámbito devolverá las mismas categorías que la consulta que escribimos anteriormente.

> Category.with_cheap_products
 => [#<Category id: 3, name: "Games", created_at: "2010-05-24 21:00:57", updated_at: "2010-05-25 18:30:18">, #<Category id: 2, name: "Groceries", created_at: "2010-05-24 21:00:50", updated_at: "2010-05-25 18:30:39">]

Cuando trabajemos con estas condiciones que cubren diferentes asociaciones hay que tener en cuenta el nombre de la tabla. Si examinamos el SQL generado al llamar al ámbito veremos que no hay un nombre de tabla en la cláusula WHERE.

> Category.with_cheap_products.to_sql
 => "SELECT     \"categories\".* FROM       \"categories\" INNER JOIN \"products\" ON \"products\".\"category_id\" = \"categories\".\"id\" WHERE     (price < 5)"

Esto podría ser un problema si ambas tablas tienen una columna llamada price porque en tal caso la consulta SQL sería ambigua. Podemos eliminar esta ambiguedad definiendo explícitamente el nombre de la tabla en el modelo Product.

/app/models/product.rb

def self.cheaper_than(price) 
  where("products.price < ?", price)
end

Con esto ya no hay peligro de que el nombre de la columna sea ambiguo. Siempre hay que especificar el nombre de las tablas cuando se construyen cadenas SQL en las condiciones de una consulta. Si estamos usando un hash (como en el ámbito) entonces no hay que preocuparse de la tabla porque Rails automáticamente lo pone.

Construcción de registros a través de ámbitos

Lo siguiente que veremos es cómo crear registros con ámbitos. Tenemos un ámbito definido sobre nuestro modelo Product llamado discontinued que encuentra todos los productos descatalogados.

> Product.discontinued
 => [#<Product id: 3, name: "Some DVD", price: 13.49, discontinued: true, category_id: 1, created_at: "2010-05-25 19:45:05", updated_at: "2010-05-25 19:45:05">]

Como el ámbito utiliza un hash podemos invocar el método build sobre él para construir un nuevo producto, que tendrá el atributo discontinued puesto a true.

> p = Product.discontinued.build
 => #<Product id: nil, name: nil, price: nil, discontinued: true, category_id: nil, created_at: nil, updated_at: nil>

Esto es así porque el atributo discontinued forma parte de la condición where, funcionando de forma parecida a una asociación en el sentido de que si se invoca build sobre una asociación automáticamente se pone la clave foránea que está asociada con dicho registro. En nuestro caso estamos tan sólo asignando valores a atributos que aparecen en la condición where. Es algo muy útil a tener en cuenta si necesitamos crear registros que cumplan un cierto ámbito.

Arel

Como colofón a este episodio presentaremos Arel. Arel se encarga de generar las consultas de ActiveRecord, será poco frecuente que tengamos que interactuar directamente con Arel pero es bueno tener un conocimiento de cómo funciona y qué puede hacer en caso de que nos haga falta.

Para trabajar con Arel directamente en Rails 3 se puede acceder a la arel_table de un modelo. Vamos a recuperar la tabla de Arel para el modelo de producto en la consola y se la asignaremos a una varialbe.

> t = Product.arel_table

Se trata de una representación de la tabla de productos. Podemos acceder a las columnas de la tabla así:

>t[:price]
 => <Attribute price>

Y sobre este objeto vamos a invocar métodos sobre un atributo para obtener condiciones de búsqueda. Por ejemplo, si queremos encontrar todos los productos que cuestan 2.99€ podemos ejecutar

> t[:price].eq(2.99)
 => #<Arel::Predicates::Equality:0x1040dd9f0 @operand1=<Attribute price>, @operand2=2.99>

Esto devuelve un predicado (que básicamente es la condición de búsqueda) Existen también otros métodos que podríamos llamar, como por ejemplo matches que ejecutará una consulta LIKE.A Al igual que con otras consultas podemos ejecutar to_sql para examinar la sentencia SQL que generará esta consulta.

> t[:name].matches('%lore').to_sql
 => "\"products\".\"name\" LIKE '%lore'"

Podemos usar el método or para encadenar predicados, por ejemplo para encontrar los productos que cuestan 2.99€ y cuyo nombre termina en ‘lore’.

t[:price].eq(2.99).or(t[:name].matches('%lore'))

Esto devolverá un predicado combinado, y podemos ver la consulta SQL al igual que antes invocando to_sql.

> t[:price].eq(2.99).or(t[:name].matches('%lore')).to_sql
 => "(\"products\".\"price\" = 2.99 OR \"products\".\"name\" LIKE '%lore')"

Podemos pasar estos predicados como argumentos al método where de ActiveRecord. Esto significa que podemos pasar el predicado que acabamos de crear a Product.where para recuperar todos los productos cuyo precio sea de 2.99€ o cuyo nombre termine en ‘lore’.

>   Product.where(t[:price].eq(2.99).or(t[:name].matches('%lore')))
 => [#<Product id: 2, name: "Milk", price: 2.99, discontinued: nil, category_id: 2, created_at: "2010-05-24 21:02:38", updated_at: "2010-05-24 21:02:38">, #<Product id: 4, name: "Knight Lore", price: 2.99, discontinued: nil, category_id: nil, created_at: "2010-05-26 19:36:02", updated_at: "2010-05-26 19:36:02">]

Tan sólo hemos arañado la superficie que nos revela ActiveRecord de Arel, que es capaz de mucho más. Hay varios plugins disponibles que aprovechan la potencia de Arel y le dan una nterfaz más conveniente como MetaWhere con el cual podemos acceder a métodos de Arel como matches y eq dentro del hash de condiciones así:

Product.where(:price.eq => 2.99, :name.matches => '%lore')

Esto nos da mucha más flexibilidad a la hora de definir el hash de condiciones, y merece la pena tenerlo en cuenta si vamos a necesitar hacer consultas más complejas sobre nuestros modelos.

Tests A/B con A/Bingo

Thu, 20 May 2010 21:54:45 +0000

Los tests A/B son una forma de experimentar con variantes de una aplicación y determinar cuáles de ellas son más efectivas. A continuación se muestra el formulario de registro de una aplicación. Al comienzo del formulario hay un párrafo que explica lo que tiene que hacer el usuario y queremos determinar cómo de efectivo es este párrafo a la hora de convencer a los usuarios para que se registren, y para esto utilizaremos un test A/B.

El funcionamiento es el siguiente: a cada visitante de la página se le mostrará o no el párrafo de la parte superior, y tenemos que determinar qué opción da los mejores resultados. Para esto tenemos que definir un evento que, cuando ocurra, nos indicará que la opción ha tenido éxito. En nuestro caso este evento ocurrirá cuando el usuario rellene el formulario y lo envíe.

Cómo escoger la herramienta adecuada

Hay varias herramientas disponibles para hacer tests A/B. Una de las que podríamos utiliar es Google Website Optimizer. No es una tecnología específica de Rails por lo que puede usarse con cualquier tipo de aplicación web, incluso con sitios estáticos. Con esta herramienta podemos dar diferentes URLs, o utilizar JavaScript para rastrear las conversiones. Se trata de una opción bastante buena pero si queremos hacer nuestros tests sobre una aplicación Rails tendremos que usar algo que se integre dentro de la aplicación para gestionar el seguimiento propiamente dicho.

Una de las soluciones específicas de Rails más populares esVanity. Devuelve informes de resultados muy vistosos e incluye bastantes funcionalidades pero hoy no vamos a tratar de ella (si bien puede que lo hagamos en algún próximo episodio). Puede resultar un poco difícil de configurar porque por motivos de rendimuento necesita una base de datos Redis pero merece la pena echarle un vistazo para ver si se ajusta a nuestras necesidades.

El plugin que vamos a usar es A/Bingo. El DSL que trae viene bastante bien para definir experimentos y es fácil de usar. La aplicación sobre la que haremos nuestros tests está escrita con Rails 2, por lo que instalaremos el plugin con

script/plugin install git://git.bingocardcreator.com/abingo.git

en el directorio de nuestra aplicación. Una vez que haya terminado generaremos una migración con

script/generate abingo_migration

y la ejecutaremos con

rake db:migrate

Con esto se generarán dos tablas nuevas en la base de datos en la que se guardarán los resultados de nuestros tests: experiments y alternatives .

En el entorno de producción es recomendable que configuremos la caché en A/Bingo para que utilice algo como memcached pero nos saltaremos esa parte porque sólo vamos a usar el entorno de desarrollo.

Nuestro primer test

Como ya hemos instalado A/Bingo podemos escribir nuestro primer test. Queremos mostrar u ocultar el párrafo de la parte superior del formulario de registro de forma que aparezca para algunos usuarios y otros no lo vean. Esto lo podemos hacer con el método ab_test:

/app/views/users/new.html.erb

<% title ("Sign up") %>

<% if ab_test "signup_intro" %>
<p>Complete the form below to create a new user account. You will then be able 
to create projects and tasks, and mark them as complete when finishing them.</p>
<% end %>
<p>Already have an account? <%= link_to "Log in", new_user_session_path %>.</p>

<% form_for @user do |form| %>
 <!-- se omite el formulario -->
<% end %>

El primer argumento que se pasa a ab_test es el nombre del test, que en este caso hemos llamado signup-intro. Si no proporcionamos más argumentos este método devolverá aleatoriamente true o false para los diferentes visitantes del sitio por lo que el párrafo se mostrará u ocultará dependiendo de quién cargue la página.

A continuación añadiremos el evento para poder rastrear los resultados. Queremos que se registre dicho evento cuando se guarde el usuario correctamente, para lo que modificaremos la acción create del controlador UsersController.

/app/controllers/users_controller.rb

def create
  @user = User.new(params[:user])
  if @user.save
    bingo! "signup_intro"
    session[:user_id] = @user.id
    flash[:notice] = "Thank you for signing up. You are now logged in."
    redirect_to root_url
  else
    render :action => 'new'
  end
end

Tan sólo tenemos que invocar el método bingo! en la acción create y pasarle el nombre del test.

Si recargamos el formulario de registro veremos que esta vez ab_test ha devuelto false por lo que no vemos el párrafo de la parte de superior. Podemos recargar la página todas las veces que queramos pero el párrafo no se va a mostrar porque se ha registrado nuestra identidad (en breve explicaremos cómo).

Si completamos el formulario y lo enviamos se activará el evento que hemos definido.

Visualización de resultados

Podemos ver los resultados de nuestro test creando un controlador para ver dichos resultados. Nosotros lo llamaremos abingo_dashboard.

script/generate controller abingo_dashboard

En este controlador sólo tenemos que incluir el módulo correspondiente de A/Bingo.

/app/controllers/abingo_dashboard_controller.rb

class AbingoDashboardController < ApplicationController
  # PENDIENTE poner autorizacion
  include Abingo::Controller::Dashboard
end

Queda claro que si pusiésemos esta aplicación en producción no querríamos que cualquiera viese este panel de control por lo que tendríamos que añadir autorización al controlador.

También tenemos que añadir una nueva ruta para que podamos acceder a este nuevo controlador.

/config/routes.rb

map.abingo_dashboard "/abingo/:action/:id", :controller => :abingo_dashboard

Una vez que esté todo ya podemos visitar http://localhost:3000/abingo y veremos nuestro panel.

Es fácil modificar las plantillas de vistas para darle los estilos que queramos a este cuadro de mandos. Sin embargo incluso con los estilos por defecto podemos ver los resultados de los experimentos, así que por ahora no los cambiaremos. Si nos fijamos en los resultados veremos que tenemos un experimento con un participante, que hemos sido nosotros mismos en la visita anterior a la página de registro, y una conversión finalizada que ocurrió cuando enviamo el formulario. El párrafo de la parte superior del formulario no se estaba mostrando por lo que el participante y su conversión aparecen en la sección de resultados "false".

Cómo se identifica a los usuarios

Antes vimos que si volvíamos a visitar el formulario de registro no veíamos nunca el párrafo porque A/Bingo siempre consideraba que nuestra identidad era la misma. Para esto tenemos que darle instrucciones sobre cómo distinguir unos usuarios de otros. Esto se hace en el controlador de aplicación escribiendo un before_filter.

/app/controllers/application_controller.rb

class ApplicationController < ActionController::Base
  helper :all # include all helpers, all the time
  protect_from_forgery # See ActionController::RequestForgeryProtection for details
  before_filter :set_abingo_identity

  private
  def set_abingo_identity
    session[:abingo_identity] ||= rand(10 ** 10)
    Abingo.identity = session[:abingo_identity]
  end
end

Hemos añadido el filtro llamado set_abingo_identity y en dicho método hemos puesto el código que determina la identidad de cada usuario. En primer lugar se comprueba la existencia de una variable de sesión llamada abingo_identity y si no existe la crea con un valor numérico aleatorio lo que significa que mientra el usuario mantenga su sesión será identificado como la misma persona por A/Bingo y verán o no el párrafo siempre de la misma forma.

Si tuviéramos autenticación de usuarios en nuestro aplicación querriamos que un usuario registrado viera siempre lo mismo independientemente de que cambiase su sesión o estén utilizando un ordenador o navegador distinto. Podemos cambiar el método set_abingo_identity para que utilice el id del usuario si hay una sesión iniciada o volver al método basado en cookie de sesión para usuarios anónimos.

/app/controllers/application_controller.rb

def set_abingo_identity
  if current_user
    Abingo.identity = current_user.id
  else
    session[:abingo_identity] ||= rand(10 ** 10)
    Abingo.identity = session[:abingo_identity]
  end
end

También podemos comprobar si la visita viene de una araña web y darle a cada robot la misma identidad para que los resultados no se vean afectados por estos visitantes no humanos.

/app/controllers/application_controller.rb

def set_abingo_identity
  if request.user_agent =~ /\b(Baidu|Gigabot|Googlebot|libwww-perl|lwp-trivial|msnbot|SiteUptime|Slurp|WordPress|ZIBB|ZyBorg)\b/i
     Abingo.identity = "robot"
   elsif current_user
     Abingo.identity = current_user.id
   else
     session[:abingo_identity] ||= rand(10 ** 10)
     Abingo.identity = session[:abingo_identity]
   end
end

Comprobamos si se trata de un robot comparando la cadena de agente de usuario contra una lista de nombres conocidos y si coincide, se establece el valor de identidad igual a la cadena “robot”. De esta forma todos los robots que visiten la página serán identificados como el mismo usuario.

Durante el desarrollo de la aplicación, he visitado la página de alta con diferentes identidades y me he registrado un par de veces, lo que queda reflejado en el cuadro de mandos de A/Bingo. Ahora aparecen ocho participantes, dos de los cuales vieron el párrafo y seis no.

Tests más complejos

Vamos a terminar el episodio mostrando cómo se pueden introducir múltiples opciones diferentes para un único test. El test signup_into es un test sencillo pero también nos puede interesar tener más de dos posibilidades (por ejemplo si queremos probar con muchos títulos diferentes de página).

Es importante tener siempre en cuenta que si tenemos múltiples tests en una única página nuestros resultados pueden sesgarse hacia las opciones que aparezcan con más frecuencia. Esto es muy importante en aplicaciones en producción pero como esto es tan sólo una aplicación de ejemplo no nos preocupa.

Podemos llamar a ab_test con dos argumentos para crear un test con múltiples opciones. El segundo parámetro será un array con las diferentes opciones que queremos testar. En nuestro caso queremos probar con tres títulos diferentes de página y podemos cambiar la página de alta para mostrar uno de ellos :

/app/views/users/new.html.erb

<% title ab_test("signup_title", ["Sign up", "Registration", "Free Sign up"]) %>

Con esto cada usuario que visite la página verá uno de estos títulos de forma aleatoria. Por supuesto, esto es trivial para algo tan sencillo como poner el título de la página pero si queremos utilizar el valor aleatorio más de una vez en la misma página podemos pasarle un bloque a ab_test.

/app/views/users/new.html.erb

<% ab_test("signup_title", ["Sign up", "Registration", "Free Sign up"]) do |signup_title| %>
<% title signup_title %>
<% end %>

Es posible, si no estamos usando la última versión de A/Bingo, que veamos el mensaje “can’t modify frozen array”. Ryan Bates ha enviado un parche para corregir este problema que ha sido aceptado, por lo que si vemos este error podemos intentarlo otra vez tras actualizar la versión del plugin.

Cuando visitemos la página de registro veremos una de las opciones del título y al página mostrará o no el párrafo de la parte superior. Pero aún nos queda una cosa por hacer. Aunque hemos configurado el test en la vista, no estamos registrando si ha tenido éxito o no en el controlador, lo que podemos hacer añadiendo otra llamada a bingo! in la acción create:

/app/controllers/users_controller.rb

def create
  @user = User.new(params[:user])
  if @user.save
    bingo! "signup_intro"
    bingo! "signup_title"
    session[:user_id] = @user.id
    flash[:notice] = "Thank you for signing up. You are now logged in."
    redirect_to root_url
  else
    render :action => 'new'
  end
end

Cabría sospechar que esto se nos puede ir de las manos si acabamos con muchos tests sobre una acción determinada. En estos casos conviene hacer una única llamada al método bingo! con el nombre de una conversión y utilizar el nombre de dicha conversión como un argumento extra del método ab_test en la vista, y de esta forma podemos reemplazar las dos llamadas a bingo! por una:

/app/controllers/users_controller.rb

def create
  @user = User.new(params[:user])
  if @user.save
    bingo! "signup"
    session[:user_id] = @user.id
    flash[:notice] = "Thank you for signing up. You are now logged in."
    redirect_to root_url
  else
    render :action => 'new'
  end
end

... siempre que en la vista le pasemos el nombre de la conversión como parte del hash de argumentos.

/app/views/users/new.html.erb

<% ab_test("signup_title", ["Sign up", "Registration", "Free Sign up"], :conversion => "signup") do |signup_title| %>
  <% title signup_title %>
<% end %>

<% if ab_test "signup_intro", nil, :conversion => "signup" %>
<!-- resto de la vista -->

Nótese que como el segundo test es de tipo booleano simple hemos pasado nil como segundo argumento.

Y con esto cerramos este episodio. Los tests A/B son una forma excelente de experimentar con variantes de una aplicación web y medir el éxito de sus resultados. Desde aquí os aninamos a probarlo en vuestras aplicaciones usando Google Website Optimizer, Vanity o A/Bingo.