apux

apux

Publicado
Marzo 10, 2014

Próximos Eventos

Blog

Formularios anidados

En ocasiones, tenemos modelos asociados que necesitamos manipular en un único formulario en lugar de tener un formulario por cada uno de ellos. La gema nested_form nos permite crear formularios complejos cuando trabajamos con modelos anidados, su uso es realmente sencillo y su documentación cubre los aspectos más comunes. Sin embargo, existen algunos escenarios en los que debemos de tener algunas consideraciones adicionales para que todo funcione correctamente, especialmente con Rails 4.

En este tutorial, veremos cómo utilizar esta gema cuando incluimos relaciones uno a muchos y muchos a muchos en nuestros modelos.

Creación del proyecto

Para este tutorial, trabajaremos con un proyecto en Rails 4.1. Al momento de escribir este tutorial, es una versión que todavía está en RC, por lo que se se instala de la siguiente manera:

gem install rails --pre

Para empezar, agregamos la gema nested_form a nuestro proyecto.

echo "gem 'nested_form'" >> Gemfile

Y ejecutamos

bundle install

Ahora debemos agregar el javascript de la gema al asset pipeline. En el archivo application.js, ingresamos la siguiente línea:

//= require jquery_nested_form

Nota: La versión de nested_form utilizada para este post es 0.3.2.

Creación de modelos

Trabajaremos con tres modelos relacionados entre sí. El modelo Proyecto tiene muchas Tareas (relación uno a muchos), y las Tareas están asociadas a muchos Empleados (relación muchos a muchos).

Por comodidad, usaremos scaffold para generar los recursos de Proyecto y Empleado, mientras que Tarea no tendrá ni vista ni controlador propio, sino que se creará a través del formulario de Proyecto, que es donde utilizaremos la gema nested_form que acabamos de instalar.

rails generate scaffold proyecto nombre fecha_entrega:date
rails generate scaffold empleado nombre_completo
rails generate model tarea nombre prioridad:integer proyecto:references

Para la relación muchos a muchos entre tareas y empleados necesitamos una migración adicional para crear la tabla intermedia entre estos dos modelos. En Rails 4, podemos hacerlo de la siguiente manera:

rails generate migration create_join_table_empleados_tareas empleado tarea

Este comando nos genera una migración que crea la tabla intermedia para nuestra relación muchos a muchos:

class CreateJoinTableEmpleadosTareas < ActiveRecord::Migration
  def change
    create_join_table :empleados, :tareas do |t|
      # t.index [:empleado_id, :tarea_id]
      # t.index [:tarea_id, :empleado_id]
    end
  end
end

Ahora creamos la base de datos y generamos las tablas por medio de las migraciones. En este ejemplo, utilizaremos SQLite como manejador de base de datos, por lo que no es necesario configurar nada más. Si prefieres utilizar MySql, Postgres o algún otro manejador, asegúrate de incluir su gema correspondiente en el archivo Gemfile y adaptar el archivo config/database.yml.

rake db:create
rake db:migrate

Modificamos los modelos correspondientes para que incluyan las relaciones que hemos creado en la base de datos:

# app/models/proyecto.rb
class Proyecto < ActiveRecord::Base
  has_many :tareas
end

# app/models/tarea.rb
class Tarea < ActiveRecord::Base
  belongs_to :proyecto
  has_and_belongs_to_many :empleados
end

# app/models/empleado.rb
class Empleado < ActiveRecord::Base
  has_and_belongs_to_many :tareas
end

Datos de inicio

Agreamos empleados a la base de datos por medio del archivo db/seeds.rb.

# db/seeds.rb
Empleado.create! [
  {nombre_completo: 'Juan Pérez'},
  {nombre_completo: 'Pedro López'},
  {nombre_completo: 'María Hernández'},
  {nombre_completo: 'Carlos Sánchez'},
]

Para almacenar esa información en la base de datos:

rake db:seed

