#284 Active Admin

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.

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></pre>

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.

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.

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.

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 => "£"
    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.

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 => "£"
    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.

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 => "£"
      end
    end
    default_actions
  end
end

Nous pouvons maintenant styliser cette colonne en modifiant le fichier 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.

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 => "£"
      end
    end
    default_actions
  end
end

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

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.

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.

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.

/*
 * 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.

/* 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.

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.