1- Instalación de Searchlogic

Por supuesto, la instalación de Searchlogic es muy simple:

sudo gem install searchlogic

Una vez instalado el gem agregamos la siguiente línea a nuestro archivo de configuración de entorno:

#config/environment.rb
config.gem "searchlogic"

Aunque es más recomendable el método anterior, también se puede instalar como plugin:

script/plugin install git://github.com/binarylogic/searchlogic.git

2- Conceptos Básicos

Searchlogic es un plugin muy completo y flexible: nos brinda filtros y una clase para encapsularlos, métodos de ordenamiento, helpers para nuestras vistas, integración con otros plugins (como WillPaginate), etc. No vamos a cubrir todos sus aspectos, por lo menos no en esta ocasión; pero sí conoceremos algunos conceptos básicos que nos darán el puntapié necesario para animarnos a usarlo en nuestras aplicaciones. Comenzaremos viendo su concepto central: filtros.

Filtros (Named Scopes)

Una vez instalado, Searchlogic nos permite utilizar cierto número de filtros predeterminados, que en realidad son los famosos named_scopes de Rails. En la documentación hay una lista completa de todas las opciones que podemos usar; aquí conoceremos sólo algunas.

Searchlogic no necesita nada de configuración: podemos utilizar sus filtros directamente. Supongamos que tenemos un modelo llamado User con algunos de los campos más comunes: username, email, password y age (nombre de usuario, email, contraseña y edad, respectivamente). También ya tenemos varios usuarios registrados, y lo que queremos es ver cuáles de los usuarios registrados menores a 20 años tienen una cuenta de email dentro del Reino Unido (termina en “.co.uk“). Para ello podemos levantar nuestra consola rails y simplemente ingresar lo siguiente:

User.age_lt(20).email_ends_with(".co.uk")

Searchlogic nos devuelve una lista con los usuarios que cumplen con dichos criterios. Podemos concatenar toda la cantidad de filtros que sea necesario, uno tras otro. El método age_lt significa age_less_than (edad menor a); y como ésta, existen también otras formas de comparación similares, junto con sus abreviaturas. En la documentación podemos encontrar todas las posibilidades.

Es importante notar que podemos usar estos filtros con cualquier campo. Si por ejemplo tuviéramos un campo que sea login_count para almacenar la cantidad de veces que el usuario inició sesión en nuestro sitio, podemos buscar todos los usuarios del Reino Unido que hayan entrado más de 100 veces o más de la siguiente forma:

User.email_ends_with(".co.uk").login_count_gte(100)
# gte es la abreviatura de "greater than or equal"
# y significa "mayor o igual a".

Negando Filtros

De la misma forma que podemos buscar los usuarios cuyos emails terminen con “.co.uk”, también podemos buscar aquellos cuyos emails no terminen con dicha cadena:

User.email_does_not_end_with(".co.uk")

#Otro ejemplo:
User.username_not_like("juan")
#devuelve todos aquellos cuyo nombre de usuario no contiene la cadena "juan"

Podemos hacer lo mismo con cualquier otro filtro.

Combinando Filtros

Puede ser el caso que querramos buscar a todos los usuarios cuyo nombre (name) o nombre de usuario (username) contengan la cadena “juan”. Para ello podemos combinar los filtros en un mismo llamado por medio de la palabra “or”, de la siguiente forma:

User.name_or_username_like("juan")

Todos o Cualquiera

Los filtros aceptan también más de un elemento, pero para ello debemos usar alguno de los modificadores especiales para múltiples parámetros: all (todos) o any (cualquiera). Veamos algunos ejemplos:

#Busca los usuarios con cuenta de email del Reino Unido o de Argentina:
User.email_ends_with_any(".co.uk", ".ar")

#Busca los usuarios que tengan "Juan" y "Perez" dentro de su nombre:
User.name_like_all("Juan", "Perez")
#Algunos resultados pueden ser:
#  Juan Perez Aguilar
#  Juan Marcos Perez

#También podemos pasar un Array:
User.name_like_all(["Juan", "Perez"])

Ordenamiento

En SQL es posible ordenar los resultados que obtenemos, y Searchlogic no se ha olvidado de ello. Para ordenar los resultados anteriores por nombre de usuario podemos hacer lo siguiente:

#Ordena por nombre de usuario desde la A a la Z
User.email_ends_with(".co.uk").login_count_gte(100).ascend_by_username
#Ordena por nombre de usuario desde la Z a la A
User.email_ends_with(".co.uk").login_count_gte(100).descend_by_username

De forma similar a los demás filtros, “ascend_by” y “descend_by” son filtros dinámicos, y en su caso particular deben ser precedidos por el nombre del campo a ordenar (username).

Rendimiento

De aquí nos puede surgir la duda de si Searchlogic implementa todos los named scopes posibles para cada modelo de forma predeterminada. Por suerte esto no es así, sino que los crea a medida que los vamos utilizando. Además, una vez creado el named scope, Searchlogic no lo vuelve a crear si lo necesitamos de nuevo. Por lo tanto, no hay que temer por nuestros recursos: el rendimiento con Searchlogic es muy similar al rendimiento que obtendríamos si usáramos nuestros propios named scopes.

Algo más que vale destacar en cuanto a rendimiento: Searchlogic no ejecuta ningún query en la base de datos sino hasta que llamemos al último filtro en la cadena. En el caso anterior, por ejemplo, la siguiente consulta SQL se ejecuta sólo luego de aplicarse el filtro “login_count_gte“:

SELECT * FROM `users` WHERE ((users.login_count >= 100) AND (users.email LIKE '%.co.uk'))

3- La clase Search