Por supuesto, también podemos agregar empleados manualmente desde nuestra aplicación, ejecutando rails server, y accediendo a la ruta empleados/new.

Formulario de proyectos

Ya con nuestros modelos creados, debemos trabajar con el formulario de proyectos, donde podemos crear un proyecto que contenga muchas tareas que a su vez estén asociadas con muchos empleados.

El formulario que nos creó el scaffold es el siguiente:

<%# app/views/proyectos/_form.html.erb %>
<%= form_for(@proyecto) do |f| %>
  <% if @proyecto.errors.any? %>
    <div id="error_explanation">
      <h2><%= pluralize(@proyecto.errors.count, "error") %> prohibited this proyecto from being saved:</h2>

      <ul>
      <% @proyecto.errors.full_messages.each do |msg| %>
        <li><%= msg %></li>
      <% end %>
      </ul>
    </div>
  <% end %>

  <div class="field">
    <%= f.label :nombre %><br>
    <%= f.text_field :nombre %>
  </div>
  <div class="field">
    <%= f.label :fecha_entrega %><br>
    <%= f.date_select :fecha_entrega %>
  </div>
  <div class="actions">
    <%= f.submit %>
  </div>
<% end %>

Para utilizar la gema, debemos utilizar el helper nested_form_for en lugar de form_for y agregar los campos de las tareas. Rails nos provee de un helper para agregar campos a objetos asociados: fields_for. El formulario quedaría de la siguiente manera:

<%# app/views/proyectos/_form.html.erb %>
<%= nested_form_for(@proyecto) do |f| %>
  <% if @proyecto.errors.any? %>
    <div id="error_explanation">
      <h2><%= pluralize(@proyecto.errors.count, "error") %> prohibited this proyecto from being saved:</h2>

      <ul>
      <% @proyecto.errors.full_messages.each do |msg| %>
        <li><%= msg %></li>
      <% end %>
      </ul>
    </div>
  <% end %>

  <div class="field">
    <%= f.label :nombre, 'Nombre del proyecto' %><br>
    <%= f.text_field :nombre %>
  </div>
  <div class="field">
    <%= f.label :fecha_entrega %><br>
    <%= f.date_select :fecha_entrega %>
  </div>
  <fieldset id="tareas">
    <%= f.fields_for :tareas do |tareas_form| %>
      <div class="field">
        <%= tareas_form.label :nombre, 'Nombre de la tarea' %><br>
        <%= tareas_form.text_field :nombre %>
      </div>
      <div class="field">      
        <%= tareas_form.label :prioridad %><br>
        <%= tareas_form.text_field :prioridad %>
      </div>
      <%= tareas_form.link_to_remove "Eliminar esta tarea" %>
    <% end %>
    <p><%= f.link_to_add "Agregar una tarea", :tareas %></p>
  </fieldset>
  <div class="actions">
    <%= f.submit %>
  </div>
<% end %>

Uso de accepts_nested_attributes_for

Si en estos momentos entramos a nuestra aplicación e intentamos crear un proyecto, obtendremos el siguiente error:

Invalid association. Make sure that accepts_nested_attributes_for is used for :tareas association.

Esto es porque nuestro formulario de Proyecto incluye ya los atributos anidados de Tareas, pero no hemos configurado nuestros modelos para que permita recibir estos campos.

En nuestro modelo Proyecto agregamos el accepts_nested_attributes_for:

# app/models/proyecto.rb
class Proyecto < ActiveRecord::Base
  has_many :tareas
  accepts_nested_attributes_for :tareas, allow_destroy: true
end

De esta manera, Proyecto puede recibir y procesar los atributos de tareas mediante la llave tareas_attributes. Ejemplo:

Proyecto.create nombre: 'Mi proyecto',
             fecha_entrega:  1.month.from_now,
             tareas_attributes: [
                                 {nombre: 'Tarea 1', prioridad: 5},
                                 {nombre: 'Tarea 2', prioridad: 3}
             ]

