ASCIIcasts - Full Episode Feed

Active Admin

Mon, 24 Oct 2011 08:21:47 +0000

Dans cet épisode, nous allons voir Active Admin. Cette gem vous permet d'ajouter facilement une interface d'administration à vos applications Rails. Elle crée de jolies pages d'administration et est très paramétrable. Vous pouvez jeter un œil à la démo live pour vous faire une idée.

Nous allons ajouter Active Admin à une application Rails existante. L'application que nous utiliserons est un simple système d'e-commerce contenant un certain nombre de produits, chacun ayant un prix et appartenant à une catégorie. Nous allons utiliser Active Admin pour créer un interface d'administration pour gérer nos produits.

Installer Active Admin

Active Admin est distribuée sous forme de gem et s'installe, comme d'habitude, grâce à une référence dans le Gemfile et à un appel à bundle. Notre application a été développée avec Rails 3.1, nous devons donc nous assurer qu'elle inclut bien sass-rails car Active Admin en dépend. Sous Rails 3.0, ce n'est pas un problème et nous n'avons pas besoin de l'inclure.

/Gemfile

gem 'activeadmin'

Une fois que Bundler a terminé, nous devons lancer un générateur pour ajouter les fichiers d'Active Admin à notre application. Ce générateur va nous fournir les instructions sur les réglages que nous allons devoir effectuer après son lancement. Nous devons ajouter l'option host à la configuration du Mailer dans l'environnement de développement, nous assurer que nous avons une URL root et que les messages flash notice et alert sont bien affichés dans le layout de l'application.

$ rails g active_admin:install
      invoke  devise
    generate    devise:install
      create    config/initializers/devise.rb
      create    config/locales/devise.en.yml

==================================================================

Some setup you must do manually if you haven't yet:

  1. Setup default url options for your specific environment. Here is an example of development environment:

       config.action_mailer.default_url_options = { :host => 'localhost:3000' }

     This is a required Rails configuration. In production it must be the actual host of your application

  2. Ensure you have defined root_url to *something* in your config/routes.rb.
     For example:

       root :to => "home#index"

  3. Ensure you have flash messages in app/views/layouts/application.html.erb. For example:

       <p class="notice"><%= notice %></p>
       <p class="alert"><%= alert %></p>

Nous avons déjà fait tout cela pour notre application, nous sommes donc prêts à continuer.

La commande crée également quelques migrations, nous allons donc les lancer maintenant.

$ rake db:migrate

Utiliser Active Admin

Si nous regardons la documentation d'Active Admin, nous allons voir que lorsque nous l'installons, elle crée un utilisateur ayant admin@example.com comme nom d'utilisateur et password comme mot de passe. Nous pouvons utiliser ces identifiants pour nous connecter (vous pouvez les configurer en éditant devise_create_admin_users.rb avant de lancer les migrations). Si nous visitons http://localhost:3000/admin, une fois le serveur Rails lancé, nous allons voir un formulaire de connexion via lequel nous pouvons nous connecter avec les identifiants vus précédemment.

Une fois que nous nous sommes connectés, nous allons être redirigés vers le tableau de bord d'Active Admin. Il n'y aura, cependant, pas grand chose à voir pour le moment.

Nous voulons gérer nos produits. Nous allons donc ajouter notre ressource Product dans Active Admin en lançant cette commande :

$ rails g active_admin:resource product
      create  app/admin/products.rb

Ce générateur va créer un fichier products.rb dans le dossier app/admin de notre application. Lorsque nous rafraichissons le tableau de bord, nous allons voir un lien “Products” ; si nous cliquons sur ce lien, nous allons être dirigés vers une page contenant tout ce dont nous avons besoin pour gérer nos produits.

Cette page a des options de tri et de filtrage des produits sur chaque attributs. Active Admin va même détecter la relation belongs_to avec Category et nous fournir un menu déroulant pour filtrer nos produits par catégorie. Cela fonctionne également lorsque nous créons un nouveau produit. Les catégories sont montrées sous forme de menu déroulant et les autres attributs seront saisis dans des champs correspondant à leur type.

Personnaliser ce comportement est très facile. Nous allons commencer par personnaliser la page d'index des produits et en réduire le nombre de colonnes affichées. Pour cela, nous allons modifier le fichier /app/admin/products.rb généré précédemment. Nous modifions la page d'index en surchargeant la méthode index. Cette méthode prend en paramètre un bloc. Dans ce dernier, nous spécifions les colonnes que nous voulons voir sur la page en appelant column.

/app/admin/products.rb

ActiveAdmin.register Product do
  index do
    column :name
    column :category
    column :released_at
    column :price
  end
end

Lorsque nous rechargeons la page des produits, nous allons voir les colonnes que nous avons choisies.

Notez que l'association Category a été détectée et que la bonne catégorie est affichée pour chaque produit.

Nous pouvons pousser plus loin cette personnalisation et changer le titre d'une colonne en passant un titre en premier argument de l'appel à column. Nous allons nous en servir pour modifier le titre de la colonne released_at.

/app/admin/products.rb

ActiveAdmin.register Product do
  index do
    column :name
    column :category
    column "Release Date", :released_at
    column :price
  end
end

Si nous voulons changer les valeurs d'une colonne, nous pouvons le faire en passant un bloc à column. Le champ price ne montre pas le symbole de monnaie mais nous pouvons changer cela pour que ça soit le cas. La méthode column peut prendre un bloc et, lorsqu'elle en reçoit un, lui passe la ressource courante, dans notre cas un Product. Ce que le bloc retourne est affiché comme valeur dans la colonne concernée. Nous avons accès aux helpers, nous pouvons donc utiliser number_to_currency pour afficher le prix correctement.

/app/admin/products.rb

ActiveAdmin.register Product do
  index do
    column :name
    column :category
    column "Release Date", :released_at
    column :price do |product|
      number_to_currency product.price, :unit => "&pound;"
    end
  end
end

Si nous rechargeons la page, nous allons voir le titre “Release Date” et chaque prix de produit sera affiché sous forme de valeur monétaire.

Personnaliser la valeur retournée par le champ price signifie que le champ n'est plus triable. Il nous manque également les liens de modification et de suppression de chaque produit. Nous allons donc corriger cela. Lorsque nous utilisons un bloc pour personnaliser une valeur, nous devons utiliser l'option :sortable pour préciser à Active Admin comment trier ce champ. Nous allons donc faire cela et ajouter un appel à default_actions pour retrouver les liens d'édition et de suppression.

/app/admin/products.rb

ActiveAdmin.register Product do
  index do
    column :name
    column :category
    column "Release Date", :released_at
    column :price, :sortable => :price do |product|
      number_to_currency product.price, :unit => "&pound;"
    end
    default_actions
  end
end

Le champ price est bien affiché sous forme monétaire mais il serait préférable que la valeur soit également alignée à droite. Nous pouvons changer cela dans les CSS mais pour que tout fonctionne, il nous faut un moyen de référencer une colonne en particulier. Active Admin fournit un moyen similaire à Markaby pour générer du HTML. Tout ce que nous avons à faire, c'est de passer une option :class pour donner à la balise une référence utilisable dans nos CSS.

/app/admin/products.rb

ActiveAdmin.register Product do
  index do
    column :name
    column :category
    column "Release Date", :released_at
    column :price, :sortable => :price do |product|
      div :class => "price" do
        number_to_currency product.price, :unit => "&pound;"
      end
    end
    default_actions
  end
end

Nous pouvons maintenant styliser cette colonne en modifiant le fichier active_admin.css.scss.

/app/assets/stylesheets/active_admin.css.scss

// Active Admin CSS Styles
@import "active_admin/mixins";
@import "active_admin/base";

// To customize the Active Admin interfaces, add your
// styles here:
.price {
  text-align :right;
}

La colonne price est maintenant alignée correctement.

Les Scopes

Les scopes sont une autre fonctionnalité intéressante d'Active Admin. Ils agissent comme des filtres pré-existants et leur création consiste en deux étapes. Tout d'abord, nous ajoutons un appel à scope, dans le fichier de configuration Active Admin pour nos produits, en lui passant en paramètre le nom d'un scope.

/app/admin/products.rb

ActiveAdmin.register Product do
  scope :unreleased
  index do
    column :name
    column :category
    column "Release Date", :released_at
    column :price, :sortable => :price do |product|
      div :class => "price" do
        number_to_currency product.price, :unit => "&pound;"
      end
    end
    default_actions
  end
end

Nous devons ensuite écrire ce scope dans le modèle Product.

/app/models/product.rb

class Product < ActiveRecord::Base
  belongs_to :category
  scope :unreleased, where(:released_at => nil)
end

Si nous rechargeons la page des produits, nous voyons le scope listé. Lorsque nous cliquons sur celui-ci, la liste des produits est filtrée à partir de ce scope.

Personnaliser le Tableau de Bord

Nous allons maintenant voir la personnalisation du Tableau de Bord. Il est vide par défaut. Nous allons donc le modifier pour faire en sorte qu'il affiche une liste des produits les plus récents. Cela se fait dans le fichier /app/admin/dashboards.rb. Les commentaires de ce fichier sont une documentation utile, ils expliquent les différentes manières de personnaliser le tableau de bord.

Pour ajouter une section au tableau de bord, nous utilisons la méthode section. Nous voulons lister les produits les plus récents dans un tableau et nous pouvons le faire en utilisant la méthode table_for. Dans son bloc, nous précisons les colonnes que nous voulons afficher grâce à column, comme nous l'avons fait pour la page des produits.

/app/admin/dashboards.rb

ActiveAdmin::Dashboards.build do
  section "Recent Products" do
    table_for Product.order("released_at desc").limit(5) do
      column :name
      column :released_at
    end
    strong { link_to "View All Products", admin_products_path }
  end
end

Lorsque nous rechargeons la page, nous voyons maintenant les cinq derniers produits ainsi qu'un lien pointant vers la page de tous les produits.

La page serait plus pratique si chaque produit de la liste était un lien vers la page d'administration de ce produit. Nous pouvons faire cela en passant à nouveau un bloc à l'appel de column, comme nous l'avons précédemment fait pour la colonne price.

/app/admin/dashboards.rb

ActiveAdmin::Dashboards.build do
  section "Recent Products" do
    table_for Product.order("released_at desc").limit(5) do
      column :name do |product|
        link_to product.title, admin_product_path(product)
      end
      column :released_at
    end
    strong { link_to "View All Products", admin_products_path }
  end
end

Il existe un moyen plus court de définir le chemin dans link_to. Au lieu d'utiliser admin_product_path(product), nous pouvons passer un tableau ayant un symbole comme première valeur et le produit comme seconde, comme ceci :

link_to product.title, [:admin, product]

Si nous rechargeons le tableau de bord, nous allons voir que chaque titre de produit est un lien. Lorsque nous cliquons sur l'un d'eux, nous somme dirigés vers la page d'administration du produit concerné.

Corriger les CSS

Un problème existe lorsque nous utilisons Active Admin avec Rails 3.1. Nous pouvons le voir en allant sur une page de notre application autre que l'administration.

La page ne ressemble plus vraiment à ce qu'elle était avant car les CSS d'Active Admin sont incluses sur toutes les pages. Par défaut, Rails 3.1 inclut toutes les CSS en raison de la ligne require_tree . dans le manifest application.css. Ce n'est pas ce que nous voulons et il est de toute manière de bon ton de supprimer cette ligne pour nous donner plus de contrôle sur les CSS de notre application. Nous n'avons qu'une seule autre CSS dans l'application principale, nous allons donc remplacer require_tree . par require products.

/app/assets/stylesheets/application.css

/*
 * This is a manifest file that'll automatically include all the stylesheets available in this directory
 * and any sub-directories. You're free to add application-wide styles to this file and they'll appear at
 * the top of the compiled file, but it's generally better to create a new file per style scope.
 *= require_self
 *= require products
*/

/* Rest of file omitted */

Une solution encore meilleure est de passer à la commande import de SASS. Nous pouvons transformer le principal fichier CSS de notre application en lui ajoutant une extension .scss. Nous pouvons ensuite supprimer le manifest au début du fichier (la partie du fichier que vous pouvez voir ci-dessus) et ajouter la commande import en fin de fichier.

/app/assets/stylesheets/application.css.scss

/* Styles omitted */

@import "products";

Lorsque nous rechargeons la page d'accueil, seules les CSS adéquates sont incluses et la page a un rendu correct.

Configuration Globale

Active Admin a un autre fichier de configuration dans le dossier /config/initializers et nous terminerons cet épisode par un coup d'œil sur celui-ci. Le fichier contient un grand nombre d'options de configuration, la plupart étant commentée. Une qui ne l'est pas est le titre de l'interface d'administration et nous allons le changer.

/config/initializers/active_admin.rb

ActiveAdmin.setup do |config|

  # == Site Title
  #
  # Set the title that is displayed on the main layout
  # for each of the active admin pages.
  #
  config.site_title = "Eifion's Store"

  # Other configuration options omitted.
end

Nous devons redémarrer le serveur pour voir le changement pris en compte.

C'est tout pour cet épisode. Active Admin regorge de fonctionnalités que nous n'avons pas vues ici, nous vous encourageons donc à consulter la documentation pour voir tout ce dont elle est capable. Nous pouvons personnaliser le rendu et les fonctionnalités de chaque page d'administration pour les adapter à nos besoins et cela en fait une puissante solution d'administration pour Rails.

Authentification avec Sorcery

Sun, 16 Oct 2011 22:14:01 +0000

Dans l'épisode 250 [regarder, lire], nous avons ajouté, from scratch, un mécanisme d'authentification dans une application Rails. Si vous préférez utiliser une solution tierce, il existe bon nombre de gems répondant à ce besoin. Dans cet épisode, nous allons jeter un œil sur celle nommée Sorcery.

Sorcery est une solution simple. Elle ne propose qu'une vingtaine de méthodes mais cela suffit amplement pour répondre à notre besoin. Malgré sa simplicité, elle est très complète et modulaire, nous pouvons donc choisir les parties que nous voulons utiliser, la réinitialisation de mot de passe, par exemple. Sorcery fonctionne à un niveau plus bas que les autres solutions d'authentification et nous laisse le soin d'écrire les couches contrôleurs et vues. Dans cet épisode, nous allons l'utiliser pour ajouter un mécanisme d'authentification à une application existante.

Démarrer

L'application avec laquelle nous allons travailler est très simple. Elle a une page d'accueil contenant un lien vers une page “secrète”. La page secrète est, pour le moment, visible par tout le monde. Nous voulons en restreindre l'accès aux utilisateurs connectés. Pour ce faire, nous devons ajouter une couche d'authentification à l'application et c'est la que Sorcery entre en jeu.

Sorcery est fournie sous forme de gem et s'installe de façon classique, Gemfile et bundle.

/Gemfile

gem 'sorcery'

Une fois cela fait, nous devons lancer la commande suivante pour créer l'initializer de Sorcery (nous reviendrons dessus plus loin).

$ rake sorcery:bootstrap

Nous allons ensuite générer une migration sorcery_migration. Elle va nous servir à choisir les modules de Sorcery que nous voulons inclure. Nous allons ajouter le module core, qui permet une authentification par mot de passe, et le module remember_me. Pour une liste complète des modules, consultez le README de Sorcery.

$ rails g sorcery_migration core remember_me
      create  db/migrate/20110914221626_sorcery_core.rb
      create  db/migrate/20110914221627_sorcery_remember_me.rb

La commande crée un certain nombre de fichiers de migration en fonction des modules choisis. Si nous regardons la migration sorcery_core, nous allons voir les attributs ajoutés à la table users.

/db/migrate/20110914221626_sorcery_core.rb