Searchlogic también nos permite buscar utilizando una clase llamada Search. Esta clase nos sirve para añadir o quitar filtros a una búsqueda, cuyas condiciones quedan almacenadas en la instancia. Igual que en el caso anterior, Searchlogic ejecuta un sólo query a la hora de buscar. En este caso, sin embargo, lo ejecuta luego de que llamemos a algunos de los métodos de búsqueda. Veamos un ejemplo:

@search = User.search #Crea el objeto Search para el modelo User
@search.age_lt(20)
@search.email_ends_with(".co.uk")
# Hasta aquí todavía no se ha hecho ningún query a la base de datos

@search.all #ejecuta el query y devuelve todos los registros
@search.first #ejecuta el query y devuelve sólo el primer registro
@search.count #devuelve el número de registros encontrados
#etc.

Otra posibilidad menos atractiva pero potencialmente más flexible es acceder directamente al Hash de filtros, de la siguiente manera:

@search = User.search #Crea el objeto Search
@search.conditions[:age_lt] = 20 # notar la diferencia de sintaxis
@search.conditions[:name_begins_with] = "a"
# Otra forma que puede ser útil en algunos casos:
@search.conditions.merge!({:email_ends_with => ".co.uk"})
#Ahora @search contiene el siguiente hash:
# {:age_lt=>20, :email_ends_with=>".co.uk", :name_begins_with=>"a"}
@search.all #devuelve todos los resultados filtrados

Para quitar un filtro del objeto Search, basta con llamar su método delete y pasarle la condición que queremos borrar:

@search.delete(:name_begins_with)
#=> {:age_lt=>20, :email_ends_with=>".co.uk"}

4- Búsquedas Avanzadas

Hay varias formas de búsqueda que requieren utilizar conceptos un poco más avanzados, como los JOINS o INCLUDES de SQL. Sin embargo, Searchlogic nuevamente nos facilita la tarea con sus potentes herramientas. Para esta sección vamos a suponer que los usuarios de la tabla Users “tienen muchos” Permissions (permisos) a través de una relación habtm (explicar los conceptos básicos de este tipo de relación escapa a nuestro propósito en este momento).

Buscando en clases Asociadas

De acuerdo con la relación que tenemos entre los usuarios y sus permisos, supongamos que queremos buscar a todos los usuarios que tengan permiso para comentar:

@search = User.search
@search.permissions_name_is("comment")
@search.all # ejecuta la consulta

La consula SQL generada es:

SELECT `users`.* FROM `users` INNER JOIN `permissions_users` ON `permissions_users`.user_id = `users`.id INNER JOIN `permissions` ON `permissions`.id = `permissions_users`.permission_id WHERE (permissions.name = 'comment')

En otras palabras, podemos acceder a la descendencia de clases simplemente concatenándola al llamar al filtro. Otro ejemplo, con más niveles de descendencia, en donde los usuarios tienen un rol que a su vez tiene muchos permisos, y en donde queremos encontrar todos los usuarios que puedan comentar:

@search = User.search
@search.role_permissions_name_is("comment")
@search.all # ejecuta la consulta

Si queremos resolver un problema de consultas N+1, también podemos especificar un INCLUDE en alguno de los métodos de búsqueda:

@results = @search.all(:include => :permissions) # ejecuta dos consultas SQL
@results.first.permissions # no ejecuta ninguna consulta SQL

Las consultas SQL ejecutadas por la primera línea:

SELECT `users`.* FROM `users` INNER JOIN `permissions_users` ON `permissions_users`.user_id = `users`.id INNER JOIN `permissions` ON `permissions`.id = `permissions_users`.permission_id WHERE (permissions.name = 'comment')
SELECT `permissions`.*, t0.user_id as the_parent_record_id FROM `permissions` INNER JOIN `permissions_users` t0 ON `permissions`.id = t0.permission_id WHERE (t0.user_id IN (1,200))

Procedimientos de Filtro (Scoped Procedures)

En nuestra aplicación queremos filtrar a los usuarios que no sean del Reino Unido (UK) y cuya edad se encuentre entre los 12 y 20 años inclusive (es decir, que sean adolescentes). Supongamos que queremos hacer esto en muchos lugares de nuestra aplicación, pero volver a llamar a ambos filtros uno por uno, definitivamente, no es muy DRY.

En casos como este, podemos recurrir a los Scope Procedures, que básicamente significa que podemos darle un nombre a esa combinación de filtros y añadirla como un procedimiento de nuestro modelo User. Para el ejemplo, vamos a nombrar esa combinación de filtros uk_teens (“adolescentes del Reino Unido” en inglés):

#Para crear el Scope Procedure
@search = User.search
@search.email_does_not_end_with(".co.uk")
@search.age_lt(20).age_gt(12)
User.scope_procedure :uk_teens, lambda{ @search }

#Otra forma de hacerlo, pero no tan limpia:
User.scope_procedure :uk_teens, lambda { User.email_does_not_end_with(".co.uk").age_lt(20).age_gt(12) }

# Finalmente, para utilizar el Scope Procedure
User.uk_teens.all # devuelve todos los resultados
User.search(:uk_teens => true) # lo mismo que lo anterior

Es importante notar el uso del método lambda, que lo que hace es recibir un bloque que va a ser ejecutado cada vez que llamamos al Scoped Procedure. Explicar esto a fondo escapa del ámbito de este tutorial. Otro elemento importante es el parámetro que le pasamos al método search, que le dice a Searchlogic que quiere utilizar el método uk_teens como si fuera un filtro más. Podemos utilizar la misma convención para llamar a cualquier named_scope que hayamos declarado manualmente.

También es importante advertir que el ejemplo en la documentación oficial no funciona (tal como está a la fecha de publicación de este artículo). El ejemplo en este artículo demuestra el uso correcto, a mi entender, de los Scoped Procedures.

Conclusión