Con esto, le indicamos a ActiveRecord que cree un proyecto con dos tareas.

La opción allow_destroy nos permitirá eliminar alguna tarea de la lista de tareas agregando la bandera :_destroy. Ejemplo:

Proyecto.create nombre: 'Mi proyecto',
             fecha_entrega:  1.month.from_now,
             tareas_attributes: [
                                 {nombre: 'Tarea 1', prioridad: 5},
                                 {nombre: 'Tarea 2', prioridad: 3, _destroy: true }
             ]

Con esto, le indicamos a ActiveRecord que cree un proyecto con una sola tarea (Tarea 1), ya que Tarea 2 está marcada para ser eliminada y por lo tanto no se crea. Si la tarea ya existe previamente, al incluir la opción _destroy: true se borrará también de la base de datos, pero para eso habrá que especificar el id, como veremos más adelante.

Si tratamos de entrar a nuestro formulario de proyectos (/proyectos/new) veremos que el formulario se muestra correctamente y podemos agregar o eliminar tareas visualmente de manera dinámica.

Agregar tareas por omisión

Si queremos que nuestro proyecto se muestre inicialmente con algunas tareas asociadas, podemos agregar algunas desde el controlador. Ejemplo:

#app/controllers/proyectos_controller.rb
def new
  @proyecto = Proyecto.new
  2.times { @proyecto.tareas.build }
end

Parciales

En nuestro ejemplo, el modelo Proyecto tiene dos campos, y el modelo Tarea otros dos, pero en un caso real, ambos tendrían muchos más campos y mostrarlos todos dejaría un tanto sucio el código de nuestro formulario. En esos casos, es mejor utilizar parciales.

nested_form permite el uso de parciales de una manera elegante. Necesitamos crear una parcial con el nombre en singular de nuestro modelo más el sufijo _fields. En la nueva parcial, la variable del formulario anidado (tareas_form en nuestro caso), se pasa simplemente como f. Los archivos quedarían de la siguiente manera:

El formulario principal de proyectos de proyectos.

<%# app/views/proyectos/_form.html.erb %>
<%= nested_form_for(@proyecto) do |f| %>
  <% if @proyecto.errors.any? %>
    <div id="error_explanation">
      <h2><%= pluralize(@proyecto.errors.count, "error") %> prohibited this proyecto from being saved:</h2>

      <ul>
      <% @proyecto.errors.full_messages.each do |msg| %>
        <li><%= msg %></li>
      <% end %>
      </ul>
    </div>
  <% end %>

  <div class="field">
    <%= f.label :nombre, 'Nombre del proyecto' %><br>
    <%= f.text_field :nombre %>
  </div>
  <div class="field">
    <%= f.label :fecha_entrega %><br>
    <%= f.date_select :fecha_entrega %>
  </div>
  <fieldset id="tareas">
    <%= f.fields_for :tareas %>
    <p><%= f.link_to_add "Agregar una tarea", :tareas %></p>
  </fieldset>
  <div class="actions">
    <%= f.submit %>
  </div>
<% end %>

La nueva parcial:

<%# app/views/proyectos/_tarea_fields.html.erb %>
<div class="field">
  <%= f.label :nombre, 'Nombre de la tarea' %><br>
  <%= f.text_field :nombre %>
</div>
<div class="field">
  <%= f.label :prioridad %><br>
  <%= f.text_field :prioridad %>
</div>
<%= f.link_to_remove "Eliminar esta tarea" %>

Como vemos, queda más limpio y mejor organizado.

Show

Antes de crear un proyecto por medio del formulario, modificaremos el show para mostrar no sólo los datos del proyecto sino también los de las tareas asociadas. Así podremos saber si las tareas se crearon correctamente.

<%# app/views/proyectos/show.html.erb %>
<p id="notice"><%= notice %></p>

<p>
  <strong>Nombre:</strong>
  <%= @proyecto.nombre %>