class SorceryCore < ActiveRecord::Migration
  def self.up
    create_table :users do |t|
      t.string :username,         :null => false  
      t.string :email,            :default => nil 
      t.string :crypted_password, :default => nil
      t.string :salt,             :default => nil
      t.timestamps
    end
  end

  def self.down
    drop_table :users
  end
end

Par défaut, la migration crée un champ username. Nous n'en avons pas besoin, nous allons donc commenter cette ligne.

/db/migrate/20110914221626_sorcery_core.rb

class SorceryCore < ActiveRecord::Migration
  def self.up
    create_table :users do |t|
      # t.string :username,         :null => false
      t.string :email,            :default => nil
      t.string :crypted_password, :default => nil
      t.string :salt,             :default => nil
      t.timestamps
    end
  end
end

Nous allons également devoir configurer Sorcery pour qu'il utilise le champs email plutôt que le champ username. Cela se fait en modifiant l'initializer de Sorcery. Au début de ce fichier, nous devons spécifier les modules que nous voulons activer. En dehors du module core, nous n'utilisons que le module remember_me, c'est donc le seul que nous devons ajouter.

/config/initializers/sorcery.rb

# The first thing you need to configure is which modules you need in your app.
# The default is nothing which will include only core features (password encryption, login/logout).
# Available submodules are: :user_activation, :http_basic_auth, :remember_me, 
# :reset_password, :session_timeout, :brute_force_protection, :activity_logging, :external
Rails.application.config.sorcery.submodules = [:remember_me]

# Rest of file omitted.

Il y a d'autres options de configuration que nous pouvons utiliser. Elles sont toutes documentées dans le fichier. Nous n'avons pas besoin de modifier la plupart d'entre elles. La seule que nous devons changer est username_attribute_name. Nous allons lui donner comme valeur :email afin de spécifier que c'est ce champ qui sera utilisé pour identifier les utilisateurs.

/config/initializers/sorcery.rb

config.user_config do |user|
  # -- core --
  user.username_attribute_name = :email
  # change default username
  # attribute, for example,
  # to use :email as the login.

  # Other options omitted.
end
# This line must come after the 'user config' block.
config.user_class = "User"
# define which model authenticates
# with sorcery.
end

À la fin du fichier, on peut trouver un élément de configuration qui permet de spécifier le nom du modèle utilisé par Sorcery pour l'authentification (User par défaut). Notre application n'a pas encore de modèle User, nous allons donc le créer. Nous avons déjà un fichier de migration pour spécifier les champs de User, nous allons donc dire à Rails de ne pas générer de migration pour ce modèle.

$ rails g model user --skip-migration

Pour activer Sorcery dans le modèle User, nous avons juste une ligne de code à ajouter.

/app/models/user.rb

class User < ActiveRecord::Base
  authenticates_with_sorcery!
end

Cela ajoute au modèle User un certain nombre de méthodes pour gérer l'authentification. Les attributs ne sont, cependant, ni validés ni protégés ; c'est à nous d'écrire ce code.

/app/models/user.rb

class User < ActiveRecord::Base
  authenticates_with_sorcery!

  attr_accessible :email, :password, :password_confirmation

  validates_confirmation_of :password
  validates_presence_of :password, :on => :create
  validates_presence_of :email
  validates_uniqueness_of :email
end

Il est maintenant temps de lancer les migrations pour que la table users soit crée.

$ rake db:migrate

Ajouter les Contrôleurs et les Vues

Maintenant que nous avons le modèle User, nous allons générer quelques contrôleurs pour l'accompagner. Nous allons commencer par UsersController pour gérer le processus d'inscription.

$ rails g controller users new

Nous allons également avoir besoin de SessionsController pour gérer les connexions.

$ rails g controller sessions new

Cela ressemble beaucoup à ce que nous avons fait dans l'épisode 250, sur l'authentification from scratch, nous allons donc passer rapidement sur ce sujet. UsersController va être relativement standard, construire un nouvel utilisateur dans l'action new et en créer un basé sur les informations fournies dans l'action create.

/app/controllers/users_controller.rb

class UsersController < ApplicationController
  def new
    @user = User.new
  end
  
  def create
    @user = User.new(params[:user])
    if @user.save
      redirect_to root_url, :notice => "Signed up!"
    else
      render :new
    end
  end
end

Le template new va être assez standard également, un formulaire permettant de créer un nouvel utilisateur avec les champs email, password et password_confirmation ainsi qu'un peu de code pour afficher les erreurs de validation.

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

<h1>Sign Up</h1>

<%= form_for @user do |f| %>
  <% if @user.errors.any? %>
    <div class="error_messages">
      <h2>Form is invalid</h2>
      <ul>
        <% for message in @user.errors.full_messages %>
          <li><%= message %></li>
        <% end %>
      </ul>
    </div>
  <% end %>
  <div class="field">
    <%= f.label :email %>
    <%= f.text_field :email %>
  </div>
  <div class="field">
    <%= f.label :password %>
    <%= f.password_field :password %>
  </div>
  <div class="field">
    <%= f.label :password_confirmation %>
    <%= f.password_field :password_confirmation %>
  </div>
  <div class="actions"><%= f.submit %></div>
<% end %>

SessionsController est bien plus intéressant. Nous avons une action new mais celle-ci ne nécessite aucun code, nous allons donc voir son template. Ici, nous allons avoir besoin d'un simple formulaire de connexion avec des champs texte pour email et password, et une checkbox pour le champ remember_me.

/app/views/sessions/new.html.erb

<h1>Log in</h1>

<%= form_tag sessions_path do %>
  <div class="field">
    <%= label_tag :email %>
    <%= text_field_tag :email, params[:email] %>
  </div>
  <div class="field">
    <%= label_tag :password %>
    <%= password_field_tag :password %>
  </div>
  <div class="field">
    <%= check_box_tag :remember_me, 1, params[:remember_me] %>
    <%= label_tag :remember_me %>
  </div>
  <div class="actions"><%= submit_tag "Log in" %></div>
<% end %>

Nous devons écrire une action create pour gérer le formulaire de connexion. Sorcery fournit une méthode appelée login qui peut prendre trois paramètres, un nom d'utilisateur ou une adresse email, un mot de passe et la valeur du champ remember_me. Cette méthode va effectuer l'authentification et retourner un User en cas de succès. Nous pouvons donc vérifier son retour et rediriger vers la page d'accueil si un utilisateur est trouvé. Dans le cas contraire, nous allons afficher un message flash et afficher de nouveau le formulaire de connexion.

/app/views/controllers/sessions_controller.rb

class SessionsController < ApplicationController
  def new
  end
  
  def create
    user = login(params[:email], params[:password], ↵
      params[:remember_me])
    if user
      redirect_back_or_to root_url, :notice => "Logged in!"
    else
      flash.now.alert = "Email or password was invalid."
    end
  end
end

Au lieu d'utiliser redirect_to pour rediriger sur la page d'accueil lorsqu'un utilisateur est trouvé, nous allons utiliser une méthode fournie par Sorcery et appelée redirect_back_or_to. Son comportement est similaire à redirect_to mais si une URL est stockée par Sorcery, la redirection se fera vers cette URL plutôt que vers celle spécifiée dans le code. Ce fonctionnement est bien pratique car cela signifie que si un utilisateur tente d'accéder à une certaine page et qu'il est redirigé vers le formulaire de connexion, il sera redirigé vers cette page un fois connecté.

Il nous reste encore à fournir un moyen de se déconnecter. Nous allons donc ajouter une action destroy au contrôleur. Sorcery fournit une méthode logout et c'est tout ce dont nous avons besoin pour déconnecter un utilisateur. Une fois l'utilisateur déconnecter, nous allons le rediriger vers la page d'accueil.

/app/views/controllers/sessions_controller.rb

def destroy
  logout
  redirect_to root_url, :notice => "Logged out!"
end

Nous allons ensuite aller dans la configuration de nos routes et remplacer les actions générées par défaut par ceci :

/config/routes.rb

Auth::Application.routes.draw do
  get "logout" => "sessions#destroy", :as => "logout"
  get "login" => "sessions#new", :as => "login"
  get "signup" => "users#new", :as => "signup"
  resources :users
  resources :sessions
  get "secret" => "home#secret", :as => "secret"
  root :to => "home#index"
end

Nous avons à présent différentes routes nommées et deux ressources nous permettant de gérer toute la couche authentification.

Maintenant que nous avons ces nouvelles pages, nous allons avoir besoin de quelques liens pour que les utilisateurs puissent y accéder. Nous allons les ajouter au layout afin de les rendre disponibles sur toutes les pages. Nous pouvons utiliser la méthode current_user pour vérifier si l'utilisateur est connecté ou non. Si c'est le cas, nous allons afficher son adresse email suivie d'un lien “Log out”. Si, au contraire, il n'est pas connecté, nous allons afficher les liens d'inscription et de connexion.

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

<!DOCTYPE html>
<html>
<head>
  <title>Auth Example</title>
  <%= stylesheet_link_tag    "application" %>
  <%= javascript_include_tag "application" %>
  <%= csrf_meta_tags %>
</head>
<body class="<%= params[:controller] %>">
  <div id="container">
    <div class="user_nav">
      <% if current_user %>
        Logged in as <%= current_user.email %>.
        <%= link_to "Log out", logout_path %>
      <% else %>
        <%= link_to "Sign up", signup_path %> or
        <%= link_to "Log in", login_path  %>.
      <% end %>
    </div>
    <% flash.each do |name, msg| %>
      <%= content_tag :div, msg, :id => "flash_#{name}" %>
    <% end %>
    <%= yield %>
  </div>
</body>
</html>

Nous sommes prêts à tester notre site. Si nous nous rendons sur la page d'accueil, nous allons maintenant voir les liens “Sign up” et “Log in”.

Si nous cliquons sur “Sign up”, nous allons voir le formulaire d'inscription et nous pouvons nous inscrire sur le site. Nous pouvons ensuite cliquer sur “Log in” et nous connecter avec nos identifiants.

Autorisation

Maintenant que nous sommes connectés sur le site, nous pouvons visiter la page secrète. Cependant, si nous nous déconnectons et tentons de visiter la page, nous pouvons toujours la voir. Nous devons ajouter un mécanisme d'autorisation pour restreindre l'accès à la page aux utilisateurs connectés.

La page secrète est une action du contrôleur HomeController. Nous pouvons utiliser un before_filter fournit par Sorcery, require_login, pour limiter l'accès aux actions. Nous allons l'utiliser pour protéger la page secrète.

/app/controllers/home_controller.rb

class HomeController < ApplicationController
  before_filter :require_login, :only => :secret

  def index
  end

  def secret
  end
end

Lorsque ce filtre est déclenché, Sorcery appelle sa méthode not_authenticated. Nous pouvons surcharger cette méthode dans ApplicationController pour contrôler ce qu'il se passe lorsque l'autorisation échoue. Nous allons rediriger vers la page de connexion et afficher un message d'alerte.

/app/controllers/application_controller.rb

class ApplicationController < ActionController::Base
  protect_from_forgery
  
  private
  def not_authenticated
    redirect_to login_url, :alert => "First log in to view ↵
    this page."
  end
  
end

Si nous essayons de consulter la page secrète sans être connectés, nous allons être redirigés vers la page de connexion et le message d'alerte sera affiché.

Lorsque nous nous connectons, nous sommes redirigés vers la page secrète, Sorcery se souvenant de la page à laquelle nous tentions d'accéder avant d'être redirigés.

C'est tout pour cet épisode sur Sorcery. De nombreuses fonctionnalités n'ont pas été vues ici, pour en savoir plus, rendez-vous dans la documentation. Si vous cherchez une solution d'authentification fonctionnant à un niveau relativement bas, Sorcery vaut la peine d'y jeter un œil.

Migrer vers Rails 3.1

Sun, 16 Oct 2011 22:10:38 +0000

Rails 3.1 est enfin sorti. On trouve un bon aperçu des nouvelles fonctionnalités dans les Release Notes sur le site RailsGuides. Certaines ont déjà été abordées sur Railscasts ainsi que sur Asciicasts. Dans cet épisode, nous allons nous concentrer sur la migration de Rails 3.0 à Rails 3.1 et nous utiliserons le site Railscasts pour la démonstration.

Préparer Le Site

Avant de passer le site sous Rails 3.1, nous allons avoir besoin d'effectuer quelques opérations de préparation. Si le site n'utilise pas encore la dernière version de Rails 3.0 (3.0.10 actuellement), nous allons devoir le mettre à jour. Nous pouvons le faire en changeant la version dans le Gemfile et en lançant bundle.

/Gemfile

gem "rails", "3.0.10"

Nous allons ensuite lancer la suite de tests de l'application afin de s'assurer qu'elle passe toujours et que nous n'avons pas d'erreur de dépreciation. Si nous en rencontrons, nous devons les corriger avant de continuer. Le code de Railscasts passe, nous pouvons donc passer à la migration.

Migration

Nous sommes maintenant prêts à migrer le site. Nous allons le faire dans un nouvelle branche Git que nous appellerons rails31.

$ git checkout -b rails31

Migrer vers Rails 3.1 est plutôt simple. Nous avons juste besoin d'aller dans le Gemfile de notre application et de changer à nouveau la version de Rails pour mettre le numéro de la dernière (actuellement 3.1.0).

/Gemfile

gem "rails", "3.1.0"

Nous pouvons maintenant lancer bundle update pour installer la nouvelle version. Le seul autre changement que nous devons opérer a lieu dans le fichier de configuration development.rb. Nous devons supprimer ou commenter la ligne suivante.

/config/development.rb

# config.action_view.debug_rjs = true

Si nous lançons nos tests à nouveau, nous allons voir qu'ils passent toujours. Nous pouvons même démarrer le serveur Rails et tester dans notre navigateur.

Modifier notre application pour qu'elle utilise l'Asset Pipeline

L'asset pipeline est une des plus importantes fonctionnalités de Rails 3.1. Toutefois, les images, CSS et JavaScripts de notre application se situent toujours dans le dossier /public de notre application, nous n'en tirons donc pas avantage. L'asset pipeline est totalement optionnel et n'est pas actif tant que nous ne le demandons pas. De cette manière, si nous ne sommes pas sûrs de vouloir l'utiliser, cela ne nous empêche pas de migrer vers Rails 3.1. Étant donné la facilité de migration, il y a très peu de raisons de ne pas sauter le pas.

Si nous voulons utiliser l'asset pipeline, nous devons l'activer. Pour ce faire, nous devons ajouter les lignes suivantes à notre Gemfile (extraites du Gemfile généré par Rails 3.1).

/Gemfile

# Gems used only for assets and not required
# in production environments by default.
group :assets do
  gem 'sass-rails', " ~> 3.1.0"
  gem 'coffee-rails', " ~> 3.1.0"
  gem 'uglifier'
end

gem 'jquery-rails'

Ce code crée un groupe assets et y place quelques gems relatives aux assets. On y trouve la gem jquery-rails, nous pourrons donc utiliser jQuery (si vous préférez Prototype, vous pouvez utiliser la gem prototype-rails gem). Nous allons également devoir modifier le fichier /config/application.rb pour remplacer ce code :

/config/application.rb

# If you have a Gemfile, require the gems listed there, including any gems
# you've limited to :test, :development, or :production.
Bundler.require(:default, Rails.env) if defined?(Bundler)

par celui-ci :

/config/application.rb

if defined?(Bundler)
  # If you precompile assets before deploying to production, 
    use this line
  Bundler.require *Rails.groups(:assets => %w(development test))
  # If you want your assets lazily compiled in production, 
    use this line
  # Bundler.require(:default, :assets, Rails.env)
end