En este tutorial, basado en la documentación oficial de Searchlogic, cubrimos los aspectos básicos de Searchlogic y algunos de los avanzados. Como fue mencionado antes, el plugin es muy flexible, y los usos que le podemos dar son tan variados como nuestra imaginación. Decidí no cubrir la parte de búsqueda con formularios, explicada en la documentación y en el Railscast de Searchlogic, porque es útil sólo para casos muy específicos (vistas de administrador) y se va del eje central de este artículo.

Por favor, no dudes en dejar un rápido comentario ante cualquier duda, corrección o sugerencia! También podés subscribirte al feed o por email (en la barra de navegación) para recibir notificaciones de los últimos artículos.

En este tutorial veremos cómo permitirle a un usuario subir una foto para su perfil. Paperclip se encargará no sólo de guardar la foto en nuestro servidor, sino también de crear automáticamente un thumbnail (vista en miniatura) de esa imagen.

Para el procesar imágenes, Paperclip  utilizar una librería muy popular conocida como ImageMagick. Es esta librería la que nos permitirá generar los thumbnails para nuestros usuarios. Comencemos con los requisitos necesarios:

1- Instalación de ImageMagick

Este paso es necesario solamente para aquellos usuarios que no tengan ImageMagick instalado en su equipo, que por lo general son los usuarios de Windows. Las distribuciones de Linux y Mac tienen el paquete instalado por defecto, pero para evitar problemas en el futuro no estaría de más cerciorar que el paquete está presente en el sistema.

Windows

La instalación en Windows es muy simple: hay que descargar uno de los instaladores (ante la duda, el Q16-windows-dll funciona en la mayoría de los sistemas) y ejecutarlo. Una vez dentro del instalador, activar la opción “Update executable search path” para que la librería pueda ser accedida desde todo el sistema.

Ubuntu

Para instalar ImageMagick en Ubuntu o similares (si aún no está instalado), correr el siguiente comando en la consola: sudo apt-get install imagemagick. Si alguien necesita información de cómo hacerlo en otra distribución, dejen un comentario y voy a tratar de responder lo más pronto posible.

2- Instalación de Paperclip

Instalamos Paperclip de la misma forma que con cualquier otro plugin:

script/plugin install git://github.com/thoughtbot/paperclip.git

Para aquellos que prefieran instalarlo como un gem, agregamos en nuestro environment.rb:

config.gem 'paperclip', :source => 'http://gemcutter.org'

Y luego corremos en la consola rake gems:install, para instalar Paperclip en el entorno.

3- Preparar la Base de Datos

Supongamos que ya tenemos un modelo User en donde reside la información sobre un usuario de nuestro sitio. Lo que queremos hacer es brindarle al usuario la posibilidad de subir una imagen de perfil (foto, avatar, etc) a nuestro sitio. Esta imagen va a ser accedida por medio de un atributo de User que llamaremos picture. Por suerte, Paperclip nos ayuda con un generador, que facilitará mucho nuestra tarea.

En la consola:

script/generate paperclip user picture

El generador toma dos parámetros: el primero  indica el modelo al que le queremos adjuntar una imagen, en nuestro caso user. El segundo indica el nombre que le daremos (dentro del modelo) a esta imagen adjunta, y aquí utilizamos picture. Lo que hace este generador es crear un nuevo archivo de migración para agregar cuatro campos nuevos a nuestro modelo User:

#db/migrate/20091129014122_add_attachments_picture_to_user.rb
class AddAttachmentsPictureToUser < ActiveRecord::Migration
  def self.up
    add_column :users, :picture_file_name, :string
    add_column :users, :picture_content_type, :string
    add_column :users, :picture_file_size, :integer
    add_column :users, :picture_updated_at, :datetime
  end

  def self.down
    remove_column :users, :picture_file_name
    remove_column :users, :picture_content_type
    remove_column :users, :picture_file_size
    remove_column :users, :picture_updated_at
  end
end

A esta altura debemos correr rake db:migrate para que los cambios se apliquen a la base de datos.

4- Adjuntar Paperclip al Modelo

Una vez hechos los cambios en la base de datos, necesitamos indicarle a nuestro modelo User que queremos un archivo adjunto con nombre picture. Paperclip detectará y utilizará automáticamente los campos que acabamos de agregar a la base de datos. Para hacerlo, agregamos lo siguiente en nuestro modelo:

#app/models/user.rb
class User < ActiveRecord::Base
  # Paperclip
  has_attached_file :picture,
    :styles => {
      :thumb=> "100x100#",
      :small  => "150x150>" }
end

Es importante mencionar que Paperclip aún no sabe que sólo queremos permitir al usuario subir imágenes. Pero más allá de eso, hay un par de parámetros que nos interesan.

El primero es :picture, que le indica a Paperclip el nombre del archivo adjunto. Es importante que coincida con el nombre que decidimos darle en la base de datos en el paso anterior.

El segundo parámetro es :styles. Es utilizado sólamente cuando estamos tratando con imágenes, porque no tiene efecto sobre ningún otro tipo de archivos. Este parámetro toma un Hash de claves y sus correspondientes valores. Cada clave define una nueva imagen que se va a generar a partir de la imagen original, y su valor indica qué formato va a tener. Para ver qué formas puede tomar el valor, referirse a la documentación de ImageMagick. En este caso en particular, se guardarán tres imágenes: la original, una thumb (de tamaño 100×100 y recortada en los bordes) y otra small (de tamaño máximo 150×150). Para ver cómo modificar el nombre y la ruta donde las imágenes son almacenadas del lado servidor, referirse a la documentación de Paperclip Interpolations.

Si queremos evitar que se guarde la imagen original, podemos definir un estilo que se llame :original y Paperclip guardará la imagen con este nuevo formato, descartando la imagen original. Esto es especialmente útil si queremos evitar guardar imágenes muy pesadas en nuestro servidor.