</p>

<p>
  <strong>Fecha entrega:</strong>
  <%= @proyecto.fecha_entrega %>
</p>

<p>
  <strong>Tareas:</strong>
  <p>
    <% @proyecto.tareas.each do |tarea| %>
      Nombre: <%= tarea.nombre %><br/>
      Prioridad: <%= tarea.prioridad %>
      <hr/>
    <% end %>
  </p>
</p>

<%= link_to 'Edit', edit_proyecto_path(@proyecto) %> |
<%= link_to 'Back', proyectos_path %>

Strong parameters

Ahora sí, es momento de crear nuestro primer proyecto por medio del formulario. Ingresamos los datos tanto del proyecto como de las tareas, y damos clic en el botón de submit.

La página de show nos muestra el nombre del proyecto y la fecha de entrega pero la lista de tareas está vacía, lo que significa que algo falló en el proceso.

El problema se encuentra en el controlador. Rails 4 incluye strong_parameters, que valida que se reciban sólo atributos autorizados para un formulario. Por omisión, al ejecutar el scaffold, sólo se autorizan los campos que se incluyen en el modelo Proyecto, por lo que tenemos que agregar a mano los campos del modelo Tarea, incluyendo el atributo _destroy, para que una tarea pueda ser eliminada de la lista. Estos atributos se agregan a la lista que recibe el método permit como un hash, donde la llave es tareas_attributes y el valor es un arreglo con los nombres de los campos.

# app/controllers/proyectos_controller.rb

# [...]

# Never trust parameters from the scary internet, only allow the white list through.
def proyecto_params
  params.require(:proyecto).permit(
    :nombre, :fecha_entrega, tareas_attributes: [
      :nombre, :prioridad, :_destroy
    ]
  )
end

Y ahora sí, al crear un proyecto con tareas, éstas se crearán correctamente.

Update

Ahora bien, si queremos modificar un proyecto que ya hayamos ingresado, podemos hacerlo en el path correspondiente, por ejemplo, /proyectos/1/edit.

Sin embargo, aquí notamos un comportamiento extraño. En lugar de actualizar las tareas, crea siempre tareas nuevas. Es decir, mantiene las tareas creadas anteriormente y trata las tareas que estamos modificando como si las estuvieras agregando. Vemos también otro error: si queremos eliminar una tarea, ésta no se elimina, sino que sigue ahí.

Este comportamiento sucede porque para realizar la modificación, ActiveRecord espera recibir como parámetro, el id del modelo a modificar. Si el id corresponde a un registro de la base de datos, entonces lo modifica. Ejemplo:

Imaginemos un proyecto con dos tareas, las tareas tienen los ids 1 y 2 respectivamente.

proyecto = Proyecto.first
proyecto.update nombre: 'Mi nuevo proyecto',
             fecha_entrega:  1.week.from_now,
             tareas_attributes: [
                                 {nombre: 'Tarea nueva', prioridad: 1 },
                                 {id: 1, nombre: 'Tarea modificada', prioridad: 4 },
                                 {id: 2, nombre: 'Tarea 2', prioridad: 2, _destroy: true }
             ]

Este fragmento de código actualiza los datos del proyecto, incluyendo sus tareas. La primera tarea no lleva id, por lo que simplemente se crea y se asocia al proyecto. Las siguientes dos tareas sí llevan id, por lo que se entiende que ya existen previamente y están asociadas a ese proyecto; esas tareas se actualizan. En este caso, la tarea con id 1 sólo actualiza sus datos, mientras que la tarea con id 2 se elimina porque incluye la bandera _destroy como true.

Strong parameters

Conociendo la teoría, la solución es sencilla. Basta con agregar a la lista de parámetros aceptados, el id de las tareas. Para esto, modificamos de nuevo la lista de nuestros strong parameters.

# app/controllers/proyectos_controller.rb

# [...]