Ce code ajoute le groupe assets aux groupes requis par Bundler. Nous allons de plus devoir activer l'asset pipeline dans ce fichier. Cela se fait en ajoutant les lignes suivantes dans la classe Application :

/config/application.rb

# Enable the asset pipeline
config.assets.enabled = true

# Version of your assets, change this if you want to expire all your assets
config.assets.version = '1.0'

Ce code active l'asset pipeline et lui donne un numéro de version. Ce numéro peut être changé pour expirer les assets.

Il nous faut également changer la configuration de chaque environnement. Nous allons commencer par development.rb. Nous avons deux changements à faire de façon à ce que les assets ne soient pas compressés et pour activer le debug des assets.

/config/environments/development.rb

  # Do not compress assets
  config.assets.compress = false
  
  # Expands the lines which load the assets
  config.assets.debug = true

Passons à production.rb.

/config/environments/production.rb

# Compress JavaScript and CSS
config.assets.compress = true
   
# Don't fallback to assets pipeline
config.assets.compile = false
   
# Generate digests for assets URLs
config.assets.digest = true

En mode production, nous voulons voir les assets compressés mais nous mettons compile à false car nous ne voulons pas que l'asset pipeline soit appelé alors que nous allons précompiler les assets. Nous mettons digest à true de façon à ce que les URLs des assets aient une fingerprint. Bien sûr, nous pouvons configurer tout cela pour l'adapter aux besoins de notre application en production.

Enfin, nous allons modifier l'environnement de test. Ici nous précisons que les fichiers statiques doivent être servis et mis en cache. Nous activons également le debug des assets.

/config/environments/test.rb

# Configure static asset server for tests with Cache-Control for performance
config.serve_static_assets = true
config.static_cache_control = "public, max-age=3600"

# Allow pass debug_assets=true as a query parameter to load pages with unpackaged assets
config.assets.allow_debugging = true

Si nous utilisons Git pour contrôler les sources de notre application, nous pouvons également modifier le fichier .gitignore et ajouter le dossier .sass-cache à la liste des éléments ignorés. Nous ne voulons pas le cache de SASS dans Git.

/.gitignore

.sass-cache/

Déplacer les assets

Maintenant que notre asset pipeline est configuré, il est temps de créer un dossier /app/assets. Nous pouvons ensuite déplacer les dossiers images, javascripts et stylesheets de /public vers /app/assets.

$ mkdir app/assets
$ mv public/images/ app/assets/
$ mv public/javascripts/ app/assets/
$ mv public/stylesheets/ app/assets/

Certains fichiers que nous avons déplacés ne sont plus nécessaires, ceux liés à jQuery dans le dossier javascripts par exemple. Ils sont inclus dans la gem jQuery, nous pouvons donc supprimer les fichiers jquery.js, jquery.min.js et rails.js. Il est maintenant temps de décider de si nous devons placer certains fichiers, comme les plugins jQuery, dans /lib/assets ou /vendor/assets, tel que vu dans l'épisode 279 [regarder, lire].

Nous devons ensuite créer les fichiers de manifest. Cette application contient déjà les fichiers application.js et application.css, nous n'avons donc pas besoin de les créer. Nous allons commencer par le fichier CSS. Pour le transformer en manifest, nous devons ajouter, au début de celui-ci, quelques commentaires qui indiqueront à Sprockets quels fichiers inclure (la syntaxe de Sprockets est également vue dans l'épisode 279). Nous allons dire à Sprockets d'inclure le reste du fichier ainsi que tout ceux présents dans le dossier stylesheets et ses sous dossiers.

/app/assets/stylesheets/application.css

/*
*= require_self
*= require_tree .
*/

/* rest of file omitted */

Nous pouvons faire la même chose pour le fichier application.js mais ce sera légèrement différent car nous voulons inclure jQuery.

/app/assets/javascripts/application.js

//= require jquery
//= require jquery_ujs
//= require_self
//= require_tree .

/* rest of file omitted */

Pour rappel, nous ajoutons require_self ici car le reste du fichier contient du code et require_tree pour inclure les fichiers contenus dans le même dossier.

Nous allons devoir aller dans le layout de l'application pour changer les lignes d'inclusion des fichiers CSS et JavaScript afin qu'elles référencent uniquement les fichiers nécessaires, puisque les autres fichiers sont inclus via les manifests.

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

<%= stylesheet_link_tag "application" %>
<%= javascript_include_tag "application", "http://cdn.sublimevideo.net/js/3s7oes9q.js" %>

Les fichiers JavaScript nécessaires à l'application comprennent un fichier externe qui ne sera pas inclus par l'asset pipeline. Pour celui-ci, nous avons toujours besoin d'une inclusion explicite comme ci-dessus.

Il est maintenant temps de tester notre application dans le navigateur pour nous assurer que toutes nos modifications ont fonctionné. Avant cela, nous allons lancer une nouvelle fois bundle pour installer les gems que nous avons ajoutées. Cela fait, nous pouvons lancer le serveur.

$ rails s