Por último, los estilos también pueden ser Procs (una de las características interesantes de Ruby). Por ejemplo, si le queremos permitir al usuario definir un ancho y un alto para su imagen (y tenemos dichos valores guardados en los atributos picture_width y picture_height de nuestro modelo, respectivamente):

has_attached_file :picture,
  :styles => {
    :thumb=> "100x100#",
    :small  => "150x150>" }
    :custom => Proc.new {
      |user| # devuelve la instancia actual del usuario
      "#{user.photo_width}x#{user.photo_height}>" }
  }

Sin embargo, en nuestro ejemplo no necesitamos hacer esto, así que nos quedaremos con los estilos thumb y small.

5- Definir Validaciones

Las validaciones de Paperclip son una de sus características más útiles. El plugin nos provee métodos especiales para algunas de las validaciones más comunes, aunque también podemos agregar manualmente las que nos parezca conveniente a través del método validate de ActiveRecord.

Todos las validaciones toman dos parámetros: (nombre, opciones = {}). El primero especifica a qué archivo adjunto queremos aplicar la validación. Esto es sobre todo útil si el modelo que utilizamos debe tener más de un archivo adjunto. El segundo parámetro es un Hash en donde debemos, en la mayoría de los casos, especificar ciertos valores que le darán sentido a la validación. El Hash de opciones admite algunas opciones que son comunes tanto para este tipo de validación de Paperclip como para el resto de las validaciones de ActiveRecord:

:if => Acepta una condición para la validación (importante recordar: de la misma forma que lo hacen las validaciones de ActiveRecord). Ejecuta la validación si la condición evalúa a verdadero.

:unless => Lo mismo que lo anterior, sólo que la validación no se ejecuta si la condición evalúa a verdadero.

:message => Define el mensaje que se mostrará si el archivo adjunto no pasa la validación. Es útil si necesitamos traducir los mensajes de error al Español (u otro idioma), pero si estamos trabajando en inglés los mensajes suelen ser bastante descriptivos.

Los métodos que nos provee Paperclip para validar los archivos adjuntos son:

validates_attachment_presence (nombre, opciones = {})
Funciona igual que el validates_presence_of de ActiveRecord: el modelo no se podrá guardar siempre que no haya un archivo adjunto (al campo especificado por nombre).

validates_attachment_size (nombre, opciones = {})
Valida el tamaño del archivo adjunto. Debemos indicar cómo queremos validarlo a través de las opciones. Algunas opciones de ejemplo son (hay que utilizar sólo una de ellas):

:less_than => 5.megabytes # menos de 5 Mb
:greater_than => 500.kilobytes # más de 5 Mb
:in => (100..5.megabytes) # de 100 bytes hasta 5 Mb

validates_attachment_content_type (nombre, opciones = {})
Valida que el archivo adjunto pertenezca a los tipos MIME que especificaremos en las opciones a través de la clave :content_type. Un ejemplo:

:content_type => ['image/jpeg', 'image/png']

Con esto en mente, podemos agregarle las validaciones que necesitamos a nuestro modelo User. No utilizaremos validates_attachment_presence porque queremos que el usuario pueda decidir tener una imagen de perfil o no.

#app/models/user.rb
class User < ActiveRecord::Base
  # Paperclip
  has_attached_file :picture,
    :styles => {
      :thumb=> "100x100#",
      :small  => "150x150>" }
  # Validaciones de Paperclip
  validates_attachment_size :picture, :less_than => 2.megabytes
  validates_attachment_content_type :picture, :content_type => ['image/jpeg', 'image/png']
end

6- Las Vistas

Ya casi terminando, veremos que tanto en las Vistas como en los Controladores podemos tratar al modelo como estamos acostumbrados. Un formulario de ejemplo que permite a un usuario subir su foto de perfil:

<!-- app/views/user/new.html.erb -->
<% form_for @user, :html => { :multipart => true } do |form| %>
  <ol>
    <!-- Otros campos del usuario ... -->
    <li>
      <%= form.label :picture, "Picture" %>
      <%= form.file_field :picture %>
    <li>
      <%= form.submit "Save Picture!" %>
    </li>
  </ol>
<% end %>

Como se puede observar, tratamos a nuestro campo picture de Paperclip como si fuera un file_field. Cuando el usuario seleccione una imagen y envíe el formulario al servidor, Paperclip sabrá qué hacer con la imagen y hará todo el trabajo por nosotros. Lo único que tenemos que hacer que puede ser diferente a lo que hayamos hecho hasta ahora, es decirle a Rails que queremos un formulario multipart. Esto es necesario siempre que queremos subir imágenes o archivos (además de datos comunes) en un formulario HTML.

Para mostrar la imagen en cualquier vista podemos utilizar el método url de nuestro objeto Paperclip. Este método devuelve una ruta a la imagen original (sin parámetros) o a las secundarias (con el parámetro apropiado):

<%= image_tag @user.picture.url %>
<%= image_tag @user.picture.url(:thumb) %>
<%= image_tag @user.picture.url(:small) %>

7- El Controlador

El controlador es lo más fácil, porque si lo hicimos correctamente, no tenemos que cambiar absolutamente nada de código para que Paperclip funcione:

#app/controllers/users_controller.rb
class UsersController < ApplicationController
  #...

  def new
    @user = User.new
  end

  def create
    @user = User.create(params[:user])
  end

  def update
    @user = current_user
    if @user.update_attributes(params[:user])
      flash[:info] = "Sus datos fueron actualizados con éxito"
      redirect_to user_path(@user)
    else
      render :action => :edit
    end
  end

  def edit
    @user = current_user
  end

  private

  def current_user
    User.find_by_id(session['user_id'])
  end
end