# Never trust parameters from the scary internet, only allow the white list through.
def proyecto_params
  params.require(:proyecto).permit(
    :nombre, :fecha_entrega, tareas_attributes: [
      :id, :nombre, :prioridad, :_destroy
    ]
  )
end

Y listo. Con eso podemos modificar y eliminar tareas correctamente desde nuestro formulario de proyectos.

Muchos a muchos

Ya hemos asociado correctamente proyectos y tareas desde un solo formulario, pero aún nos falta asociar tareas y empleados, que es una relación muchos a muchos.

Lo primero que modificaremos será nuestro show para incluir información sobre los empleados.

<%# app/views/proyectos/show.html.erb %>
<p id="notice"><%= notice %></p>

<p>
  <strong>Nombre:</strong>
  <%= @proyecto.nombre %>
</p>

<p>
  <strong>Fecha entrega:</strong>
  <%= @proyecto.fecha_entrega %>
</p>

<p>
  <strong>Tareas:</strong>
  <p>
    <% @proyecto.tareas.each do |tarea| %>
      Nombre: <%= tarea.nombre %><br/>
      Prioridad: <%= tarea.prioridad %><br/>
      Empleados: <%= tarea.empleados.map(&:nombre_completo).to_sentence %>
      <hr/>
    <% end %>
  </p>
</p>

<%= link_to 'Edit', edit_proyecto_path(@proyecto) %> |
<%= link_to 'Back', proyectos_path %>

Ahora procedemos a modifcar nuestro formulario para incluir empleados.

Como primer recurso, recurro a este railscast, donde se muestra una forma de hacerlo utilizando chec_kbox_tag.

En un formulario normal, la asociación podría hacerce de la siguiente manera:

<% Empleado.all.each do |empleado| %>
  <%= check_box_tag 'tarea[empleado_ids][]',
                    empleado.id,
                    @tarea.empleado_ids.include?(empleado.id) %>
  <%= empleado.nombre_completo %><br/>
<% end %>

Sin embargo, eso da por sentado que la tarea es el formulario del primer nivel, lo que es falso para nuestro caso. Nosotros necesitaríamos de una estructura más compleja que incluyera el proyecto y la tarea (mediante tareas_attributes).

Si analizamos el request que se hace cuando envía nuestro formulario, veremos que los parámetros llevan la siguiente estructura:

Started POST "/proyectos" for 127.0.0.1 at 2013-08-12 12:41:01 -0500
Processing by ProyectosController#create as HTML
  Parameters: {"utf8"=>"✓",
               "authenticity_token"=>"RtyGum+m6wIvaoOAvxcQnIlvMEPGStBmFvaTL+t+paQ=",
               "proyecto"=>{
                             "nombre"=>"Mi proyecto",
                             "fecha_entrega(1i)"=>"2013",
                             "fecha_entrega(2i)"=>"9",
                             "fecha_entrega(3i)"=>"22",
                             "tareas_attributes"=>{
                                                    "0"=>{
                                                           "nombre"=>"Tarea 1",
                                                           "prioridad"=>"1",
                                                           "_destroy"=>"false"},
                                                    "1"=>{
                                                           "nombre"=>"Tarea 2",
                                                           "prioridad"=>"",
                                                           "_destroy"=>"false"}
                                                  }
                           },
               "commit"=>"Create Proyecto"}

Como vemos, el formulario envía tareas_attributes no como un arreglo sino como un hash, donde la llave es un índice para cada tarea. Si quisiéramos incluir los checkboxes de empleados, tendríamos que indicar el número de cada tarea. Otro aspecto a tomar en cuenta es que no tenemos @tarea, sino @proyecto, por lo que tendríamos que tomarlo del objeto del formulario. Algo como esto:

<%= check_box_tag "proyecto[tareas_attributes][#{id_tarea}][empleado_ids][]",
                  empleado.id,
                  f.object.empleado_ids.include?(empleado.id) %>