En dehors de quelques images cassées (le logo en haut de l'écran par exemple), tout semble fonctionner.

Le problème est que les URLs des images ont été hard-codée dans le fichier de layout.

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

<img src="/images/railscasts_logo.png" width="423" height="56" alt="RailsCasts = Ruby on Rails Screencasts"/>

Cela ne peut pas fonctionner puisque les images de notre application ne sont plus dans le dossier /public/images. La solution la plus simple pourrait être de changer l'url de l'image de /images/railscasts_logo.png à /assets/railscasts_logo.png mais bien que cela marche en développement, ce ne sera pas le cas en production. Si l'option assets.digest est activée, un hash sera ajouté au nom de fichier, la référence statique vers celui-ci ne fonctionnera plus. Nous devons donc toujours utiliser le helper. Celui-ci va lier l'image correctement en développement comment en production.

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

<%= image_tag("railscasts_logo.png", :size => "423x56", :alt => "RailsCasts - Ruby on Rails Screencasts") %>

Nous allons devoir chercher, dans notre application, toues les références statiques et faire en sorte qu'elles utilisent le helper, comme ci-dessus. Si nous rechargeons la page, l'image apparait, nous indiquant que notre asset pipeline fonctionne correctement.

Nous avons terminé notre migration vers Rails 3.1. Il y a d'autres fonctionnalités dont vous pouvez tirer avantage. Cela vaut la peine de jeter un œil sur les autres épisodes autour de Rails 3.1 pour voir ce qui pourra vous être utile.

Foreman

Sun, 16 Oct 2011 22:06:47 +0000

Ryan Bates à demandé il y a peu, via Twitter, quelle était la meilleure façon de gérer les processus en arrière-plan sur lesquels repose une application Rails pendant son développement. Plusieurs personnes ont recommandé Foreman. Nous allons donc vous le présenter dans cet épisode.

Par exemple, pour utiliser l'application GoVsGo de Ryan en développement, nous devons lancer un certain nombre de processus en arrière-plan. On a par exemple besoin de Beanstalkd, processus script/worker et un serveur Faye. Nous devons lancer chacun d'eux chaque fois que nous voulons utiliser l'application. Il serait agréable d'avoir une solution simple permettant de gérer tous ces processus et c'est pour ça que Foreman est fait.

Installer et Utiliser Foreman

Foreman est fournit sous forme de gem et s'installe de manière classique.

$ gem install foreman

Foreman trouve la liste des processus à gérer dans un fichier Procfile à la racine de l'application, nous devons donc le créer. Dans ce fichier, nous allons lister les processus que nous voulons voir gérés par Foreman. Chacun d'eux est définit par un nom, suivi par le catactère deux-points et du processus à lancer. Notre liste ressemble à ceci :

/Procfile

beanstalk:  beanstalkd
worker:     ./script/worker
faye:       rackup faye.ru -s thin -E production

Une fois notre Procfile écrit, nous pouvons vérifier sa validité en lançant la commande foreman check.

$ foreman check
valid procfile detected (beanstalk, worker, faye)

Si nous utilisons des tabulations au lieu d'espaces pour séparer le nom de la commande, nous allons voir des erreurs de dépréciation, nous devons donc garder cela en tête lors de l'écriture de notre Procfile. Si notre fichier est considéré comme valide, nous pouvons tenter de lancer Foreman avec la commande foreman start.

$ foreman start
20:06:35 beanstalk.1  | started with pid 23140
20:06:35 worker.1     | started with pid 23141
20:06:35 faye.1       | started with pid 23143
20:06:36 faye.1       | >> Thin web server (v1.2.11 codename Bat-Shit Crazy)
20:06:36 faye.1       | >> Maximum connections set to 1024
20:06:36 faye.1       | >> Listening on 0.0.0.0:9292, CTRL+C to stop
20:06:38 worker.1     | [2011-08-29 20:06:38 +0100] Working 1 jobs: [ Game.move ]

Lorsque nous le faisons, chaque processus spécifié dans notre Procfile va être lancé et listé, suivi de ses affichages, dans le terminal. Si nous tapons CTRL+C dans cette fenêtre de terminal, tous les processus sont stoppés.

Foreman a une page de manuel utile qui documente ses fonctionnalités et les différentes options que l'on peut lui passer. Si nous voulons lancer seulement un processus, nous pouvons directement passer son nom en paramètre.

$ foreman start faye
20:35:41 faye.1       | started with pid 23322
20:35:41 faye.1       | >> Thin web server (v1.2.11 codename Bat-Shit Crazy)
20:35:41 faye.1       | >> Maximum connections set to 1024
20:35:41 faye.1       | >> Listening on 0.0.0.0:9292, CTRL+C to stop

Si nous voulons démarrer plusieurs copies d'un même processus, nous pouvons le faire en passant l'option -c. Par exemple, nous pouvons lancer 4 processus worker en appelant foreman start -c worker=4.

$ foreman start -c worker=4
20:39:41 beanstalk.1  | started with pid 23366
20:39:41 worker.1     | started with pid 23368
20:39:41 worker.2     | started with pid 23370
20:39:41 worker.3     | started with pid 23372
20:39:41 worker.4     | started with pid 23374
20:39:41 faye.1       | started with pid 23376
20:39:42 faye.1       | >> Thin web server (v1.2.11 codename Bat-Shit Crazy)
20:39:42 faye.1       | >> Maximum connections set to 1024
20:39:42 faye.1       | >> Listening on 0.0.0.0:9292, CTRL+C to stop
20:39:46 worker.3     | [2011-08-29 20:39:46 +0100] Working 1 jobs: [ Game.move ]
20:39:46 worker.1     | [2011-08-29 20:39:46 +0100] Working 1 jobs: [ Game.move ]
20:39:46 worker.2     | [2011-08-29 20:39:46 +0100] Working 1 jobs: [ Game.move ]
20:39:47 worker.4     | [2011-08-29 20:39:47 +0100] Working 1 jobs: [ Game.move ]

Cela va lancer chaque processus une fois, sauf worker qui sera lancé quatre fois.

Exporter les Processus

Forman fournit une commande export qui permet d'exporter la liste des processus dans un format utilisable sur un serveur de production. Les formats supportés sont pour l'instant inittab et upstart. Si nous lançons la commande foreman export upstart ., Forman va écrire un certain nombre de fichiers de configuration upstart dans le dossier courant. Si nous regardons l'un d'eux de plus près, nous allons voir qu'il va lancer une commande pour démarrer beanstalkd et gérer les logs.

/govsgo-beanstalk-1.conf

start on starting govsgo-beanstalk
stop on stopping govsgo-beanstalk
respawn

exec su - govsgo -c 'cd /Users/eifion/govsgo; export PORT=5000; beanstalkd >> /var/log/govsgo/beanstalk-1.log 2>&1'

C'est tout pour cet épisode sur Foreman. Il est plus court que d'habitude mais Foreman est une solution simple répondant parfaitement à un problème spécifique. Si vous avez besoin de lancer un certain nombre de processus pour faire fonctionner votre application Rails en développement, Foreman vaut la peine d'être considéré.

Pry avec Rails

Sun, 02 Oct 2011 22:16:47 +0000

Pry est une alternative à IRB et, comme IRB, il fournit une invite de commande permettant d'exécuter du code Ruby. Ce qui fait la différence, c'est un nombre important de fonctionnalités en plus. Dans cet épisode, nous allons vous montrer comment Pry fonctionne et comment l'intégrer dans vos applications Rails.

Pry est fournit sous forme de gem et est facile à installer. Nous allons également installer la gem pry-doc, nous reviendrons dessus plus loin.

$ gem install pry pry-doc

Comme nous utilisons les gemsets RVM, nous allons installer Pry de manière à ce qu'il soit accessible globalement, peu importe le gemset utilisé. Nous pouvons le faire grâce aux deux commandes suivantes.

$ rvm gemset use global
$ gem install pry pry-doc

Une fois Pry installé, nous pouvons lancer la commande pry et exécuter du code Ruby comme nous le ferions avec irb.

$ pry
pry(main)> 1 + 2
=> 3

Pry est bien plus qu'un simple calculateur mais, avant d'aller plus loin, nous allons voir comment le faire fonctionner avec une application Rails. Nous allons utiliser l'application de blog qui nous a déjà servi dans de précédents épisodes.

Si nous lançons rails c depuis le dossier de l'application, IRB va démarrer. Pour utiliser Pry à la place, nous devons juste appeler la commande pry et lui passer le fichier d'environnement Rails. Cela fait, nous pouvons accéder aux modèles de notre application, comme dans la console Rails classique.

$ pry -r ./config/environment
pry(main)> Article.count
=> 3

Maintenant que Pry est en place, nous pouvons voir certaines de ses fonctionnalités de plus près. Si nous tapons help, nous allons obtenir la liste de toutes les commandes à notre disposition. Les deux que nous allons utiliser le plus souvent sont cd et ls, jetons-y un œil. La commande cd change le scope courant. Si nous tapons cd Article, nous allons nous placer dans la classe Article. Nous pouvons connaitre le scope courant à tout moment en appelant self.

pry(main)> cd Article
pry(#<Class:0x1022f60e0>):1> self
=> Article(id: integer, name: string, content: text, created_at: datetime, updated_at: datetime, published_at: datetime)

Maintenant que nous somme dans la classe Article, nous pouvons appeler n'importe laquelle de ses méthodes, first par exemple, pour retourner le premier article, comme si nous appelions Article.first.

pry(#<Class:0x1022f60e0>):1> first
=> #<Article id: 1, name: "What is Music", content: "Music is an art form in which the medium is sound o...", created_at: "2011-08-24 20:35:29", updated_at: "2011-08-24 20:37:22", published_at: "2011-05-13 23:00:00">

Nous pouvons également faire cd sur un objet. Si nous appelons cd first en étant dans le scope Article, nous allons changer de scope pour être dans celui du premier article. Nous pouvons dès lors appeler n'importe quelle méthode ou propriété dessus, name par exemple.

pry(#<Class:0x1022f60e0>):1> cd first
pry(#<Article:0x102300c98>):2> name
=> "What is Music"

Nous pouvons même faire cd dans le name de l'article et appeler des méthodes sur cette chaine de caractères.

pry(#<Article:0x102300c98>):2> cd name
pry("What is Music"):3> upcase
=> "WHAT IS MUSIC"

Pry conserve une trace de nos déplacements que nous pouvons voir en appelant nesting.

pry("What is Music"):3> nesting
Nesting status:
--
0. main (Pry top level)
1. #<Class:0x1022f60e0>
2. #<Article:0x102300c98>
3. "What is Music"

Cette commande retourne une liste des objets que nous avons traversé. Si nous tapons exit, nous allons remonter dans l'objet précédant, dans notre cas, le premier article. Si nous remontons de nouveau, nous serons de retour dans la classe Article.

L'autre commande fréquemment utilisée est ls. Cette commande liste les variables et méthodes. Par défaut, elle va lister celles du scope courant. Si, par exemple, nous sommes dans la classe Article, nous verrons ses méthodes lorsque nous appellerons ls.

pry(#<Class:0x1022f60e0>):1> ls
[:_, :_pry_, :inp, :out, :@_create_callbacks, :@_defined_class_methods, :@_save_callbacks, :@_update_callbacks, :@_validate_callbacks, :@arel_engine, :@arel_table, :@attribute_methods_generated, :@cached_attributes, :@column_names, :@columns, :@columns_hash, :@finder_needs_type_condition, :@generated_attribute_methods, :@inheritable_attributes, :@inheritance_column, :@parent_name, :@quoted_primary_key, :@quoted_table_name, :@relation]

Certaines commandes Pry supportent des options et nous pouvons obtenir une liste des options d'une commande en la lançant avec l'option -h. Si nous lançons ls -h, nous verrons la liste des options qu'elle supporte, y compris -m qui permet de lister les méthodes de classe et -M qui liste les méthodes d'instance. Nous pouvons également passer en paramètre un objet ou une classe pour obtenir une liste des méthodes de celui-ci plutôt que pour le scope courant.

Une autre commande Pry utile est show-doc. Disons que nous voulons savoir comment fonctionne la méthode in_groups_of de la classe Array. Nous pouvons le savoir en lançant show-doc Array#in_groups_of.

pry(#<Class:0x1022f60e0>):1> show-doc Array#in_groups_of

From: /Users/eifion/.rvm/gems/ruby-1.9.2-p290/gems/activesupport-3.0.10/lib/active_support/core_ext/array/grouping.rb @ line 19:
Number of lines: 15

signature: in_groups_of(number, fill_with=?)

Splits or iterates over the array in groups of size number,
padding any remaining slots with fill_with unless it is false.

  %w(1 2 3 4 5 6 7).in_groups_of(3) {|group| p group}
  ["1", "2", "3"]
  ["4", "5", "6"]
  ["7", nil, nil]

  %w(1 2 3).in_groups_of(2, '&nbsp;') {|group| p group}
  ["1", "2"]
  ["3", "&nbsp;"]

  %w(1 2 3).in_groups_of(2, false) {|group| p group}
  ["1", "2"]
  ["3"]

Nous pouvons également appeler show-doc directement sur un objet. Notre scope courant est celui de la classe Article, nous pouvons donc appeler all pour obtenir un tableau des articles. Nous pouvons ensuite lancer show-doc all.in_groups_of pour voir la même documentation que ci-dessus.

Autre commande utile, show-method. Cette dernière nous montre le code source d'une méthode. Nous pouvons l'utiliser pour voir la source de in_groups_of (notons que Pry offre l'auto-complétion des commandes grâce à la touche TAB).

pry(#<Class:0x104e63de0>):1> show-method all.in_groups_of

From: /Users/eifion/.rvm/gems/ruby-1.9.2-p290/gems/activesupport-3.0.10/lib/active_support/core_ext/array/grouping.rb @ line 19:
Number of lines: 19

def in_groups_of(number, fill_with = nil)
  if fill_with == false
    collection = self
  else
    # size % number gives how many extra we have;
    # subtracting from number gives how many to add;
    # modulo number ensures we don't add group of just fill.
    padding = (number - size % number) % number
    collection = dup.concat([fill_with] * padding)
  end

  if block_given?
    collection.each_slice(number) { |slice| yield(slice) }
  else
    groups = []
    collection.each_slice(number) { |group| groups << group }
    groups
  end
end

Conjointement, nous trouvons la commande edit-method. Lorsque nous la lançons en lui passant une méthode en paramètre, elle va ouvrir le fichier adéquat dans un éditeur de texte et nous placer sur la ligne appropriée.

Nous pouvons également lancer une commande shell en la préfixant d'un point. Si nous lançons .ls dans Pry, la commande shell ls va être appelée et va lister les fichiers du dossier courant.

Pry est également très utile pour le debug. Dans notre modèle Article, nous avons une méthode word_count qui devrait retourner le nombre de mots dans le contenu d'un article. Il y a un bug dans cette méthode car elle retourne toujours 0, quelque soit le contenu de l'article. Nous pouvons voir la méthode en faisant cd dans le premier Article et en lançant edit-method word_count. Cette méthode ressemble à ceci :

/app/models/article.rb

class Article < ActiveRecord::Base
  attr_accessible :name, :content, :published_at
  has_many :comments

  def word_count
    words = content.scan(/\\w+/)
    words.size
  end
end

Nous pouvons ajouter un breakpoint à n'importe quel endroit du code en appelant binding.pry. Si nous le faisons juste avant la ligne words.size et sauvons le fichier, lorsque nous appelons la méthode word_count de nouveau, l'exécution va s'arrêter sur binding.pry et nous redonner la main sur Pry.

> word_count

From: /Users/eifion/blog/app/models/article.rb @ line 7 in Article#word_count:

     2:   attr_accessible :name, :content, :published_at
     3:   has_many :comments
     4: 
     5:   def word_count
     6:     words = content.scan(/\\w+/)
 =>  7:     binding.pry
     8:     words.size
     9:   end
    10: end

Nous avons accès à toutes les variables locales à la méthode. Nous pouvons donc appeler words pour voir le contenu du tableau words.

pry(#<Article:0x1008c3f38>):3> words
=> []

Le tableau est vide, il semble donc qu'il y ait un problème avec l'expression régulière qui scanne le contenu. Si nous y jetons un œil, nous voyons qu'il y a deux backslashes là où il ne devrait y en avoir qu'un seul. Pour corriger cela, nous pouvons de nouveau faire appel à edit-method word_count, corriger l'expression, retirer binding.pry et sauver le fichier.

/app/models/article.rb

class Article < ActiveRecord::Base
  attr_accessible :name, :content, :published_at
  has_many :comments

  def word_count
    words = content.scan(/\w+/)
    words.size
  end
end

Nous pouvons tester notre correctif en appelant une nouvelle fois word_count. Cette fois, elle fonctionne comme désiré.

pry(#<Article:0x1008c3f38>):3> word_count
=> 55

Nous avons parfois besoin de debugger un contrôleur ou une vue de notre application et la console Rails n'est pas toujours le plus simple pour cela. Pry nous aide également à le faire. Tout d'abord, nous devons ajouter Pry à notre Gemfile.

/Gemfile

source 'http://rubygems.org'

gem 'rails', '3.0.10'
gem 'sqlite3'
gem 'nifty-generators'
gem 'pry', :group => :development

Nous appelons ensuite bundle pour installer la gem puis nous lançons rails s pour démarrer le serveur. Nous pouvons maintenant ajouter un appel à binding.pry n'importe où dans nos contrôleurs pour ajouter un breakpoint.

/app/controllers/articles_controller.rb

def index
  @articles = Article.all
  binding.pry
end

Si nous visitons cette page dans le navigateur, elle va bloquer sur le chargement. Dans le terminal, on peut voir une invite de commande Pry et nous sommes dans le contexte du breakpoint. Comme nous le faisions dans les modèles, nous pouvons inspecter les valeurs de toutes les variables locales. Une fois notre travail terminé, nous pouvons taper exit-all pour permettre à la requête de se terminer.

From: /Users/eifion/blog/app/controllers/articles_controller.rb @ line 4 in ArticlesController#index:

     1: class ArticlesController < ApplicationController
     2:   def index
     3:     @articles = Article.all
 =>  4:     binding.pry
     5:   end
     6: 
     7:   def show
     8:     @article = Article.find(params[:id])
     9:   end

C'est tout pour cet épisode sur Pry. C'est une gem très utile et elle fournit bien plus de fonctionnalités que ce que nous venons de vous montrer. Le wiki couvre beaucoup plus et contient un lien vers un très bon screencast réalisé par Joshua Cheek.

Comprendre l'Asset Pipeline

Wed, 28 Sep 2011 18:38:08 +0000

L'asset pipeline est une des plus importantes fonctionnalités de Rails 3.1. Elle peut cependant être difficile à appréhender. Dans cet épisode, nous allons tenter de la démystifier un peu en montrant comment elle gère les ressources media (assets) de vos applications Rails. Si le sujet vous est totalement inconnu, un bon point de départ est le Guide Rails sur l'asset pipeline qui aborde bon nombre de ses fonctionnalités.

Si vous avez écrit une application Rails 3.1, vous savez probablement qu'en visitant http://localhost:3000/assets/application.js, vous allez obtenir un fichier contenant tous les fichiers JavaScript de votre application. Mais comment cela fonctionne-t-il ?

Le fichier application.js n'a rien de particulier. Tout fichier placé dans le dossier /app/assets/javascripts est tout autant accessible. Si, par exemple, nous créons, dans ce dossier, un fichier nommé greeting.txt, nous pouvons le voir dans le navigateur en visitant http://localhost:3000/assets/greeting.txt. Bien que le fichier soit dans /app/assets/javascripts, l'URL par laquelle nous y accédons est /assets/greeting.txt. Cela s'applique, peu importe, dans quel sous dossier de /app/assets nous plaçons le fichier. Nous pouvons même créer un nouveau dossier et y placer le fichier, il sera toujours accessible à la même URL. Si nous créons effectivement un nouveau dossier, nous devrons tout de même relancer le serveur avant que les fichiers que l'on y place soient accessibles.

Le dossier /app/assets n'est pas le seul dans lequel nous pouvons ajouter des assets. Si nous créons un dossier assets dans /lib, tout fichier placé dans celui-ci sera accessible comme s'il était mis dans le dossier /app/assets. Cela s'applique également à tout fichier placé dans le dossier /vendor/assets.

Si vous avez des assets qui ne sont pas vraiment spécifiques à l'application courante, les dossiers assets situés dans /lib ou /vendor sont leur destination idéale. Si l'application utilise un plugin jQuery, le dossier /vendor/assets est l'endroit où placer ses fichiers JavaScript puisqu'ils sont maintenus par quelqu'un d'autre. Pour les assets maintenus par nos soins mais qui ne sont pas spécifiques à l'application, le choix se portera plutôt sur le dossier /lib.

Dans sa forme la plus basique, l'asset pipeline est une liste de chemins de chargement (loadpaths). Nous pouvons voir cette liste en lançant la console Rails et en inspectant Rails.application.config.assets.paths. Nous afficherons le résultat en YAML pour plus de lisibilité.

> y Rails.application.config.assets.paths
--- 
- /Users/eifion/store/app/assets/images
- /Users/eifion/store/app/assets/javascripts
- /Users/eifion/store/app/assets/stylesheets
- /Users/eifion/store/lib/assets/greeting.txt
- /Users/eifion/store/vendor/assets/stylesheets
- /Users/eifion/.rvm/gems/ruby-1.9.2-p180@railspre/gems/jquery-rails-1.0.13/vendor/assets/javascripts

Le résultat est une liste de tous les dossiers contenus dans /app/assets ainsi que ceux présents dans /lib/assets et /vendor/assets. On trouve toutefois un dossier intéressant à la fin de la liste. Celui-ci provient de la gem jquery-rails, incluse dans notre application. Nous pouvons voir son contenu grâce à la commande bundle open.

$ bundle open jquery-rails

Cela ouvre la gem avec l'éditeur définit dans les variables d'environnement BUNDLER_EDITOR ou EDITOR. Si nous jetons un œil aux fichiers de la gem, nous allons voir un dossier vendor/asset/javascripts contenant un certain nombre de fichiers jQuery que nous pouvons charger via l'asset pipeline.

Comme vous pouvez vous y attendre, nous pouvons accéder à chacun de ces fichiers, via le navigateur, sous le chemin assets puisque le dossier les contenant est listé dans le loadpath de l'asset pipeline.

Ce qu'il est intéressant de noter, c'est que cela signifie que les gems Ruby n'ont plus pour unique but de gérer du code Ruby. Nous pouvons les utiliser pour gérer des fichiers JavaScript ou tout autre type d'asset. Il est à parié que nous verrons, sous peu, de nombreuses librairies JavaScript distribuées sous forme de gems Ruby, nous pourrons alors profiter des avantages de Bundler et de sa gestion des dépendances.

Gérer les Assets avec Sprockets

Retournons au fichier application.js de notre application et jetons-y un œil.

/app/assets/javascripts/application.js

// This is a manifest file that'll be compiled into including all the files listed below.
// Add new JavaScript/Coffee code in separate files in this directory and they'll automatically
// be included in the compiled file accessible from http://example.com/assets/application.js
// It's not advisable to add code directly here, but if you do, it'll appear at the bottom of the
// the compiled file.
//
//= require jquery
//= require jquery_ujs
//= require_tree .

Le fichier contient uniquement des commentaires mais certains ont une signification. Ce type de fichier est un manifest et est géré par Sprockets. Lorsqu'une requête pour ce fichier arrive, Sprockets lit le manifest et compile tous les fichiers mentionnés dans celui-ci puis inclut leur contenu avant le code du manifest.

Le loadpath fonctionne également ici. Nous trouvons une ligne require jquery dans ce fichier (l'extension .js est facultative). Sprockets va chercher ce fichier dans le loadpath et, dans le cas de jquery, le charger depuis le dossier vendor/asset/javascripts de l'engine jquery-rails.

Nous pouvons ajouter n'importe quel fichier JavaScript se trouvant dans le loadpath. Si nous ajoutons require jquery-ui au manifest, le fichier jquery-ui.js sera inclus. Cela s'applique également aux fichiers CoffeeScript. Si nous ajoutons require home, le fichier /app/assets/javascripts/home.js.coffee va être analysé et inclus.

Inclure ce fichier home n'est pas nécessaire car, en bas du fichier, on trouve require_tree .. Le point représente ici le dossier courant. Cela signifie que tout fichier JavaScript ou CoffeeScript présent dans ce dossier et ses sous dossiers sera inclus.

Si nous voulons exclure certains fichiers de l'arborescence, nous le pouvons. Disons que nous avons des pages d'administration sur notre site et que certains fichiers JavaScript doivent être inclus uniquement sur ces pages. Par défaut, ces fichiers vont être inclus sur toutes les pages du site.

Si nous voulons voir les fichiers inclus, nous pouvons ajouter un paramètre debug_assets=1 à l'URL. Cela va stopper l'agrégation des fichiers JavaScript et, lorsque nous consultons le code source de la page, nous allons voir tous les fichiers que Sprockets inclurait, y compris les fichiers du dossier admin.

Il existe deux façons de résoudre ce problème. Nous pourrions utiliser require_directory au lieu de require_tree. Cela permettrait de charger uniquement les fichiers du dossier courant et non ceux de ses sous dossiers. Si nous voulions plus de contrôle sur les fichiers inclus, nous pourrions faire appel à require sur chaque fichier plutôt que sur le dossier. Nous pourrions également déplacer les fichiers JavaScript que nous souhaitons inclure sur toutes les pages dans un sous dossier public et utiliser require_tree ./public pour inclure uniquement ces fichiers.

Si vous vous demandez quelles commandes peuvent être utilisées dans un manifest Sprockets, il n'existe pas encore de bonne documentation mais, dans le code source du fichier directive_processor.rb, on peut trouver des commentaires expliquant comment tout cela fonctionne et quelles sont les commandes utilisables.

Prétraitement

L'asset pipeline permet également de faire du prétraitement. Pour montrer comment cela fonctionne, nous allons créer un fichier nommé greeting.txt dans un nouveau dossier /app/assets/anything. Tel quel, c'est simplement un fichier texte statique mais, nous pouvons ajouter une autre extension au nom de fichier et spécifier un processeur, par exemple .erb. Nous pouvons maintenant ajouter du code ERB dans ce fichier et il sera traité.

/app/assets/anything/greeting.txt.erb

hello world <%= 1 + 1 %>

Si nous regardons ce fichier dans un navigateur, nous allons voir que le code ERB a été exécuté. Notez que nous n'incluons pas l'extension du préprocesseur dans l'URL.

C'est essentiellement la manière de fonctionner de SASS et CoffeeScript. Lorsqu'un fichier a une extension .scss, elle est traitée comme une extension de préprocesseur et le fichier passera par le processeur SASS. Nous pouvons même chaîner les extensions et créer un fichier avec, par exemple, une extension .scss.erb. Ce fichier passerait d'abord par le processeur ERB puis par le processeur SASS.

Le prétraitement est très configurable. Nous pouvons ajouter notre propre processeur ou échanger ceux existants. Tout est géré par la gem Tilt.

Les différences en mode Production

C'est tout pour notre tour rapide de l'asset pipeline. Il existe quelques différences sur son fonctionnement en production et nous allons terminer cet épisode en les abordant. Tout d'abord, nous allons lancer notre serveur en mode production.

$ rails s -e production

Si nous visitons la page d'accueil de notre application et regardons son code source, nous allons voir que nos assets sont délivrés différemment.

<link href="/assets/application-412fe22651f4486c51e54176003a9f57.css" media="screen" rel="stylesheet" type="text/css" />
  <script src="/assets/application-3e3a5167191afa70c7b72440eee7dd40.js" type="text/javascript"></script>

Les noms de fichiers incluent un hash prévu pour le cache. Cela fonctionne bien mieux que l'ancienne méthode, basée sur la query string et utilisée par Rails 3.0, car le nom des fichiers est modifié. Si nous regardons le contenu des fichiers, nous pouvons voir qu'il sont minifiés pour économiser de la bande passante.

Ces assets sont automatiquement mis en cache et servis par le middleware Rack Cache pour plus de rapidité. Si nous voulons que le serveur web se charge lui-même de servir et héberger ces assets, nous pouvons les précompiler en lançant

$ rake assets:precompile

Cela va précompiler les assets dans le dossier /public pour les rendre facilement accessibles par le serveur web.

C'est tout pour cet épisode sur l'asset pipeline. N'oubliez pas de regarder le Guide Rails pour plus d'informations.

Recherche avec Sunspot

Wed, 28 Sep 2011 18:32:07 +0000

Sunspot est une solution permettant d'ajouter une recherche full-text aux applications Ruby. Elle utilise Solr en arrière-plan et a de nombreuses fonctionnalités sympathiques. Dans cet épisode, nous allons l'utiliser pour ajouter une recherche full-text à une application Rails. Nous utiliserons une application de blog qui nous a déjà servi dans de précédents épisodes.

Cette application contient une page qui affiche un certain nombre d'articles et nous voulons faire en sorte de pouvoir chercher parmi ceux-ci. En utilisant SQL, cela devient rapidement difficile et ce n'est pas, en général, la meilleure approche. Une solution dédiée à la recherche full-text, comme Sunspot, s'avère plus pertinente pour implémenter cette fonctionnalité.

Installer Sunspot

Sunspot est distribuée sous forme de gem et s'installe de la manière habituelle, Gemfile et bundle.

/Gemfile

source 'http://rubygems.org'

gem 'rails', '3.0.9'
gem 'sqlite3'
gem 'nifty-generators'
gem 'sunspot_rails'

Une fois la gem et ses dépendances installées, nous devons générer le fichier de configuration de Sunspot en lançant

$ rails g sunspot_rails:install

Cette commande crée un fichier YML dans /config/sunspot.yml. Nous n'avons besoin de faire aucun changement aux réglages par défaut.

Sunspot encapsule Solr dans la gem, nul besoin, donc, de l'installer séparément. Cela signifie que tout fonctionne tout de suite, ce qui est bien pratique en développement. Pour démarrer, nous lançons

$ rake sunspot:solr:start

Si vous êtes sous OS X Lion et que vous n'avez pas installé le runtime Java, il vous sera demandé de le faire lorsque vous lancerez la commande. Vous verrez peut-être un warning de dépréciation mais il peut être ignoré. La commande va également créer quelques fichiers de configuration supplémentaire pour un réglage plus avancé. Nous ne les verrons pas mais ils sont détaillés dans la documentation.

Utiliser Sunspot

Maintenant que nous avons installé Sunspot, nous pouvons l'utiliser dans notre modèle Article. Pour ajouter la recherche full-text, nous utilisons la méthode searchable.

/app/models/article.rb

class Article < ActiveRecord::Base
  attr_accessible :name, :content, :published_at
  has_many :comments
  
  searchable do
    text :name, :content
  end
end

Cette méthode prend un bloc et, dedans, nous définissons les attributs sur lesquels nous voulons effectuer la recherche de manière à ce que Sunspot sache quoi indexer. Nous pouvons utiliser la méthode text pour définir les attributs sur lesquels une recherche full-text sera effectuée. Pour nos articles, nous le ferons pour les champs name et content.

Sunspot indexe automatiquement toute nouvel article mais pas les existants. Nous pouvons dire à Sunspot de re-indexer les entrées existantes en lançant

$ rake sunspot:reindex

Tous les articles sont maintenant dans la base de données de Solr et nous pouvons chercher parmi ceux-ci. Nous allons donc ajouter un champ de recherche en haut de la page d'index.

/app/views/articles/index.html.erb

<% title "Articles" %>

<%= form_tag articles_path, :method => :get do %>
  <p>
    <%= text_field_tag :search, params[:search] %>
    <%= submit_tag "Search", :name => nil %>
<% end %>
<!-- rest of view omitted -->

Ce formulaire envoie les information de recherche en GET à l'action index. Tous les paramètres de recherche seront donc ajoutés à la query string. Nous allons ensuite modifier le contrôleur de façon à ce qu'il récupère les articles en utilisant ce paramètre search. Pour lancer une recherche avec Sunspot, nous appelons la méthode search sur le modèle et lui passons un bloc. Dans ce bloc, nous pouvons faire appel à différentes méthodes pour gérer les recherches complexes. Nous allons utiliser la méthode fulltext et lui passer les paramètres de recherche du formulaire. Enfin, nous allons assigner le résultat à @search. Nous pouvons appeler results dessus pour obtenir la liste des articles correspondants.

/app/controllers/articles_controller.rb

def index
  @search = Article.search do
    fulltext params[:search]
  end
  @articles = @search.results
end

Nous pouvons tester cela en rechargeant la page des articles et en cherchant un mot clé. Nous voyons alors une liste des articles répondant à cette recherche.

La recherche retourne une liste des articles contenant le terme de recherche, que cela soit dans le champ name ou content.

Nous pouvons faire bien plus dans le bloc searchable du modèle Article. Par exemple, nous pouvons utiliser boost pour modifier le poids des champs. Nous pouvons donc rendre le champ name plus important que le champ content.

/app/models/article.rb

class Article < ActiveRecord::Base
  attr_accessible :name, :content, :published_at
  has_many :comments
  
  searchable do
    text :name, :boost => 5
    text :content
  end
end

C'est important lorsque nous voulons trier les résultats par pertinence. Dans notre cas, les articles dont le nom contient le terme recherché apparaîtront avant ceux le comprenant seulement dans leur contenu.

Les attributs listés dans le bloc searchable ne doivent pas nécessairement être des champs en base de données, nous pouvons utiliser n'importe quelle méthode définie dans le modèle. Nous allons créer une méthode publish_month qui va retourner le nom du mois et l'année de publication de l'article et effectuer ensuite une recherche sur cette méthode comme s'il s'agissait d'un champ en base.

/app/models/article.rb

class Article < ActiveRecord::Base
  attr_accessible :name, :content, :published_at
  has_many :comments
  
  searchable do
    text :name, :boost => 5
    text :content, :publish_month
  end
  
  def publish_month
    published_at.strftime("%B %Y")
  end
  
end

Nous devons indexer de nouveau les entrées en lançant rake sunspot:reindex avant de pouvoir effectuer notre recherche sur le nom de mois.

Au lieu de créer une méthode, nous pouvons créer un bloc et effectuer la recherche sur ce que retourne ce dernier. Un article a des commentaires, nous pouvons donc ajouter la possibilité d'effectuer une recherche sur le contenu des commentaires en utilisant un bloc.

/app/models/article.rb

class Article < ActiveRecord::Base
  attr_accessible :name, :content, :published_at
  has_many :comments
  
  searchable do
    text :name, :boost => 5
    text :content, :publish_month
    text :comments do
      comments.map(&:content)
    end
  end
  
  def publish_month
    published_at.strftime("%B %Y")
  end
  
end

Dans le bloc, le contexte est celui d'un Article. Nous pouvons donc obtenir les commentaires et faire un mapping sur leur contenu. Bien que cela retourne un tableau, Sunspot saura s'en charger et indexer tous les commentaires afin de pouvoir effectuer une recherche sur ces derniers.

Effectuer une recherche sur les attributs

Que devons-nous faire si nous souhaitons des capacités de recherche plus puissantes qu'une simple recherche full-text ? Une recherche sur un attribut particulier, par exemple. Nous devons simplement passer le type d'attribut que nous voulons filtrer, que ce soit string, integer, float ou encore timestamp. Pour ajouter l'attribut published_at aux champs recherchés, nous pouvons utiliser la méthode time.

/app/models/article.rb

class Article < ActiveRecord::Base
  attr_accessible :name, :content, :published_at
  has_many :comments
  
  searchable do
    text :name, :boost => 5
    text :content, :publish_month
    text :comments do
      comments.map(&:content)
    end
    time :published_at
  end
  
  def publish_month
    published_at.strftime("%B %Y")
  end
  
end

Nous pouvons en faire usage dans ArticlesController pour restreindre les articles cherchés à une date de publication antérieure à la date courante. Pour cela, nous utilisons la méthode with.

/app/controllers/articles_controller.rb

def index
  @search = Article.search do
    fulltext params[:search]
    with(:published_at).less_than(Time.zone.now)
  end
  @articles = @search.results
end

Cela fait, une recherche ne retournera pas les articles qui n'ont pas encore été publiés. Vous pouvez trouver une très bonne documentation sur le sujet sur la page de wiki de Sunspot.

Recherche à facettes

Une recherche à facettes nous permet de filtrer les résultats de recherche en se basant sur certains attributs comme le mois de publication d'article. Disons que nous voulons ajouter une liste de liens montrant les dates auxquelles des articles ont été publiés. Lorsque nous cliquons sur l'un de ces liens, la liste des articles est alors filtrée pour afficher uniquement ceux publiés pour le mois choisi.

Pour ce faire, nous allons d'abord ajouter un attribut string au bloc searchable pour notre méthode publish_month.

/app/models/article.rb

class Article < ActiveRecord::Base
  attr_accessible :name, :content, :published_at
  has_many :comments
  
  searchable do
    text :name, :boost => 5
    text :content, :publish_month
    text :comments do
      comments.map(&:content)
    end
    time :published_at
    string :publish_month
  end
  
  def publish_month
    published_at.strftime("%B %Y")
  end
  
end

Nous pouvons en faire une recherche à facettes en appelant facet dans le bloc search du contrôleur ArticlesController.

/app/controllers/articles_controller.rb

def index
  @search = Article.search do
    fulltext params[:search]
    with(:published_at).less_than(Time.zone.now)
    facet(:publish_month)
  end
  @articles = @search.results
end

Nous pouvons maintenant lister ces facettes sur la page index en ajoutant le code suivant entre le champ de recherche et la liste des articles.

/app/views/articles/index.html.erb

<div id="facets">
  <h3>Published</h3>
  <ul>
    <% for row in @search.facet(:publish_month).rows %>
      <li>
        <% if params[:month].blank? %>
          <%= link_to row.value, :month => row.value %> (<%= row.count %>)
        <% else %>
          <strong><%= row.value %></strong> (<%= link_to "remove", :month => nil %>)
        <% end %>
      </li>
    <% end %>
  </ul>
</div>

Dans ce code, nous bouclons sur chacune des facettes publish_month et les affichons. Si nous appelons .facet sur notre objet @search et passons l'attribut que nous voulons lister, dans notre cas :publish_month, nous pouvons ensuite appeler .rows dessus pour obtenir chaque option de facette pour cet attribut.

Lorsque nous appelons row.value, la valeur de l'attribut est retournée (ex: “January 2011”). Nous pouvons également faire appel à row.count pour obtenir le nombre d'articles correspondant à cette valeur. S'il y a un paramètre month dans la query string, nous allons afficher sa valeur suivie d'un lien “remove” qui permet de supprimer le paramètre. Cela nous permet de sélectionner une facette donnée et de la passer sous forme d'un paramètre month.

Lorsque nous rechargeons la page, et que nous avons reindexé les entrées, nous allons voir la liste des facettes dans un panneau, chacune montrant un mois et le nombre d'articles publiés durant ce mois. Si nous sélectionnons un mois, nous allons le recevoir en paramètre dans la query string mais les articles ne seront pas filtrés. Pour corriger cela, nous devons ajouter un autre paramètre with au bloc search dans le contrôleur afin qu'il filtre les articles d'après le paramètre month s'il est présent.

/app/controllers/articles_controller.rb

def index
  @search = Article.search do
    fulltext params[:search]
    with(:published_at).less_than(Time.zone.now)
    facet(:publish_month)
    with(:publish_month, params[:month]) ↵ 
      if params[:month].present?
  end
  @articles = @search.results
end

Maintenant, lorsque nous sélectionnons un mois, nous verrons la liste correctement filtrée.

Lorsque nous cliquons sur le lien “remove”, nous revenons à la liste complète. Cela fonctionne avec les résultats de recherches. Si nous cherchons un terme, la liste affichera les mois contenant des articles correspondants.

Les facettes sont une fonctionnalité fort sympathique en parallèle de la recherche.

C'est tout pour cet épisode. Sunspot est un très bon moyen d'ajouter une recherche full-text aux applications Rails et fournit de nombreuses fonctionnalités supplémentaires non abordées ici. Pensez à jeter un oeil sur le wiki pour plus d'informations.

Mountable Engines

Thu, 08 Sep 2011 21:26:06 +0000

Le Rails 3.1 HackFest a eu lieu le week-end dernier et, grâce au dur travail des participants, la cinquième release candidate de Rails 3.1 est maintenant disponible. Cette release contient d'importantes corrections pour les mountable engines. Les mountable engines nous permettent de monter une application Rails à l'intérieur d'une autre. Nous allons voir cela dans cet épisode.

Vous vous souvenez peut être du plugin Notification Exception, couvert dans l'épisode 104 [ regarder ]. Il peut être ajouté à une application et stocke en base chaque exception levée par l'application. Il fournit également une interface utilisateur permettant de consulter les exceptions. Dans cet épisode, nous allons recréer ce plugin sous forme de mountable engine.

Mise en route

Avant de commencer à écrire notre engine, nous devons nous assurez que nous utilisons Rails 3.1 Release Candidate 5 ou une version plus récente. Nous pouvons installer la dernière version en date grâce à

$ gem install rails --pre

Une fois cela fait, nous pouvons commencer à générer notre mountable engine. Nous n'avons pas besoin de le créer dans une application existante, créer un engine revient à créer un nouvelle application Rails avec la commande rails new. La seule différence est que nous lançons rails plugin new à la place. Comme notre application s'occupe d'exceptions, nous l'appellerons uhoh. Nous devons passer l'option --mountable pour en faire un mountable engine.

$ rails plugin new uhoh --mountable

La structure du dossier de notre engine ressemble beaucoup à celle d'une application Rails classique et c'en est pratiquement une. Elle est simplement conçue pour être montée à l'intérieur d'une autre. Il existe cependant quelques différences. Il existe un certain nombre de dossier sous namespace dans l'application ; par exemple, le fichier application_controller est dans le dossier /app/controllers/uhoh. Le principe est le même pour les fichiers des dossiers assets, helpers et views. Cela permet de garder le code de l'engine séparé de celui de l'application dans laquelle il sera monté. La présence du dossier assets signifie qu'il n'est plus besoin de copier les ressources media dans le dossier public de l'application lorsque l'engine est monté. Grâce à l'asset pipeline, tout est géré pour nous.

Les assets (ressources media) sont également encapsulés dans un namespace, nous devons donc passer par ce dossier lorsque nous créons un lien vers ceux-ci. Nous pouvons également voir cela dans le dossier layouts. Il semble y avoir un bug en RC5, nous voyons deux fichiers application.html.erb . Nous pouvons supprimer celui situé en dehors du dossier uhoh. Si nous regardons l'autre, nous allons voir que les références aux assets que l'on y trouve contiennent le dossier uhoh. Chaque fois que nous créons un liens vers ces assets, nous devons inclure ce namespace.

/app/views/layouts/uhoh/application.html.erb

<!DOCTYPE html>
<html>
<head>
  <title>Uhoh</title>
  <%= stylesheet_link_tag    "uhoh/application" %>
  <%= javascript_include_tag "uhoh/application" %>
  <%= csrf_meta_tags %>
</head>
<body>

<%= yield %>

</body>
</html>

Nous allons ensuite regarder l'un des fichiers clés d'un engine, engine.rb dans le dossier /lib/uhoh.

/lib/uhoh/engine.rb

module Uhoh
  class Engine < Rails::Engine
    isolate_namespace Uhoh
  end
end

C'est une classe héritant de Rails::Engine et c'est l'endroit où la configuration est centralisée. Il existe déjà un appel à isolate_namespace dans la classe et cela signifie que l'engine sera traité comme une unité isolée et nous n'avons donc pas à nous inquiéter pour l'application dans laquelle il sera monté.

La dernière partie de l'engine que nous allons voir est située dans le dossier /test/dummy. On y trouve une application Rails permettant de montrer comment marche notre engine lorsqu'il est monté. Le dossier config de l'application contient un fichier routes.rb. Ce dernier contient un appel à mount auquel est passée la classe principale de l'engine qui sera attaché à l'URL.

/test/dummy/config/routes.rb

Rails.application.routes.draw do
  mount Uhoh::Engine => "/uhoh"
end

C'est ce qu'un utilisateur devra faire lorsqu'il installera votre engine dans une application, le monter sur une URL de leur choix. C'est une application Rack et, par conséquent, si une requête arrive sur /uhoh elle sera passée à notre class Engine. Une bonne pratique est d'ajouter cette ligne aux instructions d'installation dans le fichier README de l'engine. Cela permettra aux utilisateurs de savoir comment le monter dans le fichier routes de leur application.

Bien que cette application d'exemple soit située dans le dossier /test, elle est également utile pour tester à la main. Si nous lançons rails s depuis le dossier de notre engine, l'application d'exemple va se lancer. Si nous visitons http://localhost:3000/uhoh/, nous serons menés à notre engine puisque c'est l'URL à laquelle il est monté. Nous allons voir une erreur lors de la visite de cette page. C'est tout à fait normal puisque nous n'avons pas encore écrit le contrôleur correspondant.

Nous allons donc créer un contrôleur failures dans l'engine. Nous pouvons utiliser les générateurs de Rails pour le faire, tout comme nous le ferions dans une application Rails classique. Bien que nous soyons dans un engine, nous n'avons pas besoin de spécifier le namespace, tout cela est fait pour nous.

$ rails g controller failures index

Cela génère les mêmes fichiers que pour un contrôleur classique, à la différence que tout est dans le bon dossier de namespace. Nous allons ensuite modifier les routes de l'engine pour fournir une route root pointant vers l'action index de notre contrôleur. Cela se fait dans le fichier /config/routes.rb de l'engine.

/config/routes.rb

Uhoh::Engine.routes.draw do
  root :to => "failures#index"
end

Lorsque nous visitons la page http://localhost:3000/uhoh/, nous allons maintenant voir la vue de l'action.

Sur cette page, nous voulons afficher une liste des exceptions levées. Nous allons avoir besoin d'un modèle pour stocker cette information et nous allons donc créer un simple modèle Failure avec un champ message.

$ rails g model failure message:text

Maintenant que nous avons créé le modèle, comment lançons nous la migration ? Dans l'engine lui-même, nous pouvons lancer rake db:migrate comme d'habitude et tout fonctionnera comme prévu. Cela ne marchera pas lorsque quelqu'un tentera de monter l'engine dans une application car rake ne prendra pas les migrations de celui-ci. Nous devons dire aux utilisateurs d'utiliser rake uhoh:install:migrations. Cela va copier les migrations de l'engine dans l'application afin qu'ils puissent faire appel à rake db:migrate normalement. Inclure cette information dans les instructions d'installation de l'engine semble une bonne idée.

La console Rails fonctionne également comme attendu et nous allons maintenant l'utiliser pour créer une Failure d'exemple.

Uhoh::Failure.create!(:message => "hello world!")

Notez que nous devons inclure le namespace chaque fois que nous référençons une classe. Maintenant que nous avons une entrée Failure, nous allons l'afficher dans l'action index de FailuresController.

/app/controllers/uhoh/failures_controller.rb

module Uhoh
  class FailuresController < ApplicationController
    def index
      @failures = Failure.all
    end
  end
end

Dans la console, au contraire, nous n'avons pas besoin de spécifier le namespace car nous somme déjà dans le module Uhoh. Dans la vue, nous allons écrire un peu de code pour parcourir les exceptions et les afficher sous forme de liste.

/app/views/uhoh/failures/index.html.erb

<h1>Failures</h1>
<ul>
  <% for failure in @failures %>
  <li><%= failure.message %></li>
  <% end %>
</ul>

Lorsque nous rechargeons la page, nous allons voir la Failure que nous avons ajoutée.

Noter les exceptions

Maintenant que nous avons une méthode pour enregistrer une Failure, nous allons devoir en générer une chaque fois que l'application dans laquelle est monté l'engine lève une exception. Pour tester cela, nous devons simuler une exception dans l'application de démonstration. Nous allons donc nous placer dans le dossier de cette dernière et générer un contrôleur nommé simulate avec une action failure.

$ rails g controller simulate failure

Dans l'action, nous allons lever une exception.

/test/dummy/app/controllers/simulate_controller.rb

class SimulateController < ApplicationController
  def failure
    raise "Simulating an exception"
  end
end

Si nous visitons cette action dans le navigateur, nous allons voir l'exception, comme attendu.

Nous allons devoir changer notre engine de façon à ce qu'il note les exceptions et crée une nouvelle Failure lorsqu'elles sont levées. La solution que nous allons utiliser n'est pas la plus efficace mais elle est simple et fonctionnera dans notre cas. Nous allons commencer par créer un initializer dans notre engine. Il n'y a pas de dossier initializers dans le dossier config de l'engine mais nous pouvons en créer un et les initializers placés dedans fonctionneront. Dans ce dossier, nous allons créer un fichier nommé exception_handler.rb.

/app/config/initializers/exception_handler.rb

ActiveSupport::Notifications.subscribe ↵
  "process_action.action_controller" do ↵
  |name, start, finish, id, payload|
  if payload[:exception]
    name, message = *payload[:exception]
    Uhoh::Failure.create!(:message => message)
  end
end

Dans ce fichier, nous souscrivons à une notification (les notifications sont vues dans l'épisode 249 [regarder, lire]) qui nous indique lorsqu'une action est traitée. Lorsque c'est le cas, nous pouvons vérifier si le payload contient une exception. Si oui, nous savons donc qu'un exception a été levée et nous pouvons stocker son message dans une nouvelle Failure.

Nous devons redémarrer le serveur avant de tester. Nous pouvons ensuite visiter http://localhost:3000/simulate/failure de nouveau pour lever une exception. Une fois l'exception vue, nous pouvons ensuite vérifier qu'elle est listée en allant sur http://localhost:3000/uhoh.

Gérer les URLs dans l'engine

Tout helper d'URL que nous utilisons dans l'engine va générer des URLs pour cet engine. Par exemple, si nous ajoutons un lien vers l'URL root depuis page index des failures, ce lien pointera vers l'URL root de cet engine et non vers celle de l'application dans laquelle il est monté.

/app/views/uhoh/failures/index.html.erb

<p><%= link_to "Failures", root_url %></p>

Ce lien pointe vers http://localhost:3000/uhoh qui est l'URL root de l'engine. C'est la même page que celle contenant le lien car l'URL root est définie dans les routes pour pointer sur l'action index de FailuresController. Nous pouvons créer des liens vers l'application elle-même en appelant le helper d'URL sur main_app comme ceci :

/app/views/uhoh/failures/index.html.erb

<p><%= link_to "Failures", root_url %></p>
<p><%= link_to "Simulate Failure", main_app.simulate_failure_path %></p>

Cela nous donne un lien vers la page de simulation d'exception de l'application, http://localhost:3000/simulate/failure.

Que se passe-t-il si nous voulons faire cela dans l'autre sens et avoir un lien vers l'engine dans l'application ? La première chose à faire est de changer la ligne dans le fichier de routes de l'application pour donner un nom à la route qui monte l'engine. Cela se fait avec l'option :as.

/test/dummy/config/routes.rb

Rails.application.routes.draw do

  get "simulate/failure"

  mount Uhoh::Engine => "/uhoh", :as => "uhoh_engine"
end

Nous pouvons ensuite accéder aux helpers d'URLs de l'engine en les appelant comme des méthodes de uhoh_engine. Pour démontrer ceci, nous allons changer temporairement notre action failure de façon à ce que, au lieu de lever une exception, elle redirige vers l'URL root de l'engine.

/test/dummy/app/controllers/simulate_controller.rb

class SimulateController < ApplicationController
  def failure
    redirect_to uhoh_engine.root_url
  end
end

Si nous visitons http://localhost:3000/simulate/failure, nous allons être redirigés vers http://localhost:3000/uhoh puisque nous utilisons le helper de l'engine pour rediriger vers l'une des ses URLs. C'est une autre fonctionnalité qu'il peut être bon de mentionner dans le README de votre engine.

La fonctionnalité de notre engine est presque complète mais la page listant les failures est plutôt terne. Nous allons donc l'égayer un peu en ajoutant quelques assets. Tout d'abord, nous allons ajouter une image. Nous en avons déjà trouvé une et l'avons placée dans le dossier /app/assets/images/uhoh. Pour l'inclure dans la page, nous pouvons utiliser image_tag comme pour n'importe quelle autre image.

/app/views/uhoh/failures/index.html.erb

<%= image_tag "uhoh/alert.png" %>
<h1>Failures</h1>
<ul>
  <% for failure in @failures %>
  <li><%= failure.message %></li>
  <% end %>
</ul>

<p><%= link_to "Failures", root_url %></p>
<p><%= link_to "Simulate Failure", ↵
  main_app.simulate_failure_path %></p>

Nous allons également inclure un peu de CSS. SASS et CoffeeScript ne sont pas disponibles par défaut dans les engines, bien qu'ils puissent être ajoutés comme dépendances. Si nous ajoutons quelques CSS au fichier failures.css, il sera inclus automatiquement.

/app/assets/stylesheets/uhoh/failures.css

html, body {
  background-color: #DDD;
  font-family: Verdana;
}

body {
  padding: 20px 200px;
}

img {
  display: block;
  margin: 0 auto;
}

a {
  color: #000;
}

ul {
  list-style: none;
  margin: 0;
  padding: 0;
}

li {
  background-color: #FFF;
  margin-bottom: 10px;
  padding: 5px 10px;
}

Ceci est également valable pour JavaScript. Tout code placé dans le fichier failures.js sera automatiquement inclus.

/app/assets/javascripts/uhoh/failures.js

$(function() {
  $("li").click(function() {
    $(this).slideUp();
  });
});

Lorsque nous rechargeons la page, elle sera bien mieux et nous pourrons masquer les exceptions en cliquant dessus. Cela nous montre que le JavaScript a été inclus.

C'est tout pour cet épisode. Les mountable engines sont une très bonne fonctionnalité de Rails 3.1 et valent vraiment la peine d'y jeter un œil.

Tester le temps et les requêtes externes

Sun, 21 Aug 2011 22:07:47 +0000

Dans l'épisode précédent, nous avons montré un workflow de développement dirigé par les tests. En majeure partie, le modèle utilisé fonctionne bien mais il peut arriver que certaines fonctionnalités de notre application soient difficiles à tester. Nous allons voir deux scénarios de ce type dans cet épisode.

Tester le temps actuel

La dernière fois, nous avons créé un certain nombre de specs pour tester le modèle User. Nous les avons écrites assez rapidement et nous allons maintenant revenir sur l'une d'elles et nous attarder quelque peu dessus.

/spec/models/user.rb

it "saves the time the password reset was sent" do
  user.send_password_reset
  user.reload.password_reset_sent_at.should be_present
end

Cette spec vérifie que, lorsqu'une demande de réinitialisation de mot de passe est envoyée, le moment de l'envoi est stocké dans le champ password_reset_sent_at. Ceci est testé grâce au matcher be_present de RSpec. Ce matcher appelle une méthode, fournie par Rails, nommée present? qui vérifie l'existence d'un objet.

Cette spec est incomplète : elle vérifie qu'une valeur existe pour password_reset_sent_at mais ne s'assure pas que cette valeur est le temps actuel. Nous renseignons bien password_reset_sent_at à Time.zone.now, dans la méthode send_password_reset du modèle User, mais la spec passerait, peu importe la valeur renseignée. Idéalement, nous devrions tester que la valeur est la date actuelle en écrivant quelque chose comme ceci :

/spec/models/user.rb

it "saves the time the password reset was sent" do
  user.send_password_reset
  user.reload.password_reset_sent_at.should eq(Time.zone.now)
end

Malheureusement cela ne peut pas fonctionner. Le temps actuel, au moment du test, sera légèrement après le moment ou le code testé est exécuté. Lorsque l'on est face à un problème comme celui-ci, cela vaut la peine de se poser la question de l'utilité d'ajouter une certaine complexité aux tests afin qu'ils soient complets. Dans de nombreux cas, comme celui-ci, il est suffisant de tester que la valeur du timestamp existe. Il y a peu de chances qu'un bug ait lieu dans une ligne de code qui renseigne le temps mais il peut arriver que nous ayons besoin de tester le temps actuel. Regardons donc comment nous pourrions le faire dans les specs.

Guard tourne et nous pouvons voir que notre spec échoue. Bien que le timestamp soient très proches en terme de secondes, ils ne sont pas identiques et cela suffit à causer l'échec de la spec.

Failures:

  1) User#send_password_reset saves the time the password reset was sent
     Failure/Error: user.reload.password_reset_sent_at.should eq(Time.zone.now)

       expected Mon, 25 Jul 2011 20:34:46 UTC +00:00
            got Mon, 25 Jul 2011 20:34:46 UTC +00:00

       (compared using ==)

       Diff:
     # ./spec/models/user_spec.rb:16:in `block (3 levels) in <top (required)>'

Finished in 1.95 seconds
9 examples, 1 failure

Nous pouvons gérer ce genre de problèmes en utilisant une gem nommée Timecop. Nous pouvons l'utiliser pour manipuler le temps actuel de plusieurs façons, y compris en le gelant. Cela signifie que nous pouvons geler le temps actuel durant le fonctionnement de la spec afin que le moment auquel le timestamp est renseigné soit exactement le même que lors du test.

Nous pouvons ajouter Timecop à notre application en l'ajoutant dans le Gemfile et en lançant bundle. Puisque nous en avons seulement besoin pour nos tests, nous le plaçons dans le groupe test.

/Gemfile

source 'http://rubygems.org'

gem 'rails', '3.1.0.rc4'

gem 'sqlite3'

# Asset template engines
gem 'sass-rails', "~> 3.1.0.rc"
gem 'coffee-script'
gem 'uglifier'

gem 'jquery-rails'

gem "rspec-rails", :group => [:test, :development]
group :test do
  gem "factory_girl_rails"
  gem "capybara"
  gem "guard-rspec"
  gem "timecop"
end

Il est maintenant temps d'aller dans le fichier spec_helper.rb et d'ajouter un appel à Timecop.return dans le bloc config.before(:each). Cela assure le fait que tout changement effectué avec Timecop est annulé avant le lancement de chaque spec.

Nous pouvons appeler Timecop.freeze dans n'importe quelle spec et geler le temps durant l'exécution de cette dernière. Cela signifie que nous pouvons comparer les deux timestamps.

/spec/models/user.rb

it "saves the time the password reset was sent" do
  Timecop.freeze
  user.send_password_reset
  user.reload.password_reset_sent_at.should eq(Time.zone.now)
end

À présent, lorsque Guard lance les specs, elles passent toutes.

Il y a un autre scénario inattendu qui peut causer l'échec des tests. Si vous assistez à une conférence sur Ruby dans un autre fuseau horaire, vous pouvez vous retrouver avec un échec de vos tests relatifs au temps. Au lieu de parcourir la moitié du monde, il est bien moins coûteux de régler le fuseau horaire dans les specs. Cela se fait en réglant Time.zone :

Time.zone = "Paris"

Pour régler temporairement le fuseau, pour une seule spec, nous pouvons appeler Time.use_zone.

/spec/model/user_spec.rb

it "saves the time the password reset was sent" do
  Timecop.freeze
  user.send_password_reset
  Time.use_zone("Paris") do
    user.reload.password_reset_sent_at.should eq(Time.zone.now)
  end
end

Le code à l'intérieur du bloc sera lancé comme si nous étions à Paris. Nous pouvons utiliser cela pour tester que nos specs passent toujours, même si nous somme dans un autre fuseau horaire.

Chaque fois que nous testons de temps actuel, nous devrions utiliser quelque chose comme Timecop de façon à ce que le temps puisse être manié de manière consistante et ne change pas lors d'un changement de fuseau horaire ou d'un passage à l'heure d'été. Nous devrions également l'utiliser pour tester notre code dans différents fuseaux horaire afin de vérifier que notre application fonctionne mondialement.

Tester les requêtes web externes

Nous allons jeter un oeil au test des requêtes web externes. Cette section est basée sur un problème que Ryan Bates a rencontré lors de la réécriture du site de Railscasts, en particulier la fonctionnalité qui affiche la taille des fichiers pour chaque format vidéo lorsque vous passez sur le lien télécharger.

La taille du fichier est récupérée depuis un serveur web externe puisque les fichiers média sont stockés sur un serveur à part. Cela signifie qu'une requête web externe est effectuée et nous allons maintenant montrer comment cela a été testé. Nous allons le faire grâce à une petite application d'exemple. Elle a une ressource WebRequest et un formulaire contenant un champ texte qui attend une URL.

Lorsque nous saisissons l'URL d'une vidéo dans le champs texte et soumettons le formulaire, l'URL est affichée ainsi que la taille du fichier indiquant zéro octet.

La taille du fichier est zéro puisque nous n'avons pas encore implémenté cette fonctionnalité. Nous avons, dans notre modèle WebRequest, une méthode content_length mais cette méthode est codée en dur pour retourner 0. Nous allons maintenant l'implémenter en utilisant le TDD (développement dirigé par les tests).

/app/models/web_request.rb

class WebRequest < ActiveRecord::Base
  def content_length
    0
  end
end

Il existe un certain nombre de gems aidant au test des requêtes web externes mais nous allons utiliser Fakeweb. Cette gem peut être utilisée pour enregistrer une URI et définir ce que sa réponse doit être. Lorsque nous utilisons Net::HTTP pour récupérer cette URI, elle va, à la place, retourner cette réponse plutôt que faire une requête externe.

Fakeweb est installé, comme d'habitude, en l'ajoutant dans le Gemfile et en appelant bundle. Nous allons ensuite ajouter une configuration pour Fakeweb en effectuant deux modifications dans le fichier spec_helper.rb.

/spec/spec_helper.rb

ENV["RAILS_ENV"] ||= 'test'
require File.expand_path("../../config/environment", __FILE__)
require 'rspec/rails'
require 'capybara/rspec'

Dir[Rails.root.join("spec/support/**/*.rb")].each {|f| require f}

FakeWeb.allow_net_connect = false

RSpec.configure do |config|
  config.mock_with :rspec
  config.use_transactional_fixtures = true
  config.include(MailerMacros)
  config.before(:each) do
    Timecop.return
    reset_email
    FakeWeb.clean_registry
  end
end

Près du début du fichier, nous renseignons Fakeweb.allow_net_connect à false ce qui va empêcher les specs d'effectuer des connexion HTTP externes. Cela permet de faire en sorte que, si nous avons oublié des requêtes externes dans nos specs, elles ne ralentiront pas la totalité de la suite de tests et Fakeweb nous fera savoir que les specs tentent de se connecter au web. Dans before(:each), nous appelons Fakeweb.clean_registry afin que chaque spec démarre dans le même état.

Dans les specs pour WebRequest, nous allons écrire une spec qui va vérifier que le contenu est récupéré.

/spec/models/web_request_spec.rb

require 'spec_helper'

describe WebRequest do
  it "fetches the content length" do
    FakeWeb.register_uri(:head, "http://example.com", :content_length => 123)
    WebRequest.new(:url => "http://example.com").content_length.should eq(123)
  end
end

Nous appelons FakeWeb.register_uri pour enregistrer une fausse URL. Le premier argument de cette méthode est le type de requête que nous voulons faire, nous pouvons obtenir la taille du fichier depuis les informations d'en-tête, nous utilisons donc :head. Les autres arguments sont l'URL et les en-têtes de notre choix. Dans notre cas, la longueur du contenu (Content Length). Nous créons ensuite un nouvel objet WebRequest qui appelle cette URL et vérifions que la valeur retournée par la méthode content_length est égale à la valeur saisie dans l'en-tête.

Bien sûr, lorsque nous lançons la spec, elle échoue puisque notre méthode content_length retourne toujours 0. Pour faire passer la spec, nous devons modifier cette méthode afin qu'elle retourne la vraie valeur du content length pour le fichier demandé.

/app/models/web_request.rb

class WebRequest < ActiveRecord::Base
  def content_length
    uri = URI.parse(url)
    response = Net::HTTP.start(uri.host, uri.port) { |http| http.request_head(uri.path) }
    response["content-length"].to_i
  end
end

La méthode appelle maintenant Net::HTTP.start en utilisant l'URL passée au modèle. Le bloc passé appelle request_head pou récupérer l'en-tête de la réponse. Enfin, elle retourne la valeur de l'en-tête content-length.

Rails n'inclue pas Net::HTTP par défaut, nous devons donc ajouter un require dans notre application. Nous allons de le faire dans le fichier application.rb.

/config/auth.rb

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

require 'net/http'
require 'rails/all'
# rest of file

Toutes nos specs passent à présent et, lorsque nous rechargeons la page de notre requête, la bonne taille de fichier est affichée.

Si jamais vous avez besoin de gérer des requêtes web externes dans vos tests, Fakeweb est une très bonne solution.

Comment nous testons

Mon, 08 Aug 2011 18:43:36 +0000

À partir de cet épisode, nous verrons plus souvent le sujet des tests. Cette fois-ci, nous allons montrer comment nous aurions écrit les tests pour l'épisode précédent [regarder, lire], plus spécifiquement, le lien “forgotten password” (mot de passe oublié) que nous avons ajouté au formulaire de connexion.

Lorsque nous avons commencé le dernier épisode, nous avions une application avec un formulaire de connexion. L'application avait un système d'authentification assez simple et un formulaire de connexion mais pas de checkbox “remember me” (se souvenir de moi) ou de lien “forgotten password” (mot de passe oublié). Nous les avons donc ajoutés. Nous allons de nouveau ajouter le lien mais cette fois, nous allons le faire grâce au Test Driven Development (TDD, Développement Dirigé par les Tests).

La dernière fois, nous avons testé l'application dans le navigateur. Cette fois, nous garderons le navigateur fermé et écrirons du code pour tester la fonctionnalité. Nous l'ouvrirons seulement lorsque nous aurons besoin de nous concentrer sur l'expérience utilisateur.

Pour nous aider à écrire nos tests, nous devons ajouter quelques gems relatives aux tests dans le Gemfile de notre application. Nous utilisons Rails 3.1 mais tout ce que nous allons faire fonctionnera sous Rails 3.0.

/Gemfile

source 'http://rubygems.org'

gem 'rails', '3.1.0.rc4'

gem 'sqlite3'

# Asset template engines
gem 'sass-rails', "~> 3.1.0.rc"
gem 'coffee-script'
gem 'uglifier'

gem 'jquery-rails'

gem "rspec-rails", :group => [:test, :development]
group :test do
  gem "factory_girl_rails"
  gem "capybara"
  gem "guard-rspec"
end

Nous utilisons RSpec mais n'importe quel framework de test ferait l'affaire. Notez que, contrairement aux autres gems de test, RSpec est également dans le groupe development de façon à ce que ses tâches Rake fonctionnent correctement. Nous avons aussi choisi d'utiliser Factory Girl plutôt que les fixtures, Capybara pour simuler les interactions du navigateur et Guard pour lancer les tests automatiquement. Chacune de ces gems a été vue dans un épisode précédent : Factory Girl était abordée dans l'épisode 158 [regarder, lire], Capybara dans l'épisode 257 [regarder, lire] et Guard dans l'épisode 264 [regarder, lire].

Nous pouvons installer les gems grâce à la commande bundle. Une fois cela fait, nous allons configurer RSpec en lançant

$ rails g rspec:install

Nous allons créer quelques dossiers dans celui nommé /rspec : un dossier support pour les fichiers de support ainsi qu'un dossier models et un dossier routing qui sont requis par Guard.

$ mkdir spec/support spec/models spec/routing

Il est également temps de lancer l'initialiseur de Guard.

$ guard init rspec

Puisque nous développons sous OS X, nous devons installer la gem rb-fsevent de façon à ce que Guard puisse détecter les changements de fichiers. Une fois cela fait, nous allons lancer Guard dans un nouvel onglet de Terminal et le garder actif en arrière-plan.

$ guard
Please install growl gem for Mac OS X notification support and add it to your Gemfile

Guard is now watching at '/Users/eifion/auth'
Guard::RSpec is running, with RSpec 2!
Running all specs
No examples found.

Lorsque nous avons lancé le générateur RSpec, il a créé un fichier /spec/spec_helper.rb. Nous devons activer Capybara dans ce fichier. Pour ce faire, nous allons ajouter une ligne require 'capybara/spec'.

/spec/spec_helper.rb

# This file is copied to spec/ when you run 'rails generate rspec:install'
ENV["RAILS_ENV"] ||= 'test'
require File.expand_path("../../config/environment", __FILE__)
require 'rspec/rails'
require 'capybara/rspec'
# rest of file...

Nous allons également suivre le conseil donné dans les commentaires du fichier et retirer la ligne contenant le chemin vers les fixtures puisque nous n'allons pas les utiliser.

/spec/spec_helper.rb

# Remove this line if you're not using ActiveRecord or ↵
  ActiveRecord fixtures
config.fixture_path = "#{::Rails.root}/spec/fixtures"

Notre premier test

Nous sommes maintenant parés pour commencer nos tests et nous allons démarrer avec un test d'intégration que nous allons appeler password_reset.

$ rails g integration_test password_reset

Le générateur RSpec va prendre la main et créer ce que l'on appelle une request spec (spécification de requête). Le code par défaut dans la spec ressemble à ceci :

/spec/requests/password_resets_spec.rb

require 'spec_helper'

describe "PasswordResets" do
  describe "GET /password_resets" do
    it "works! (now write some real specs)" do
      # Run the generator again with the --webrat flag if you want to use webrat methods/matchers
      get password_resets_path
      response.status.should be(200)
    end
  end
end

Nous allons retirer la spec par défaut et la remplacer par la nôtre et tester qu'un e-mail est envoyé à un utilisateur lorsqu'il demande une réinitialisation de son mot de passe. Nous aurons besoin d'un enregistrement User avec lequel travailler. Nous pourrions passer par la page d'inscription et enregistrer notre utilisateur mais il est préférable de se concentrer uniquement sur ce que nous voulons tester. Nous allons donc utiliser une factory (fabrique). Avant de commencer nos tests, nous allons créer, dans le fichier factories.rb du dossier /spec, une factory pour le modèle User. Ce nom et cet emplacement signifient que toutes les factories que nous allons définir dedans seront automatiquement chargées par Factory Girl.

/spec/factories.rb

Factory.define :user do |f|
  f.sequence(:email) { |n| "foo#{n}@example.com" }
  f.password "secret"
end

Cette factory est simple et va générer un utilisateur avec une adresse e-mail et un mot de passe uniques. Nous allons maintenant l'utiliser pour nos tests.

/spec/requests/password_resets_spec.rb

require 'spec_helper'

describe "PasswordResets" do
  it "emails user when requesting password reset"
    user = Factory(:user)
    visit login_path
    click_link "password"
    fill_in "Email", :with => user.email
    click_button "Reset Password"
  end
end

Ce test utilise notre factory pour créer un utilisateur et simule ensuite, grâce à quelques commandes Capybara, les étapes par lesquelles un utilisateur passerait pour réinitialiser son mot de passe. Nous visitons la page de connexion et cliquons sur le lien contenant 'mot de passe'. En ne définissant pas précisément le texte du lien, nos tests sont moins figés, si le texte du lien passe, par exemple, de 'Mot de passe oublié ?' à 'Vous avez oublié votre mot de passe ?', ils fonctionneront toujours. Sur la page à laquelle nous mène le lien, nous trouvons un champ texte associé à un label dont le texte contient 'Email' et saisissons comme valeur l'e-mail de l'utilisateur. Enfin, nous cliquons sur le bouton 'Réinitialiser mot de passe'.

Notre spec n'est pas encore terminée mais lorsque nous la sauvegardons, Guard va la lancer et nous allons voir notre premier échec.

  1) PasswordResets emails user when requesting password reset
     Failure/Error: click_link "password"
     Capybara::ElementNotFound:
       no link with title, id or text 'password' found
     # (eval):2:in `click_link'
     # ./spec/requests/password_resets_spec.rb:7:in `block (2 levels) in <top (required)>'

La spec échoue car Capybara ne trouve pas le lien 'mot de passe'. Nous allons corriger ceci avant de continuer. Tout ce que nous devons faire, c'est ajouter le lien à la page de connexion.

/app/views/sessions/new.html.erb

<h1>Log in</h1>

<%= form_tag sessions_path do %>
  <div class="field">
    <%= label_tag :email %>
    <%= text_field_tag :email, params[:email] %>
  </div>
  <div class="field">
    <%= label_tag :password %>
    <%= password_field_tag :password %>
  </div>
  <p><%= link_to "forgotten password?", new_password_reset_path %>
  <div class="actions"><%= submit_tag "Log in" %></div>
<% end %>

Le lien pointe vers new_password_reset_path mais, comme ce chemin n'est pas encore défini, Guard va nous donner une autre erreur lorsqu'il lancera la spec de nouveau.

  1) PasswordResets emails user when requesting password reset
     Failure/Error: visit login_path
     ActionView::Template::Error:
       undefined local variable or method `new_password_reset_path' for #<#<Class:0x000001039349d8>:0x000001039269f0>

Cela montre les avantages de cette méthode de test. L'erreur suivante est montrée et sa correction ne devrait pas demander beaucoup de code. Nous allons générer un contrôleur PasswordResets avec une action new. Comme nous utilisons des specs de requête pour tester les couches contrôleur et vue, nous n'avons pas besoin des fichiers de spec du contrôleur et des vues. Nous pouvons dire au générateur de ne pas les créer en passant l'option --no-test-framework.

$ rails g controller password_resets new --no-test-framework

Nous devons également modifier le fichier de routage pour faire de PasswordResets une ressource.

/config/routes.rb

Auth::Application.routes.draw do

  get "logout" => "sessions#destroy", :as => "logout"
  get "login" => "sessions#new", :as => "login"
  get "signup" => "users#new", :as => "signup"
  root :to => "home#index"
  resources :users
  resources :sessions
  resources :password_resets
end

Lorsque Guard lance notre spec, il nous indique maintenant qu'il ne peut pas trouver le champ de texte email sur la page de réinitialisation de mot de passe.

  1) PasswordResets emails user when requesting password reset
     Failure/Error: fill_in "Email", :with => user.email
     Capybara::ElementNotFound:
       cannot fill in, no text field, text area or password field with id, name, or label 'Email' found

Pour corriger cela, nous allons remplacer le code par défaut de la vue de réinitialisation de mot de passe par un formulaire contenant le champ et le bouton nécessaires.

/app/views/password_resets/new.html.erb

<%= form_tag password_resets_path, :method => :post do %>
  <div class="field">
    <%= label_tag :email %>
    <%= text_field_tag :email, params[:email] %>
  </div>
  <div class="actions"><%= submit_tag "Reset Password" %></div>
<% end %>

L'erreur suivante est causée par le fait qu'il n'y ait pas d'action create à laquelle le formulaire peut envoyer une requête POST.

  1) PasswordResets emails user when requesting password reset
     Failure/Error: click_button "Reset Password"
     AbstractController::ActionNotFound:
       The action 'create' could not be found for PasswordResetsController

Nous allons créer cette action dans le contrôleur et faire en sorte qu'elle redirige vers la page d'accueil.

/app/controllers/password_resets_controller.rb

class PasswordResetsController < ApplicationController
  def new
  end

  def create
    redirect_to :root
  end

end

Nous avons maintenant le nécessaire pour que notre spec passe.

Running: spec/controllers/password_resets_controller_spec.rb
.

Finished in 0.14507 seconds
1 example, 0 failures

Étendre notre spécification

Maintenant que notre spec passe, nous pouvons l'étendre. Nous voulons montrer une notification après que le bouton 'Réinitialiser mot de passe' ait été cliqué. Nous allons donc ajouter cela à la spec.

/spec/requests/password_resets_spec.rb

require 'spec_helper'

describe "PasswordResets" do
  it "emails user when requesting password reset" do
    user = Factory(:user)
    visit login_path
    click_link "password"
    fill_in "Email", :with => user.email
    click_button "Reset Password"
    page.should have_content("Email sent")
  end
end

Le test, bien sûr, échoue puisque nous n'avons pas encore écrit le code pour afficher le message. Nous allons modifier le contrôleur pour que cela soit fait.

/app/controllers/password_resets.rb

class PasswordResetsController < ApplicationController
  def new
  end

  def create
    redirect_to :root, :notice => "Email sent with password reset instructions."
  end

end

La spec passe de nouveau mais nous n'envoyons toujours pas l'e-mail. Nous pouvons le tester en utilisant ActionMailer::Base::deliveries pour obtenir une liste des e-mails envoyés. Nous pouvons ensuite appeler last sur cette liste pour récupérer le dernier e-mail envoyé. Nous le ferons souvent dans nos specs, nous allons donc créer un nouveau fichier dans /spec/support et y écrire le code permettant de récupérer le dernier e-mail envoyé.

/spec/support/mailer_macros.rb

module MailerMacros
  def last_email
    ActionMailer::Base.deliveries.last
  end

  def reset_email
    ActionMailer::Base.deliveries = []
  end
end

Nous avons également écrit une méthode reset_email que nous allons appeler au début de chaque spec. Elle va vider la liste de façon à ce que nous puissions commencer chaque spec dans un état connu.

De façon à ce que nous puissions utiliser ces nouvelles méthodes dans nos specs, nous allons appeler config.include dans notre fichier spec_helper.rb et inclure notre nouveau module.

/spec/spec_helper.rb

# This file is copied to spec/ when you run 'rails generate rspec:install'
ENV["RAILS_ENV"] ||= 'test'
require File.expand_path("../../config/environment", __FILE__)
require 'rspec/rails'
require 'capybara/rspec'

# Requires supporting ruby files with custom matchers and macros, etc,
# in spec/support/ and its subdirectories.
Dir[Rails.root.join("spec/support/**/*.rb")].each {|f| require f}

RSpec.configure do |config|
  config.mock_with :rspec
  config.use_transactional_fixtures = true
  config.include(MailerMacros)
  config.before(:each) { reset_email }
end

Après avoir inclu notre macro, nous allons utiliser config.before(:each) pour appeler reset_email de façon à ce que la liste des e-mails envoyés soit vidée avant chaque lancement de spec.

Nous pouvons maintenant utiliser notre nouvelle méthode last_email dans nos specs et vérifier que le dernier e-mail envoyé était à destination de l'utilisateur que nous venons de créer.

/spec/requests/password_resets_spec.rb

require 'spec_helper'

describe "PasswordResets" do
  it "emails user when requesting password reset" do
    user = Factory(:user)
    visit login_path
    click_link "password"
    fill_in "Email", :with => user.email
    click_button "Reset Password"
    page.should have_content("Email sent")
    last_email.to.should include(user.email)
  end
end

Ce test va évidemment échouer. Le dernier e-mail aura pour valeur nil puisque aucun code n'a encore été écrit pour l'expédier. Nous allons générer un mailer de façon à pouvoir le faire.

$ rails g mailer user_mailer password_reset

Le générateur crée son propre fichier de spécification que nous regarderons un peu plus tard. Pour le moment, nous allons le commenter pour pouvoir nous concentrer sur notre spec en cours. Nous allons modifier le mailer de façon à ce qu'il envoie l'e-mail à l'adresse de l'utilisateur avec un sujet approprié.

/app/mailers/user_mailer.rb

class UserMailer < ActionMailer::Base
  default from: "from@example.com"

  def password_reset(user)
    @user = user
    mail :to => user.email, :subject => "Password Reset"
  end
end

Dans notre PasswordResetsController, nous allons changer l'action create de façon à ce qu'elle trouve l'utilisateur par l'adresse e-mail saisie dans le formulaire et envoie l'e-mail.

/app/controllers/password_resets_controller.rb

def create
  user = User.find_by_email(params[:email])
  UserMailer.password_reset(user).deliver
  redirect_to :root, :notice => "Email sent with password ↵
   reset instructions."
end

Notre spec passe à nouveau.

Gérer le token de réinitialisation de mot de passe

Bien que la spec passe, la fonctionnalité qu'elle définit est loin d'être complète. Nous devrions générer un token (jeton) de réinitialisation de mot de passe et l'ajouter dans l'e-mail. Ces détails n'ont pas besoin d'être placés dans la spécification de requête. Il est préférable de faire en sorte qu'elle définisse le flux général de la requête, dans notre cas, vérifier que l'utilisateur reçoit un e-mail de réinitialisation de mot de passe lorsqu'il le demande. Nous pouvons utiliser des tests plus bas niveau pour vérifier les détails.

Maintenant que nous avons une spec qui passe, c'est le moment de jeter un oeil sur notre code pour voir ce qui peut être pris du contrôleur et placé dans le modèle. Un bon exemple ici est la ligne de code dans PasswordResetsController qui envoie l'e-mail. Nous pouvons la déplacer dans une nouvelle méthode send_password_reset dans le modèle User.

/app/controllers/password_resets_controller.rb

def create
  user = User.find_by_email(params[:email])
  user.send_password_reset
  redirect_to :root, :notice => "Email sent with password ↵
   reset instructions."
end

/app/models/user.rb

class User < ActiveRecord::Base
  attr_accessible :email, :password, :password_confirmation
  has_secure_password
  validates_presence_of :password, :on => :create

  def send_password_reset
    UserMailer.password_reset(self).deliver
  end
end

Nous allons maintenant vérifier que nos specs passent toujours. C'est le cas, nous pouvons donc continuer. Nous allons ensuite écrire plus de specs pour ajouter un peu de matière à notre modèle User. Nous allons créer un fichier de specs dans /spec/models/user.rb et y écrire quelques specs.

/spec/models/user_spec.rb

require 'spec_helper'

describe User do
  describe "#send_password_reset" do
    let(:user) { Factory(:user) }

    it "generates a unique password_reset_token each time" do
      user.send_password_reset
      last_token = user.password_reset_token
      user.send_password_reset
      user.password_reset_token.should_not eq(last_token)
    end

    it "saves the time the password reset was sent" do
      user.send_password_reset
      user.reload.password_reset_sent_at.should be_present
    end

    it "delivers email to user" do
      user.send_password_reset
      last_email.to.should include (user.email)
    end
  end
end

Nous voulons que la méthode send_password_reset fasse trois choses lorsqu'elle est appelée. Elle devrait créer un token unique, enregistrer le moment auquel le token a été envoyé et expédier un e-mail à l'utilisateur. Elle effectue déjà la dernière tâche. Nous allons modifier la méthode afin qu'elle se charge également des deux autres. Notez qu'avant les specs, nous appelons let(:user). Cela assigne un nouvel utilisateur, issue de la factory, à user avant chaque exécution de spec.

Deux des specs échouent pour le moment et cela est dû au fait que nous n'avons ni le champ password_reset_token, ni le champ password_reset_sent_at dans la table des utilisateurs en base.

$ rails g migration add_password_reset_to_users password_reset_token:string password_reset_sent_at:datetime

Avec les nouveaux champs en base, les specs échouent toujours mais pour d'autres raisons.

Failures:

  1) User#send_password_reset generates a unique password_reset_token each time
     Failure/Error: user.password_reset_token.should_not eq(last_token)

       expected nil not to equal nil

       (compared using ==)
     # ./spec/models/user_spec.rb:11:in `block (3 levels) in <top (required)>'

  2) User#send_password_reset saves the time the password reset was sent
     Failure/Error: user.reload.password_reset_sent_at.should be_present
       expected present? to return true, got false
     # ./spec/models/user_spec.rb:16:in `block (3 levels) in <top (required)>'

Les specs échouent maintenant parce que password_reset_token et password_reset_sent_at ne sont pas renseignés dans la méthode sent_password_reset. Cela peut être corrigé en écrivant une méthode generate_token qui va créer un token unique. Nous pouvons ensuite modifier sent_password_reset afin qu'elle appelle generate_token, donne une valeur à password_reset_sent_at et sauvegarde l'utilisateur.

/app/models/user.rb

class User < ActiveRecord::Base
  attr_accessible :email, :password, :password_confirmation
  has_secure_password
  validates_presence_of :password, :on => :create

  def send_password_reset
    generate_token(:password_reset_token)
    self.password_reset_sent_at = Time.zone.now
    save!
    UserMailer.password_reset(self).deliver
  end

  def generate_token(column)
    begin
      self[column] = SecureRandom.urlsafe_base64
    end while User.exists?(column => self[column])
  end
end

Nos specs passent toutes à nouveau.

Tester le Mailer

Maintenant que nos specs passent, nous allons retourner à celle de notre mailer, créée lors de la génération de ce dernier. Nous l'avions alors commentée. Nous allons devoir modifier le code par défaut de façon à pouvoir vérifier que notre mailer fonctionne correctement. Dans la spec, nous allons créer un nouvel utilisateur depuis la factory mais cette fois, nous allons renseigner le champ password_reset_token de cet utilisateur. Nous allons ensuite changer la ligne créant l'e-mail afin que l'utilisateur soit passé en paramètre de l'appel à UserMailer.password_reset.

La spec va vérifier que l'e-mail est envoyé à la bonne adresse et que le corps contient le lien vers le token de réinitialisation de l'utilisateur.

/spec/mailers/user_mailer_spec.rb

require "spec_helper"

describe UserMailer do
  describe "password_reset" do
    let(:user) { Factory(:user, :password_reset_token => "anything") }
    let(:mail) { UserMailer.password_reset(user) }

    it "sends user password reset url" do
      mail.subject.should eq("Password Reset")
      mail.to.should eq([user.email])
      mail.from.should eq(["from@example.com"])
    end

    it "renders the body" do
      mail.body.encoded.should match(edit_password_reset_path(user.password_reset_token))
    end
  end
end

Notre spec échoue puisque le corps de l'e-mail ne contient pas le lien, ajoutons le donc.

/app/views/user_mailer/password_reset.text.erb

To reset your password, click the URL below.

<%= edit_password_reset_url(@user.password_reset_token) %>

If you did not request your password to be reset just ignore this email and your password will continue to stay the same.

La spec échoue toujours car une option :host est manquante pour l'envoie de l'e-mail. Nous pouvons la configurer dans le fichier de réglage de notre environnement de test en ajoutant la ligne suivante :

/config/environments/test.rb

config.action_mailer.default_url_options = { :host => "www.example.com" }

Nous devons également configurer cette option dans nos environnements de développement et de production mais nous n'allons pas le faire maintenant.

Toutes nos specs passent maintenant. Au passage, si nous avions besoin de dire à Guard de relancer les specs, nous pourrions le faire grâce à CTRL+\.

Tester d'autres scénarios

L'une des parties les plus difficiles du développement dirigé par les tests et de se lancer et d'établir un workflow. Une fois que vous avez commencé, il est facile de copier/coller les tests pour ajouter des variations et tester de nouvelles fonctionnalités. Par exemple, testons le cas où un utilisateur saisit une adresse e-mail erronée et demande une réinitialisation de mot de passe. Nous pouvons facilement copier la spec existante dans password_resets_spec.rb et en créer une nouvelle pour tester cela.

/spec/requests/password_resets_spec.rb

it "does not email invalid user when requesting password reset" do
  visit login_path
  click_link "password"
  fill_in "Email", :with => "madeupuser@example.com"
  click_button "Reset Password"
  page.should have_content("Email sent")
  last_email.should be_nil
end

La spec échoue puisque le code du contrôleur échoue si l'utilisateur n'est pas trouvé. Nous allons corriger cela.

/app/controllers/password_resets_controller.rb

def create
  user = User.find_by_email(params[:email])
  user.send_password_reset if user?
  redirect_to :root, :notice => "Email sent with password ↵
    reset instructions."
end

Cela répond au test et toutes nos specs passent à nouveau.

Avec ce modèle de développement établi, il est facile d'aller dans la spécification de requête et d'ajouter de nouvelles fonctionnalités à la réinitialisation de mot de passe, par exemple, pour tester que le token n'a pas expiré ou qu'il est bien valide, etc. D'autres cas de tests sont disponibles dans le code source final de cet épisode sur la page Github de Ryan Bates.

C'est tout pour cet épisode sur le test du lien 'Mot de passe oublié'. Tester peut être un sujet controversé et différents points de vue sont émis quant à la meilleure façon de les écrire pour une application Rails. Le plus important est que vous testiez votre application, peu importe la méthode.