Es importante destacar nuevamente que este código es genérico y puede ser utilizado con o sin Paperclip. Tanto en la acción create como en update, nuestros archivos Paperclip son validados y guardados dentro de ActiveRecord::Base#save!. Esto ocurre tanto dentro del método create como del método update_attributes.

Conclusión

Vimos un ejemplo sencillo de cómo utilizar Paperclip para adjuntar imágenes a nuestros modelos. Vale la pena repetir que Paperclip puede manejar no sólo imágenes, sino cualquier tipo de archivos. Para usos más avanzados de este plugin, referirse a la documentación.

En el futuro seguramente estaré escribiendo más artículos sobre Paperclip. Si le gustó este artículo, puede subscribirse a mi RSS Feed para ser notificado en cuanto salga uno nuevo. También hay un formulario al costado de esta página en donde puede subscribir su email para que las notificaciones le lleguen a su casilla de correo.

Si hay algún error en este artículo, sugerencias, o simplemente ha sido útil, no dude de comentar!

Recursos

Parte de este artículo está basado en los siguientes recursos disponibles en Inglés:

• Repositorio Git de Paperclip
• Paperclip: Attaching Files in Rails (de principios del 2008)
• Goodbye Attachment Fu, hello Paperclip

Este tutorial está basado en el sitio de ejemplo oficial de Authlogic, en GitHub.

1- Instalación

Authlogic se puede instalar como gem o como plugin.

A) Para instalar como plugin (recomendado por ellos mismos):

$ ./script/plugin install git://github.com/binarylogic/authlogic.git

B) Para instalar como gem, basta agregar lo siguiente a environment.rb

# config/environment.rb
config.gem "authlogic"

Luego, ejecutar en la consola (si usás linux quizás necesites correrlo con sudo):

rake gems:install

2- Crear el modelo UserSession

El modelo UserSession es aquel que se va a encargar de administrar todo lo que tiene que ver con una sesión en nuestro sitio: su creación (login), su actualización, y su destrucción (logout). Como ellos mismos comentan en su sitio de ejemplo, de la misma forma que ActiveRecord se sitúa entre nosotros y la base de datos, el modelo UserSession se situá entre nosotros y las cookies del usuario.

Asumiendo que lo que queremos autenticar es un modelo nombrado User, vamos a crear nuestro modelo UserSession. En la consola:

script/generate session user_session

Esto va a crear un archivo similar al siguiente:

#app/models/user_session.rb
class UserSession < Authlogic::Session::Base
  # aquí va la configuración
end

Es importante destacar que este modelo hereda de Authlogic::Session::Base, lo cual nos permitirá configurarlo muy fácilmente. Por ejemplo, es aquí donde podemos proteger a nuestros usuarios de ataques de fuerza bruta. Para más información, ver la documentación de los submódulos de Authlogic::Session.

3- Crear el modelo User

El modelo User es el modelo que guarda la información de registro de los usuarios. Se pueden incluir todos los campos que sean necesarios para nuestra aplicación, pero existen algunos campos que Authlogic administra de forma automática, facilitando muchísimo nuestro trabajo. Pero primero, creemos el modelo: en la consola,

script/generate model user login:string crypted_password:string

Authlogic utilizará este modelo para autenticar. El tutorial oficial (en inglés) incluye una lista que muestra cuáles son los campos administrados por Authlogic. Todos los campos son opcionales excepto el que se utiliza para que la sesión persista: persistence_token. Para este tutorial utilizaremos una combinación de nombre de usuario y contraseña para autenticar. Como fueron especificados como parámetros, ambos campos (login y crypted_password, respectivamente) fueron añadidos automáticamente por Rails a nuestro archivo de migración cuando corrimos el generador anterior. Por lo tanto, podemos directamente ejecutar rake db:migrate para crear la tabla users junto con dichos campos en nuestra base de datos.

4- Configurar el modelo

Configurar el modelo es extremadamente simple:

class User < ActiveRecord::Base
  acts_as_authentic do |c|
    c.opcion = valor # ver documentación
  end # el bloque es opcional
end

A partir de ahora el modelo intentará validar automáticamente los campos nombre de usuario, email, contraseña, etc. La configuración en bloque nos permite personalizar cómo queremos que se validen esos campos, definir nombres distintos para los campos o incluso cambiar el algoritmo de encriptación para la contraseña.

5- Crear el Controlador para UserSessions

Es a través de este controlador que el usuario iniciará y cerrará su sesión. Es importante aclarar que este controlador no debería ser usado para registrar usuarios u otras acciones similares que tienen que ver con la administración de usuarios; lo utilizaremos simplemente para iniciar o cerrar sesión. En la consola:

script/generate controller user_sessions

Aquí hay un ejemplo del contenido básico de un controlador de UserSessions. También existen ejemplos paras las vistas correspondientes. Sin cambiar lo básico, podemos agregar toda la funcionalidad que queramos, tanto a las vistas como al controlador.

En cuanto a las rutas, hace falta conectar el modelo UserSession con el controlador. Para lograrlo:

#config/routes.rb
map.resource :user_session

6- Persistiendo Sesiones

Para persistir sesiones utilizaremos el ApplicationController. Agregaremos algunos métodos al controlador y a dos de ellos los convertiremos en métodos helper, para poder accederlos desde las vistas. Estos métodos fueron extraídos del sitio ejemplo, son simplemente ilustrativos y pueden ser personalizados según la necesidad.