Para el caso de nuestro ejemplo, es posible llevar el control del id de la tarea por medio de alguna variable generada en _form y pasarla a la parcial _tareas_fields, pero pensando en varios niveles de formularios anidados, sería muy complicado llevar el registro de cada uno de los ids de los modelos e irlos pasando entre parciales. Por ejemplo, si la tarea no estuviera relacionada directamente con empleados, sino con asignaciones, y las asignaciones con empleados, tendríamos un tag parecido a esto:

<%= check_box_tag(
    "proyecto[tareas_attributes][#{tarea_index}][asignaciones_attributes][#{asignacion_index}][empleado_ids][]",
    empleado.id,
    f.object.empleado_ids.include?(empleado.id)) %>

Lo que poco a poco se vuelve insostenible.

Afortunadamente, Rails 4 incluye un helper para asociaciones muchos a muchos a través de checkboxes, y eso nos facilita bastante las cosas. El helper es collection_check_boxes. Nuestra parcial de tareas quedaría de la siguiente manera:

<%# app/views/proyectos/_tarea_fields.html.erb %>
<div class="field">
  <%= f.label :nombre, 'Nombre de la tarea' %><br>
  <%= f.text_field :nombre %>
</div>
<div class="field">
  <%= f.label :prioridad %><br>
  <%= f.text_field :prioridad %>
</div>
<div class="field">
  <%= f.collection_check_boxes :empleado_ids, Empleado.all, :id, :nombre_completo %>
</div>
<%= f.link_to_remove "Eliminar esta tarea" %>

Haciendo uso de este helper, no tenemos que preocuparnos por nada más, Rails se encarga de llevar los índices por nosotros.

Strong parameters

Si probamos nuestro formulario ahora, funciona correctamente, los parámetros que genera son los correctos, pero aún no guarda las asociaciones con empleados. De nuevo, esto tiene que ver con strong parameters. Debemos indicar que acepte los campos correspondientes a empleado_ids.

Aquí, hay que observar un pequeño truco para hacer que strong parameters acepte la lista de ids que le mandamos desde nuestro formulario. Si agregamos simplemente el campo :empleado_ids, strong parameters lo filtrará como un campo cuando en realidad necesitamos que lo considere un arreglo. En este caso debemos indicarlo como un hash, donde la llave sea :empleado_ids y el valor un arreglo vacío.

# app/controllers/proyectos_controller.rb

# [...]

# Never trust parameters from the scary internet, only allow the white list through.
def proyecto_params
  params.require(:proyecto).permit(
    :nombre, :fecha_entrega, tareas_attributes: [
      :id, :nombre, :prioridad, :_destroy, empleado_ids: []
    ]
  )
end

Y ahora sí, nuestro formulario funciona correctamente asociando proyectos, tareas y empleados.

Conclusiones

Rails permite trabajar con formularios anidados de manera relativamente fácil. La gema nested_form hace que este trabajo sea todavía más sencillo, sin embargo, hay que conocer el funcionamiento de otros módulos, como strong parameters y acceptsnestedattributes_for para que todo funcione correctamente.

Este tutorial cubrió los aspectos básicos para el trabajo con formularios anidados, pero todavía quedan algunos detalles que cubrir. En el siguiente post explicaré cómo utilizar la gema cuando tenemos una estructura de modelos más compleja. En particular, cuando tenemos modelos dentro de un namespace y recursos anidados ( nested resources ) en nuestras rutas.

Recursos

Para quien esté interesado en conocer el funcionamiento interno de la gema, puede revisar este post. Además, estos railscasts son de mucha utilidad: Nested Model Form Part 1 y Nested Model Form Part 2. También hay una versión actualizada (de paga): Nested Model Form (revised).

Un post muy completo sobre Strong Parameters.

El railscast de habtm con checkboxes y su versión de pago.

La documentación de collection check boxes.

También creé un proyecto de ejemplo en github para que sea fácil revisar el código.