# app/controllers/application.rb
class ApplicationController < ActionController::Base
  helper :all
  filter_parameter_logging :password, :password_confirmation
  helper_method :current_user_session, :current_user

  private
  def current_user_session
    return @current_user_session if defined?(@current_user_session)
    @current_user_session = UserSession.find
  end

  def current_user
  return @current_user if defined?(@current_user)
    @current_user = current_user_session && current_user_session.user
  end

  def require_user
     unless current_user
       store_location
       flash[:notice] = "You must be logged in to access this page"
       redirect_to new_user_session_url
       return false
     end
   end

   def require_no_user
     if current_user
       store_location
       flash[:notice] = "You must be logged out to access this page"
       redirect_to account_url
       return false
     end
   end

   def store_location
     session[:return_to] = request.request_uri
   end

   def redirect_back_or_default(default)
     redirect_to(session[:return_to] || default)
     session[:return_to] = nil
   end
end

Ahora tendremos acceso al usuario y su sesión en toda nuestra aplicación, con sólo llamar a current_user y current_user_session, respectivamente.

7- Restringiendo Acceso

Authlogic se encarga simplemente de la autenticación, pero nos permite restringir acceso en nuestros controladores de forma muy fácil. Lo podemos hacer a mano o utilizando algún otro plugin que agregue esta funcionalidad. Lockdown es un plugin muy bueno que permite restringir acceso según los roles que tenga un usuario, y se integra de forma excelente con Authlogic.

Sin embargo, aquí incluiremos un ejemplo muy simple de cómo restringir acceso manualmente dentro de uno de nuestros controladores. En nuestro ApplicationControler:

# app/controllers/application.rb
class ApplicationController < ActionController::Base

  #... (código anterior)

  def require_user
     unless current_user
       store_location
       flash[:notice] = "You must be logged in to access this page"
       redirect_to new_user_session_url
       return false
     end
   end

   def require_no_user
     if current_user
       store_location
       flash[:notice] = "You must be logged out to access this page"
       redirect_to account_url
       return false
     end
   end

   def store_location
     session[:return_to] = request.request_uri
   end

   def redirect_back_or_default(default)
     redirect_to(session[:return_to] || default)
     session[:return_to] = nil
   end
end

Y luego utilizamos estos nuevo métodos en nuestros controladores. Por ejemplo, si queremos que una lista de productos pueda ser vista por cualquier persona, pero que sólo usuarios logueados puedan administrarla (crear productos, actualizarlos, borrarlos, etc.), hacemos lo siguiente en nuestro ProductsController (asumiendo que existe):

# app/controllers/products_controller.rb
class ProductsController < ActionController::Base
  before_filter :require_user, :except => [:index, :show]

  #GET /products/new
  def new
    #...
  end

  # ... (resto del código)
end

De esta forma, si una visita intenta añadir un producto accediendo a “sitio.com/products/new”, será redirigida automáticamente al formulario de login para que se identifique con su usuario antes de poder continuar. Esta lógica se encuentra en el ApplicationController, dentro del método require_user.

8- Registrando Usuarios

Registrar usuarios es muy simple con Authlogic. De hecho, funciona exactamente igual que si no lo usáramos, siempre y cuando utilicemos las acciones CRUD estándar. Esto es debido a que Authlogic se inyecta automáticamente en el modelo, y por lo tanto no nos tenemos que preocupar en absoluto de nada que tenga que ver con lógica que hay detrás de registrar un usuario. Es más, tampoco es necesario preocuparnos de encriptar la contraseña antes de almacenarla en la base de datos. Authlogic se encarga de todo. Y si lo que buscamos es un poco más avanzado, Authlogic es muy fácil de configurar y extender (ver la documentación).

9- Próximos Pasos

La gente de BinaryLogic incluye una lista de próximos pasos que pueden o no ser implementados. Todos remiten a una sección en particular dentro de la documentación de Authlogic. Aquí la incluyo traducida:

1. Querés usar otro algoritmo de encriptación, como BCrypt? Ver Authlogic::ActsAsAuthentic::Password::Config
2. Migrando de autenticación REST? Ver Authlogic::ActsAsAuthentic::RestfulAuthentication::Config
3. Querés que las sesiones expiren automáticamente después de un período de inactividad? Ver Authlogic::Session::Timeout
4. Necesitás restringir tus sesiones a una cuenta o modelo en particular? Ver Authlogic::AuthenticatesMany
5. Necesitás muchos tipos diferentes de sesiones? Ver Authlogic::Session::Id
6. Querés permitir que los usuarios reestablezcan sus contraseñas o confirmen su subscripción? Utilize una clave de expiración automática. Ver Authlogic::ActsAsAuthentic::PerishableToken
7. Querés dar acceso privado a una API o canal RSS? Utilice autenticación básica por HTTP o por parámetros. Ver Authlogic::Session::HttpAuth o Authlogic::Session::Params
8. Necesitás ayuda con tus pruebas? Consulta Authlogic::TestCase

Créditos

Este tutorial está estructuralmente basado en el tutorial oficial de Authlogic (en inglés). Mucho del código lo extraje de allí directamente, aunque me tomé libertades en cuanto a su presentación y en algunos casos le cambié en formas que me parecieron más convenientes.

Si este tutorial fue de provecho, no dudes en comentar! Lo mismo si encontraste errores o quisieras dar alguna sugerencia.

También podés subscribirte al feed para mantenerte al tanto de los artículos más frescos.

En poco tiempo pudimos detectar el origen del problema: un layout en el lado del administrador que mostraba unos 15 links. El administrador tenía permisos asignados a su usuario, de modo que si no tenía permiso para acceder a cierta sección, el link no se mostraba. El layout hacía un query a la base de datos para determinar los permisos para cada link! El código original era algo como lo siguiente:

# app/views/layouts/admin.html.erb
<% if User.find(session['user_id']).permissions.include?(Permission.find(ACCESS_PRODUCTS)) %>
   <li><%= link_to 'Products', admin_products_path %></li>
<% end %>
# ... y esto se repetía 20 veces, una por cada link.

En la condición anterior sólamente se ejecutan 3 queries en la base de datos: una para buscar el usuario, otra para buscar el permiso ACCESS_PRODUCTS, y otra para ver si el usuario tiene ese permiso. Eso acababa generando 60 queries por los 20 links que había en el menú.

Lo que hicimos para mejorarlo:
1) Cargar al usuario, juntamente con sus condiciones, en un sólo query.
2) Utilizar otro método para saber si el usuario tiene o no cierto permiso.

Lo importante de este caso no es analizar la implementación de la funcionalidad de permisos, ni la de usuarios; definitivamente se puede utilizar un acercamiento más efectivo a este problema. Por esta razón, aprovecho para recomendar los plugins authlogic y lockdown, que solucionan muy elegante y eficientemente todo lo que tiene que ver con la autenticación y permisos de usuarios.

El resultado:

# en un before_filter del controlador
@current_user = User.find(session['user_id'], :include => :permissions)

# app/views/layouts/admin.html.erb
<% if @current_user.permissions.exists?(ACCESS_PRODUCTS) %>
   <li><%= link_to 'Products', admin_products_path %></li>
<% end %>

Esta solución hace un sólo query a la base de datos antes de cargar el layout. La técnica se conoce en inglés como Eager Loading, que significa algo como “Carga Entusiasta” (de los datos pertenecientes a una relación). Lo que logramos es que el usuario y los permisos se carguen al mismo tiempo utilizando un JOIN en la llamada SQL. Una vez en memoria, toma poco y nada comprobar si existe un permiso en particular para determinado link.

El tiempo de respuesta mejoró en un 20%, y se hicieron 59 queries menos a la base de datos.

El código en nuestro modelo Mailer, que llamamos mailer.rb:

  # app/models/mailer.rb

  def photo(photo, attachment_data)
    subject       "New Photo from #{photo.name}"
    body          :photo => photo
    recipients    "destinatario@host.com"
    from          "remitente@host.com"
    sent_on       Time.now

    attachment :content_type => photo.content_type,
               :filename => "photo.jpg",
               :body => attachment_data.read if photo.respond_to?(:content_type)
  end

El campo photo es simplemente uno de nuestros modelos, y tiene información extra sobre la imagen.

El parámetro más importante aquí es attachment_data, que en la vista debe ser un campo file_field. Aquí vemos un ejemplo en la línea 3 del siguiente extracto de la vista:

<!-- ... (código) ... -->
<div class="form-row">
  <%= label :file, :uploaded_data, "Upload your photo <span>(JPG or GIF format, 1MB max)</span>" %>
  <%= file_field :file, :uploaded_data %></div>
</div>
<!-- ... (más código)... -->

La documentación en inglés es muy escasa. Creo que probablemente PaperClip sea una mejor opción para adjuntar archivos a un modelo, pero indiferentemente de qué gem o plugin se utilize, la lógica dentro del Mailer es muy similar:

:content_type => Debe reflejar el tipo de contenido del archivo adjunto. En este caso, un ejemplo puede ser “image/jpeg”.

:filename => El nombre de archivo para el archivo adjunto.

:body => El contenido del archivo. Aquí utilizamos el método read, que devuelve el contenido del archivo subido por el usuario, listo para ser adjunto, pero otra forma de hacerlo es utilizando File.read("ruta/al/archivo.pdf") o simplemente utilizando un método, como generate_pdf().

Es posible también mandar emails con múltiples archivos adjuntos, pero no lo probé. Según algunos autores (en inglés), basta con llamar más de una vez al método attachment dentro de mailer.rb.

Problema

Supongamos, como caso de estudio, que creamos un modelo User y su controlador, UsersController. Este controlador normalmente lo ubicamos en app/controllers, y sus acciones REST se encargarían de mostrarle al usuario su Perfil (acción show), un formulario para editar sus datos (acción edit), un formulario de registro (acción new), etc. Sin embargo, también queremos agregar otro controlador que se encargue de las acciones que pueda ejecutar el administrador del sitio: ver la lista de usuarios, editar sus campos, eliminar usuarios, etc. Para esto tambien queremos usar las acciones REST predeterminadas (index, edit, destroy, etc).

En casos como estos es fácil caer en la tentación de crear otro controlador llamado UsersAdminController (o AdminUsersController). El problema de esto es que no es muy limpio, las rutas van a ser más difíciles de configurar, y podemos acabar con decenas de controladores difíciles de encontrar en el directorio app/contollers. Si no identificamos este problema a tiempo (idealmente antes de empezar a programar), en poco tiempo nos encontraremos con que tenemos controladores organizados al estilo Users + UsersAdmin, Books + BooksAdmin, Photos + PhotosAdmin, etc.

Solución

La solución es extremadamente simple y efectiva: utilizar namespaces. Teniendo este caso de estudio en mente, por ejemplo, podemos crear nuestra aplicación de la siguiente forma:

1) En la consola ruby:

script/generate controller 'admin/users' index new create edit update destroy

Esto genera el siguiente controlador con las acciones especificadas ya definidas:
app/controllers/admin/users_controller.rb

2) Luego, editamos routes.rb para crear el namespace admin y los recursos users dentro de él, lo que nos dará direcciones del tipo localhost/admin/users. Como queremos administrar muchos usuarios, y no sólo uno, creamos resources (en plural).

# config/routes.rb
#...
map.namespace :admin do |admin|
  admin.resources :users
end

Esto también genera las rutas REST correspondientes, como por ejemplo admin_users_path (“admin/users“), new_admin_user_path (“admin/users/new“), etc.

3) Dentro del controlador podemos agregar el código que tenga que ver con la administración de usuarios utilizando un modelo Users.

4) Ahora podemos crear un controlador con el mismo nombre pero ubicado en “app/controllers“, para adminitrar la creación de cuentas, actualización de la información, etc., del lado del cliente. Aquí queremos administrar a un sólo usuario, así que utilizamos map.resource (singular).

# config/routes.rb
#...
map.namespace :admin do |admin|
  # controlado por "controllers/admin/users_controller.rb"
  admin.resources :users
end

# controlado por "controllers/users_controller.rb"
map.resource :user

5) Listo! Ahora es posible administrar los usuarios del sitio utilizando ejemplo.com/admin/users y además permitir a cada uno de ellos acceder a sus cuentas individuales a través de ejemplo.com/user (y sus rutas derivadas).

No tuve que buscar mucho antes de encontrar un artículo que utiliza una técnica ingeniosa conocida como Evil Twin (“Gemelo Malvado” en inglés) para lograr lo que necesitaba. Con algunos cambios, pude adaptar el código a mis necesidades y hacerlo más flexible (por lo menos para mi gusto). Mis objetivos eran dos:

1) Devolver un solo mensaje de error si ningún archivo era seleccionado por el usuario.
2) Tener la opción de personalizar los mensajes de error cuando el usuario seleccionaba un archivo inválido.

Para crear este plugin primero hay que crear una carpeta en vendor/plugins que se llame attachment_fu_hack. No es estrictamente necesario que tenga ese mismo nombre, pero lo que sí importa es que el contenido sea leído después del plugin attachment_fu, porque lo que queremos es extender su funcionalidad. La razón por la cual agregamos _hack al final del nombre para nuestra nueva carpeta es porque Rails carga los plugins en orden alfabético, leyendo primero el plugin attachment_fu y luego nuestro código.

Luego creamos el archivo init.rb. Este archivo sí debe ser llamado de esa forma, porque es el inicializador de nuestro “plugin”. A partir de ahora voy a incluir el código que va dentro de init.rb en secuencia, pero lo separo en partes para poder explicarlo. Pueden ver el código completo de init.rb en mi subdominio de PasteBin. También está disponible para descargar en versión PDF.

klass = Technoweenie::AttachmentFu::ClassMethods
klass.module_eval do
  def validates_as_attachment(error_messages = {})
    validate :uploaded_data_is_present
    validates_presence_of :size, :content_type, :filename, :if => :uploaded_data?
    validate do |this|
      this.attachment_attributes_valid?(error_messages)
    end
  end
end

Línea 01: asignamos a la variable klass los métodos de clase (dentro de ClassMethods) de attachment_fu. Luego utilizamos el método module_eval para “abrir” la clase ClassMethods y sobrecargar el método validates_as_attachment, que es el que buscamos mejorar.

Línea 03: agregamos al método un parámetro opcional, error_messages. En las siguientes líneas utilizamos el mismo código del artículo citado arriba.

Línea 06: aquí comienzan los cambios. Llamamos al método validate utilizando un bloque para poder pasar parámetros a la función attachment_attributes_valid?, que ya veremos en un momento.

methods_klass = Technoweenie::AttachmentFu::InstanceMethods
methods_klass.module_eval do
  def uploaded_data? # llamado por el método validates_as_attachment de arriba
    return false unless filename # filename debería ser nil si no hay datos
    true
  end

  # Valida los atributos "size" y "content_type" de acuerdo a la configuración
  # del modelo.
  def attachment_attributes_valid?(error_messages) #recibe mensajes como parámetro
    @attachment_error_messages = error_messages # guarda los mensajes
    if uploaded_data?
      [:size, :content_type].each do |attr_name|
        enum = attachment_options[attr_name] # valores posibles para el atributo
        errors.add_to_base attachment_error_message_for(attr_name) unless enum.nil? || enum.include?(send(attr_name))
      end
    end
  end

  def uploaded_data_is_present # valida si hay datos subidos o no
    unless uploaded_data? # si no hay datos...
      errors.add_to_base("Debe seleccionar una imagen para subir.") #...agrega el error al objeto
    end
  end

  # Devuelve el mensaje de error para un atributo
  def attachment_error_message_for(attribute)
    @attachment_error_messages[attribute] || ActiveRecord::Errors.default_error_messages[:inclusion]
  end
end

Línea 13: ejecutamos el bloque para cada uno de los atributos en el Array. En este caso sólo necesitaba validar size y content_type.

Línea 14: guardamos en enum la lista de valores posibles para el atributo que estamos validando.

Línea 15: si enum es nulo o no incluye al valor actual del atributo, agrega un error a la clase con la descripción devuelta por attachment_error_message_for.

Línea 19: esto logra nuestro principal objetivo, que es devolver un solo mensaje de error si el usuario se olvidó de subir un archivo.

Línea 27: devuelve el error definido para el atributo pasado como parámetro. Si no se encuentra uno, devuelve un error de inclusión estándar de ActiveRecord (“{{attribute}} is not in the list“). Este método es el que nos permite devolver errores customizados cuando el usuario sí sube un archivo pero es del tipo incorrecto o está fuera de los límites de tamaño establecidos.

Utilizar la nueva funcionalidad es muy fácil. En el modelo:

# app/models/photo.rb
class Photo < ActiveRecord::Base
 has_attachment # ... resto del código código
 # ...
 validates_as_attachment	{ # pasamos un Hash con los atributos como "keys"
     :size => "La imagen es demasiado grande", # y los mensajes de error
     :content_type => "Formato desconocido" }  # como "values"
end

Y vemos cómo ahora podemos pasarle los errores personalizados al método validates_as_attachment. Además, lo que es más importante, ahora attachment_fu devolverá un solo error cuando el usuario no suba el archivo que necesita el modelo.

Seguramente el código puede ser mejorado. Si a alguien se le ocurre alguna mejora o forma más eficiente de hacer lo mismo, por favor no duden en compartirlo en los comentarios!