Voici donc la méthode que j’emploi pour faire du user acceptance testing. L’exemple décrit ici utilise rails, cucumber et rspec, mais cela fonctionne également bien avant Typolight, cucumber et phpspec.

Soit, je développe un site pour un client qui vend des peintures. Une des fonctionnalité est le catalogue de peinture. Pour compliquer un peu cet exemple (et le rendre donc plus proche de la réalité), disons que ce client veut que lorsqu’on visionne la page d’une peinture, on voit le nombre d’autres visiteurs qui la visionne en même temps. Je lui dis d’abord que cette fonctionnalité n’est pas rentable, si on prend en compte son temps/coût de développement et son retour sur investissement. Mon client m’assure que c’est rentable, grâce au principe « le monde attire le monde » : si un visiteur remarque que d’autres personnes regarde la peinture en même temps que lui, il aura plus envie de l’acheter.

Dans la user story du catalogue, on donc trouve le scénario suivant :

Scénario: Voir le détail d'une peinture
  Lorsque je vais sur la page de la liste des peinture
  Et que je suis le lien de la première peinture
  Alors je dois voir sa photo
  Et je dois voir son titre
  Et je dois voir son auteur
  Et je dois voir son prix
  Et je dois voir le nombre de personnes qui visualisent ce produit actuellement

Une fois que le client a validé ce scénario, j’écris les steps cucumber suivantes :

Then /je dois voir sa photo/ do
  response.should have_selector( '#paint .picture img[src*="paint-1-full.jpg"]' )
end
 
Then /je dois voir son titre/ do
  response.should have_selector( '#paint h1.title:contains("Paint 1 test")' )
end
 
Then /je dois voir son auteur/ do
  response.should have_selector( '#paint .author:contains("Paint 1 author")' )
end
 
Then /je dois voir son prix/ do
  response.should have_selector( '#paint .price:contains("10€")' )
end
 
Then /je dois voir le nombre de personnes qui visualisent ce produit actuellement/ do
  response.should have_selector( '#paint .viewer-count:contains("5")' )
end

Cucumber, couplé à webrat, a cet avantage de permettre de faire des tests précis des vues à base de sélecteur CSS3. De nombreuses autres méthodes sont permises, et notament toute une gamme de méthodes qui executent une action tout en la testant, par exemple .click_link( link ) fait une assertion sur l’existence de ce lien, puis le suit effectivement. Pour ma part, j’aime bien être le plus précis possible dans les sélecteurs dans mes steps afin de me permettre de composer d’un trait mes vues ensuite.

Ayant ces steps, je peux maintenant écrire ma vue :

<div id="paint">
  <h1 class="title">< %= @paint.title -%></h1>
 
  <div class="picture">
    <img src="<%= @paint.imageSRC -%/>" alt="Photo de < %= @paint.title -%>" />
  </div><!-- .picture -->
 
  <div class="author">
    < %= @paint.author -%>
  </div><!-- .author -->
 
  <div class="price">
    < %= "%.2f" % @paint.price -%>€
  </div><!-- .price -->
 
  <div class="viewer-count">
    < %= @viewer_count -%>
  </div><!-- .viewer-count -->
</div><!-- #paint -->

Je sais maintenant que mon controller doit assigner @paint et @viewer_count. J’ai également déjà de bon indices sur ce dont je vais avoir besoin dans mes modèles et ma base de donnée. Je peux maintenant écrire les test de mon controller. Qu’est-ce que ce controller doit faire? Il doit assigner un modèle Paint et calculer le nombre de personnes qui voient actuellement cet article. Réflichissant à cette deuxième fonctionnalité, je me dis que cela doit être une méthode de classe de Visitor, qui vérifiera les journaux de visite pour une page donnée. Je n’ai pas besoin d’en savoir plus pour l’instant.

require 'spec_helper'
 
describe PaintsController do
 
  def mock_paint(stubs={})
    @mock_paint ||= mock_model(Paint, stubs)
  end
 
  describe "GET show" do
    it "assigns the requested paint as @paint and the current viewers count as @viewer_count" do
      Paint.stub!( :find ).with( "1" ).and_return( mock_paint( :title => 'Paint 1 test', :imageSRC => 'paint-1-full.jpg', :author => 'Paint 1 author', :price => '10.0' ) )
      Visitor.stub!( :viewer_count ).with( '/paints/show/1' ).and_return( 5 )
      get :show, :id => "1"
      assigns[ :paint ].should equal( mock_paint )
      assigns[ :viewer_count ].should equal( 5 )
    end
  end
end

Je peux maintenant écrire mon controller.

class PaintsController < ApplicationController
  def show
    @paint        = Paint.find( params[:id] )
    @viewer_count = Visitor.viewer_count( request.request_uri )
 
    respond_to do |format|
      format.html # show.html.erb
      format.xml  { render :xml => @paint }
    end
  end
end

Désormais, je sais que j’ai besoin de deux modèles : Paint et Visitor. Je sais également à quoi ils doivent répondre : :title, :imageSRC, :author et :price pour les instances de Paint, :viewer_count pour la classe Visitor. Qu’est-ce qui sera attribut et qu’est-ce qui sera méthode dans tout cela? Je réalise maintenant que tous ce à quoi doit répondre une instance de paint est un attribut simple. Il s’agira donc d’un modèle simple avec title, imageSRC, author et price en tant que champs de la table `paints`.

À ce stade, je peux utiliser le generateur rspec_model pour créer ce modèle simple et ses tests :
./script/generate rspec_model Paint title:string imageSRC:string author:string price:float

Visitor est un modèle moins simple. Que sais-je sur lui? D’abord, il doit répondre à la méthode :viewer_count. J’écris donc tout de suite ce test.

require 'spec_helper'
 
describe Visitor do
  it "should give the viewer count" do
    Visitor.viewer_count( '/paints/show/1' ).should equal( 5 )
  end
end

Je m’interroge maintenant sur comment retrouver ce nombre. Les visites doivent être loggée dans une table. Un visiteur est considéré comment visitant une page s’il l’a visité dans les 5 précédentes minutes. J’identifie un visiteur par son IP. Je dois effacer les anciennes visites pour ne pas surcharger ma db. Ok, j’ai ce qu’il faut pour écrire mes specs.

D’abord, je sais que chaque visite doit être loggé. Cela passera donc par un before_filter dans application_controller.rb . Je modifie donc mon fichier de test de mon controller ainsi :

require 'spec_helper'
 
describe PaintsController do
 
  def mock_paint(stubs={})
    @mock_paint ||= mock_model(Paint, stubs)
  end
 
  before( :each ) do
    Visitor.stub!( :log )
  end
 
  describe "GET show" do
    it "assigns the requested paint as @paint and the current viewers count as @viewer_count" do
      Paint.stub!( :find ).with( "1" ).and_return( mock_paint( :title => 'Paint 1 test', :imageSRC => 'paint-1-full.jpg', :author => 'Paint 1 author', :price => '10.0' ) )
      Visitor.stub!( :viewer_count ).with( 'paints/show/1' ).and_return( 5 )
      get :show, :id => "1"
      assigns[ :paint ].should equal( mock_paint )
      assigns[ :viewer_count ].should equal( 5 )
    end
  end
end

Je peux maintenant écrire le before_filter :

class ApplicationController < ActionController::Base
  before_filter :log_visit
  helper :all # include all helpers, all the time
  protect_from_forgery # See ActionController::RequestForgeryProtection for details
 
  def log_visit
    Visitor.log( request.request_uri, request.ip, Time.now )
  end
end

Cela m’en dit plus sur mon modèle Visitor. Il possède une méthode de classe :log. Celle ci enregistrera l’ip, la page et la date. Cette méthode devra également être responsable du vidage de la table. Cela fait une requête de plus à chaque visite, mais ça maintiendra la table presque vide. Je peux donc écrire son test :

require 'spec_helper'
 
describe Visitor do
  it "should give the viewer count" do
    Visitor.viewer_count.should equal( 5 )
  end
 
  it "should log visits" do
    Visitor.should_receive( :delete_all )
    ip, page, date = '127.0.0.1', '/show/paint/1', Time.now
    Visitor.should_receive( :create ).with( :page => page, :ip => ip, :date => time )
    Visitor.log( page, id, date )
  end
end

Je sais maintenant que mon modèle ma table visitors possède les champs :page, :ip et :date. Je peux générer le modèle.
./script/generate model Visitor page:string ip:string date:datetime

Et je peux implémenter ma méthode :log

class Visitor < ActiveRecord::Base
  attr_accessible         :page, :ip, :date
 
  def self.log( page, ip, date )
    Visitor.delete_all( [ "date < ?", 5.minutes.ago.to_s( :db ) ] )
    Visitor.create( :page => page, :ip => ip, :date => date )
  end
end

Je sais également comment retrouver le nombre de visiteurs d’une page. Je complète donc son test :

require 'spec_helper'
 
describe Visitor do
  it "should give the viewer count" do
    page = '/paints/show/1'
    Visitor.should_receive( :all ).with( :conditions => [ "page = ?", page ] ).and_return( [ 1, 2, 3, 4, 5 ] )
    Visitor.viewer_count( page ).should equal( 5 )
  end
 
  it "should log visits" do
    Visitor.should_receive( :delete_all )
    ip, page, date = '127.0.0.1', '/show/paint/1', Time.now
    Visitor.should_receive( :create ).with( :page => page, :ip => ip, :date => time )
    Visitor.log( page, id, date )
  end
end

Et j’écris la méthode :

class Visitor < ActiveRecord::Base
  attr_accessible         :page, :ip, :date
 
  def self.log( page, ip, date )
    Visitor.delete_all( [ "date < ?", 5.minutes.ago.to_s( :db ) ] )
    Visitor.create( :page => page, :ip => ip, :date => date )
  end
 
  def self.viewer_count( page )
    return Visitor.all( :conditions => [ "page = ?", page ] ).length
  end
end

À ce point, j’ai terminé l’implémentation de mon scénario. Il ne me reste plus qu’à le tester. Les specs doivent déjà passer, Pour faire passer les tests de cucumber, je dois d’abord écrire ma route et inclure mes fixtures (nombreux sont ceux qui détestent les fixtures, aujourd’hui, je les trouve personnellement plus simple d’utilisation dans le cadre de cucumber).

L’immense avantage de cette méthode est de rendre tout évident. C’est un no-brainer total et il n’y a qu’à développer, au sens strict. Plutôt que de construire un outil en tentant d’imaginer ses usages, puis d’adapter les usages en fonction de l’outil créé ( schéma du type : on va des modèles aux vues ), je défini d’abord l’usage en disant ce que mes outils doivent faire, et je les construis en conséquence ( schéma du type : vues vers modèles ).

L’immense inconvénient est que les tests ne sont pas exécutables avant l’arrivée aux modèles. Il est donc important de procéder à très petite itérations. Celle que je viens de prendre pour exemple est déjà presque trop longue (en fait, il est assez probable qu’en situation réelle, j’aurai d’abord fait le :show classique, puis j’aurais rajouté le :view_count).

Prenons le script suivant :

class Person
  attr_accessor :food
 
  def initialize
    @food = 10
    @firstname = 'John'
    @lastname  = 'Doe'
  end
 
  def eat
    @food -= 1
    true
  end
 
  def name
    @firstname + ' ' + @lastname
  end
 
  def name=( fullname )
    parts      = fullname.split( ' ', 2 )
    @firstname = parts[0]
    @lastname  = parts[1]
  end
end
 
michel = Person.new
michel.name = 'Michel Dupont'
michel.food                     # => 10
michel.eat                      # => true
michel.name                     # => 'Michel Dupont'

Nous voyons ici qu’il n’est pas possible de distinguer, formellement, la méthode “eat” et la méthode “name” de l’attribut “food”. Que nous importe, finalement, leur implémentation? Lorsque j’utilise l’interface d’un objet, je veux soit exécuter une action, soit manipuler une valeur. Dans le cas où je souhaite retrouver une valeur, peu m’importe de savoir si cette valeur se trouve directement dans un attribut ou si une méthode est appelée pour me le retourner : cela relève de l’implémentation et non de l’usage. Au niveau de l’usage, ici, je sais que “food” et “name” me retourneront des valeurs, parce que ce sont des noms, et je sais que “eat” exécutera une action, parce que c’est un verbe.

Qu’en est-il en PHP? Le même script s’écrirait :

< ?php
class Person 
{
  public    $food;
  protected $firstname;
  protected $lastname;
 
  public function __construct()
  {
    $this->food       = 10;
    $this->firstname  = 'John';
    $this->lastname   = 'Doe';
  }
 
 
  public function eat()
  {
    $this->food -= 1;
    return true;
  }
 
 
  public function getName()
  {
    return $this->firstname . ' ' . $this->lastname;
  }
 
 
  public function setName( $fullname )
  {
    $parts = preg_split( '/ /', $fullname, 2 );
    $this->firstname = $parts[0];
    $this->lastname  = $parts[1];
    return $fullname;
  }
}
 
$michel = new Person();
$michel->setName( 'Michel Dupont' );   
$michel->food;                         // => 10
$michel->eat();                        // => true
$michel->getName();                    // => 'Michel Dupont'

Nous voyons ici que l’implémentation est clairement visible. “food” est un attribut, “eat”, “setName” et “getName” sont des méthodes. L’astuce, chez PHP, est de transformer un nom en verbe par l’emploi des setters et des getters ( setName() et getName() ) pour justifier l’appel d’une méthode. Néanmoins, rien ne justifie le fait que je doive exécuter une action sur une Person pour avoir son nom. Il s’agit d’une valeur et cela ne me regarde pas, à l’usage, de savoir comment ce nom a été retrouvé.

Suggestion d’une implémentation

Dans l’extension framework que j’ai faite pour Typolight, j’ai généralisé l’emploi d’un design différent pour répondre à ce problème. En voici un exemple :

< ?php
class Person 
{
  public    $food;
  protected $firstname;
  protected $lastname;
  protected $_cache      = array();
  protected $_uncachable = array();
 
 
  public function __construct()
  {
    $this->food       = 10;
    $this->firstname  = 'John';
    $this->lastname   = 'Doe';
  }
 
 
 
  /**
   * Check if a getter method exists
   *
   * @param string  the attribute name
   * @return mixed
   */
  public function __get( $key )
  {
    $firstLetter = substr( $key, 0, 1 );
    $rest        = substr( $key, 1 );
    $getter      = 'get' . strtoupper( $firstLetter ) . $rest;
 
    if ( method_exists( $this, $getter ) )
    {
      if ( array_key_exists( $key, $this->_cache ) and ! in_array( $key, $this->_uncachable ) )
      {
        return $this->_cache[ $key ];
      }
 
      $result = $this->$getter();
      if ( ! in_array( $key, $this->_uncachable ) )
      {
        $this->_cache[ $key ] = $result;
      }
 
      return $result;
    }
 
    throw new Exception( "Unknown attribute" );
  }
 
 
 
  /**
   * Check if a setter method exists
   *
   * @param string  the attribute name
   * @param string  the attribute value
   * @return mixed
   */
  public function __set( $key, $value )
  {
    $firstLetter  = substr( $key, 0, 1 );
    $rest         = substr( $key, 1 );
    $setter       = 'set' . strtoupper( $firstLetter ) . $rest;
 
    if ( method_exists( $this, $setter ) )
    {
      $this->_cache[ $key ] = $this->$setter( $value );
    }
 
    else
    {
      $getter = 'get' . strtoupper( $firstLetter ) . $rest;
      if ( method_exists( $this, $getter ) )
      {
        $this->_cache[ $key ] = $value;
        return true;
      }
    }
 
    throw new Exception( "Unknown attribute" );
  }
 
 
  public function eat()
  {
    $this->food -= 1;
    return true;
  }
 
 
  public function getName()
  {
    return $this->firstname . ' ' . $this->lastname;
  }
 
 
  public function setName( $fullname )
  {
    $parts = preg_split( '/ /', $fullname, 2 );
    $this->firstname = $parts[0];
    $this->lastname  = $parts[1];
    return true;
  }
}
 
 
// Nous pouvons maintenant faire ceci :
$michel = new Person();
$michel->name = 'Michel Dupont';  
$michel->food;                    // => 10
$michel->eat();                   // => true
$michel->name;                    // => 'Michel Dupont'

Ainsi, en utilisant les méthodes magiques __set() et __get(), nous pouvons rétablir le respect de la blackbox. Lorsque $michel->name est exécuté, __get() est appelé ( puisqu’il n’existe pas d’attribut $name ) et vérifie s’il existe une méthode getName().

En outre, cela permet d’ajouter un système de cache. La prochaine fois que j’appellerai $michel->name, la valeur précédente sera directement retournée plutôt que de devoir executer la méthode à nouveau. Si je veux éviter ce comportement, il me suffit d’appeler directement la méthode en faisant $michel->getName(), et le nom sera recalculé.

Bien entendu, mettre en place un tel mécanisme n’a pas de sens pour une petite classe isolée. J’ai employé personnellement ce mécanisme pour la couche modèle et la couche controller de mon extension. Cela est particulièrement intéressant pour les modèles, qui doivent se comporter de la manière la plus naturelle possible et qui font régulièrement des requêtes sur la base de donnée. Avec un tel mécanisme vous pouvez, dans le cadre d’un framework MVC, utiliser autant de fois que vous le voulez vos modèles dans vos vues de manière intuitive et sans vous soucier de savoir si cela va exécuter une requête sql ou non.

Le MVC, c’est quoi?

Pour ceux qui ne sont pas familiers à la notion de MVC, récapitulons brièvement. MVC est un acronyme pour : Model, View, Controller ( en français, ça marche bien aussi ). Il s’agit d’un design pattern qui structure une application selon trois tâches :

• Le traitement des données ( Modèles )
• La présentation des données ( Vues )
• La logique qui détermine quelles données associer à quelle présentation ( Contrôleurs )

Typiquement, dans une application web, les modèles sont tous les calculs faits sur la base de donnée ; les vues sont les fichiers contenant le html ( ou autre, par exemple la structure d’un email ) ; les contrôleurs sont ce qui gèrent les requêtes ( POST, GET, etc ), leurs paramètres, et décident quels modèles utiliser et quelles variables fournir aux vues.

La couche modèle est en général gérée par un ORM ( Object Relational Mapping ). Celui-ci permet de manipuler la base de donnée sans faire soi-même de pénibles requêtes SQL. Si par exemple j’ai dans ma base de donnée une table posts avec des champs id, name, content et author, j’aurai une classe Post, héritant de Model, qui me permettra de manipuler les entrées de la base de donnée comme des objets. Voici un exemple de PHP fictif qui illustre la manipulation d’un modèle :

// récupérer l'entrée de la tables posts qui à l'id 10
$post = Post::find( 10 );
 
// retrouver son attribut "name"
echo $post->name;
 
// le modifier
$post->name = 'an other name';
 
// sauvegarder le changement dans la base de donnée
$post->save();
 
// récupérer tous les posts dans un array
$posts = Post::findAll();

On peut ensuite utiliser ce array dans une vue, avec par exemple :

<ul id="posts">
  < ?php foreach ( $posts as $post ) : ?>
  <li><a href="post-<?php echo $post->id ?>">< ?php echo $post->name ?></a>, by < ?php echo $post->author ?></li>
  < ?php endforeach ?>
</ul>

Dans Typolight, les vues sont les templates et les contrôleurs sont les FrontendModule et BackendModule. Il n’y a malheureusement pas d’équivalence pour la couche modèle, et les données sont généralement retrouvées en remplissant les contrôleurs de requêtes SQL, ce qui rend la base de donnée pénible à utiliser et encombre les contrôleurs.

Comment utiliser une couche modèle dans Typolight?

Heureusement, une couche modèle existe belle et bien. Le fichier est TL_ROOT/system/libraries/Model.php . Ce fichier dispose des méthodes de base d’une couche modèle, mais il semble avoir été sabordé en route. En effet, c’est un singleton ( ce qui signifie qu’un seul objet de cette classe peut exister en même temps ). Il a en fait été pensé pour ne servir qu’aux classes User, BackendUser et FrontendUser, permettant de gérer l’utilisateur actuellement loggé.

Il n’y a en fait qu’une simple chose à faire pour rendre une couche modèle utilisable dans Typolight : créer une classe qui descend de Model et rendre publique sa méthode __construct(). C’est par exemple la méthode choisie par les développeurs de Isotope, ou par ma propre extension framework.

Nous allons reprendre la base du précédent tutoriel. Nous avions deux tables SQL : tl_filiere_services et tl_filiere_filiales. Nous allons donc faire deux classes de modèles : Service et Filiale.

< ?php if (!defined('TL_ROOT')) die('You can not access this file directly!');
 
/**
 * TYPOlight webCMS
 * Copyright (C) 2005 Leo Feyer
 *
 * This program is free software: you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation, either
 * version 2.1 of the License, or (at your option) any later version.
 * 
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 * Lesser General Public License for more details.
 * 
 * You should have received a copy of the GNU Lesser General Public
 * License along with this program. If not, please visit the Free
 * Software Foundation website at http://www.gnu.org/licenses/.
 *
 * PHP version 5
 * @copyright  
 * @author    
 * @package    
 * @license    
 * @filesource
 */
 
 
/**
 * Class Service
 *
 * @copyright  
 * @author     
 * @package    Model
 */
 
class Service extends Model
{
  protected $strTable = 'tl_filiere_services';
 
  public function __construct()
  {
    parent::__construct();
  }
}

< ?php if (!defined('TL_ROOT')) die('You can not access this file directly!');
 
/**
 * TYPOlight webCMS
 * Copyright (C) 2005 Leo Feyer
 *
 * This program is free software: you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation, either
 * version 2.1 of the License, or (at your option) any later version.
 * 
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 * Lesser General Public License for more details.
 * 
 * You should have received a copy of the GNU Lesser General Public
 * License along with this program. If not, please visit the Free
 * Software Foundation website at http://www.gnu.org/licenses/.
 *
 * PHP version 5
 * @copyright  
 * @author    
 * @package    
 * @license    
 * @filesource
 */
 
 
/**
 * Class Filiale
 *
 * @copyright  
 * @author     
 * @package    Model
 */
 
class Filiale extends Model
{
  protected $strTable = 'tl_filiere_services';
 
  public function __construct()
  {
    parent::__construct();
  }
}

Et c’est tout. Nous disposons maintenant de tout ce qu’il faut pour trouver une entrée, récupérer la valeur de ses champs, enregistrer ses changements ou l’effacer. Par exemple :

// crée un objet service
$service = new Service();
 
// retrouver l'entrée qui a l'id 10
$service->findBy( 'id, 10 );
 
// retrouve l'attribut 'name'
echo $service->name;
 
// modifie l'attribut 'name'
$service->name = 'new service';
 
// enregistre les modifications dans la base de donnée
$service->save();
 
// efface l'entrée
$service->delete();

Nous pouvons maintenant manipuler simplement nos services et nos filiales sans avoir à écrire de fastidieuses requêtes SQL.

Mais ce n’est pas tout ce à quoi sert un modèle. Pour respecter le design pattern, il faut que toute manipulation de donnée soit faite dans le modèle. C’est son rôle, après tout. Dans le monde de Ruby on Rails, il y a même une devise : “thick models, thin controllers” ( modèles gros et contrôleurs minces ). L’idée est que puisque les modèles gèrent les données et que, précisément, un site est d’abord une question de données, c’est aux modèles de faire la majeure partie du travail. Il y a là un partie pris ( comme toujours avec rails ), vous en penserez ce que vous voudrez. Néanmoins, il reste exact que les manipulations des données doivent être opérées par les modèles. Reste a définir la limite entre “traitement des données” et “contrôle d’une requête” :)

Prenons un exemple concret. Les services de nos filiales ont un prix. Disons que ce prix est hors taxe. Il va me falloir, à un moment ou un autre, calculer le prix TTC pour un service. C’est ici typiquement une méthode qui doit résider dans le modèle Service. Comme nous sommes insouciants, nous allons considérer que les taxes sont fixes et que nous pouvons considérer qu’elles sont de 20% ( dans un cas réel, il faudrait rendre cette valeur configurable en backend ). Voici la méthode que nous allons rajouter dans la classe Service :

public function ttc()
{
  $ttc = $this->price + ( $this->price * 0.2 );
  return $ttc;
}

Désormais, dans le template qui affiche un service, nous n’aurons plus qu’à faire :

<p>Prix TTC : < ?php echo $this->service->ttc() ?></p>

( nous verrons dans un prochain tutoriel comment passer des variables à un template ).

Ce que la classe Model de Typolight ne permet pas

Aujourd’hui, les ORM des frameworks permettent toutes sortes de raffinements, telle que les associations, les validations, finders et autres.

Nos filiales ont des services. Nous voudrions, avec un objet $filiale, pouvoir faire $filiale->services() pour avoir la liste des services de cette filiale. C’est ce que permettent de faire les associations, par le biais de relations ( has many, has one, belongs to, many to many… ).

Nous voudrions aussi empêcher d’enregistrer les modifications sur une filiale si l’adresse mail fournie n’est pas dans un format valide ( par exemple “1HD23s” ). C’est le rôle des validations ( elle sont présentes dans les widgets backend, dans Typolight, mais pas dans la couche modèle ).

Enfin, nous voudrions pouvoir, par exemple, trouver toutes les filiales enregistrées depuis moins d’un mois. Ou simplement trouver toutes les filiales. Ou trouver la première filiale qui se trouve à Lyon. C’est le rôle des finders.

Avec la couche modèle de Typolight, vous devrez écrire ces méthodes vous-même. Si vous désirez avoir une solution générique pour ces problèmes relativement courant, je vous invite à utiliser ma classe EModel : http://github.com/oelmekki/typolight_framework/blob/master/system/modules/framework/EModel.php ( promis, la documentation arrive. Vous devrez pour l’instant lire le code ou me poser des questions pour comprendre comment s’en servir ).

Cela conclut mon article sur les modèles dans Typolight. Nous verrons ensuite les modules frontend.

Pour rappel, ce même conseil avait rejeté une version précédente en faisant appel à l’article 11 de la déclaration des droits de l’homme de 1789, estimant qu’un filtrage du réseau nuisait à la liberté d’expression. En effet, Internet permet de communiquer et empêcher l’accès à Internet revient à nuire à la « libre communication des pensées et des opinions ».

Le point contesté était qu’une privation de liberté ne pouvait se faire sans l’intervention d’un juge (comme c’est le cas par exemple pour une peine de prison).

Or la loi que vient d’approuver aujourd’hui le conseil constitutionnel valide la mise en place de procédures simplifiées. Qu’est-ce qu’une procédure simplifiée? Ce n’est pas une comparution immédiate, telle qu’elle existe déjà dans les cas les plus extrêmes, c’est bien pire : il s’agit d’un jugement “interne” et immédiat dans lequel la présence de l’accusé n’est pas nécessaire.

Judge Dredd, bienvenue en France.

Notons cependant, ce passage du rapport des discussions :

M. Christian Paul. Quelle désinvolture, monsieur le Rapporteur, dans votre présentation des choses ! Nous sommes tout autant que vous garants de la qualité de la loi et de la défense des libertés !

Notre amendement vise donc à supprimer le recours aux ordonnances pénales. Vous nous dites, madame la ministre, que l’avis du Conseil d’État ne mentionne pas les ordonnances pénales. Je vous crois bien sûr. Mais n’est-il pas un peu facile de vous prévaloir de cet avis quand il vous arrange, tout en refusant de nous donner connaissance de l’ensemble du document ?

Monsieur le rapporteur, en acceptant une procédure de masse, vous réduisez les droits de la défense et proposez une justice expéditive. Cela n’est pas supportable. L’ordonnance pénale est une procédure écrite et non contradictoire : l’auteur des faits n’est pas entendu par le juge.

Mme Martine Billard. Même argumentaire.

M. le rapporteur. Avis défavorable. L’ordonnance pénale est certes une procédure simplifiée, mais elle est assortie de toutes les garanties. La personne incriminée peut être entendue par le juge si elle le souhaite et demander à être jugée au cours d’une audience publique.

La Commission rejette les deux amendements.

Ainsi, si vous êtes un jour victime d’Hadopi, sachez que vous pouvez refuser la « procédure simplifiée » et exiger un procès loyal.

Notons encore (tout de même) qu’il est bien habile de rejeter les soupçons de privation des droits fondamentaux sur les même juges qui subissent déjà des attaques en règle pour être assujettis au pouvoir exécutif, qui se met en même temps à l’écart des critiques constitutionnelles. Chapeau bas pour Machiavel.

J’ai réalisé ce site avec Telly Delalande, pour le compte de la société Stick’Innov. Telly s’est occupé de la charte graphique et de l’intégration et j’ai pris en charge le développement moteur et la couche javascript. Pour distinguer le site de ses concurents et lui offrir une avance en référencement, nous avons fait le choix de réaliser l’application sans utiliser flash, au profit d’une interface javascript non obstrusive et dégradable.

Le site est realisé entièrement sous Typolight, autant pour les pages statiques, que pour les fonctions motrices et que pour la partie boutique. Il constitue une première démonstration publique de ce qui est faisable avec Typolight et mon extension framework. Cette application étant commerciale et réalisée pour un tiers, je ne peux en montrer le code, mais je peux démontrer certaines particularités du framework.

Les routes

Ce qui est peut-être le plus flagrant pour un utilisateur de Typolight est l’usage des routes. Prenons par exemple l’adresse : http://www.stick-innov.fr/adhesif/Abstrait-35/modele/105.html . Ceci est rendu possible en utilisant une “route”. Une route est caractérisée par une définition, reflétant l’url, qui lorsqu’elle correspond renvoie à une page donnée avec des paramètres donnés. Ces routes peuvent être configurées soit dans le config/config.php de votre module, soit en backend. Ici, je l’ai mise dans le config.php, ce qui donne :

array_insert( $GLOBALS[ 'TL_ROUTES' ], 0, array(
    "fr_adhesif"          => array(
      'route'         => 'adhesif/:theme/modele/:modele_id',
      'staticParams'  => array(
        'action' => 'index',
        'type'   => 'adhesif',
      ),
      'method'    => 'GET',
      'resolveTo'     => 'adhesif',
    ),
  )
);

La définition de la route est donc ici : ‘adhesif/:theme/modele/:modele_id’. :theme et :modele_id sont des variables. N’importe quelle valeur peut y être introduite et sera injectée dans les paramètres GET, récupérable avec $this->Input->get( ‘nom_du_param’ ).

L’option ’staticParams’ permet de rajouter arbitrairement des paramètres supplémentaires. Ici, ‘action’ est utilisé pour déterminer quelle action le contrôleur devra executer et ‘type’ est un paramètre que j’ai ajouté pour pouvoir ne faire qu’un contrôleur pour les trois types de produits.

L’option ‘method’ détermine quel verbe http accepte la route. En utilisant GET, nous interdisons l’usage de POST. Si nous utilisons un POST sur cette url, l’application répondra par une 404. Cela permet de router vers des actions ou pages différentes le GET et le POST sur une même url. Les options de ‘method’ sont : ‘GET’, ‘POST’ ou ‘GET/POST’. Ce dernier accepte les deux verbes.

Enfin, l’option ‘resolveTo’ indique la page vers laquelle la route redirige.

Cette route a un nom : ‘fr_adhesif’. Ce nom est utilisé pour générer une url à partir d’un nom, grâce à Route::compose(). Ainsi, si nous avons :

array_insert( $GLOBALS[ 'TL_ROUTES' ], 0, array(
    "product_list"          => array(
      'route'         => 'voir/les/produits',
      'staticParams'  => array(
        'action' => 'list',
      ),
      'method'    => 'GET',
      'resolveTo'     => 'produits',
    ),
  )
);

et que nous voulons faire un lien en utilisant cette route dans une vue, nous pouvons faire :

<a href="&lt;?php echo Route::compose( 'product_list' ) ?&gt;">Voir les produits</a>

ou, avec un insert tag :

<a href="{{Route::product_list}}">Voir les produits</a>

Il est ensuite possible de modifier la définition de la route sans avoir à modifier ce code.

Dans le cas de la première route que j’ai montrée, il y a également deux paramètres dynamiques, :theme et :modele_id. Ces paramètres sont ajoutés en passant un array associatif :

<a href="&lt;?php echo Route::compose( 'fr_adhesif', array( 'theme' =&gt; $theme-&gt;urlName, 'modele_id' =&gt; $modele-&gt;id ) ) ?&gt;">Voir les produits</a>

Enfin, les routes supportent l’internationalisation. Si nous avons :

array_insert( $GLOBALS[ 'TL_ROUTES' ], 0, array(
    "fr_adhesif"          => array(
      'route'         => 'adhesif/:theme/modele/:modele_id',
      'staticParams'  => array(
        'action' => 'index',
        'type'   => 'adhesif',
      ),
      'method'    => 'GET',
      'resolveTo'     => 'adhesif',
    ),
    "en_adhesif"          => array(
      'route'         => 'adhesive/:theme/model/:modele_id',
      'staticParams'  => array(
        'action' => 'index',
        'type'   => 'adhesif',
      ),
      'method'    => 'GET',
      'resolveTo'     => 'adhesif',
    ),
  )
);

nous pouvons utiliser :

<a href="&lt;?php echo Route::composeI18n( 'adhesif', array( 'theme' =&gt; $theme-&gt;urlName, 'modele_id' =&gt; $modele-&gt;id ) ) ?&gt;">Voir les produits</a>

La langue courante sera utilisée pour déterminer quelle route il faut suivre.

Un dernier point : l’ordre des routes importe. Il est possible d’avoir des urls auxquelles plusieurs routes correspondent, comme par exemple si on a “voir/produits/tous” et “voir/produits/:produit_id”. Si cela arrive, la première route rencontrée l’emportera.

Les contrôleurs

Les contrôleurs de Typolight ( ModuleQuelqueChose, héritant de FrontendModule ) sont pensés pour n’executer qu’une seule action, bien qu’il soit possible de les forcer. Il y a la méthode generate() qui sert à initialiser le module, et la méthode compile() qui passe les variables à la vue ( template, dans le vocabulaire Typolight ). L’extension framework rajoute une nouvelle classe : RoutedModule.

RoutedModule est pensé pour permettre de gérer facilement des actions multiples. Quand un RoutedModule est généré, il regarde s’il existe un paramètre GET ‘action’. S’il y en a un et qu’une méthode du même nom existe dans le module, celle-ci est appelée et la vue est automatiquement déclarée selon le schémas : ‘fe’ + nom du contrôleur + ‘_’ + nom de l’action. Sinon, la méthode index() est utilisée. Prenons l’exemple d’un contrôleur simple :

< ?php
 
class ControllerProduct extends RoutedModule
{
  protected $controller = 'products';
 
  /* List products */
  protected function index()
  {
    $product = new Product();
    $this->Template->products = $product->all;
  }
 
  /* Show a product */
  protected function show()
  {
    $product = new Product( $this->Input->get( 'product_id' ) );
    $this->Template->product = $product;
  }
 
  /* Create a new product */
  protected function create()
  {
    $product = new Product();
    $success = false;
 
    if ( $posted = $this->Input->post( 'product' ) )
    {
      $product->data = $posted;
 
      if ( $product->save() )
      {
        $success = true;
      }
 
      else
      {
        $this->Template->errors = $product->errors;
      }
    }
 
    $this->Template->product = $product;
    $this->Template->success = $success;
  }
 
  /* Update a product */
  protected function update()
  {
    $product = new Product( $this->Input->get( 'product_id' ) );
    $success = false;
 
    if ( $posted = $this->Input->post( 'product' ) )
    {
      if ( $product->update_attributes( $posted ) )
      {
        $success = true;
      }
 
      else
      {
        $this->Template->errors = $product->errors;
      }
    }
 
    $this->Template->product = $product;
    $this->Template->success = $success;
  }
 
  /* Delete a product */
  protected function delete()
  {
    $product = new Product( $this->Input->get( 'product_id' ) );
 
    if ( $product->delete() )
    {
      $this->redirect( Route::compose( 'product_list' ) );
    }
  }
}

Ceux qui se sont déjà servi de Ruby on Rails trouveront ici une note familière. Un utilisateur de Typolight pourra s’interroger sur les méthodes de Product. Product hérite en fait d’une autre classe du framework, EModel, que je traiterai une autre fois.

La première chose à faire est de donner un nom au contrôleur :

protected $controller = 'products';

Ensuite, on définit les différentes actions, et le paramètre GET ‘action’ déterminera lequel utiliser. La vue est automatiquement retrouvée d’après le nom du contrôleur et de l’action, comme je l’ai expliqué plus haut. Ici, on aura donc les vues : fe_products_index.tpl, fe_products_show.tpl, fe_products_create.tpl, fe_products_update.tpl et fe_products_delete.tpl .

RoutedModule offre de nombreuses autres fonctionalités, comme la possibilité de forcer l’action sans prendre en compte le paramètre d’action ( utile lorsqu’on a plusieurs RoutedModule dans une même page ), les getters et les setters, le cache, la gestion de json, et autres.

Si vous désirez essayer l’extension framework, vous pouvez la télécharger sur github. Je suis sur le point de publier mon troisième site l’utilisant et je le considère donc comme stable. La version 1.0 devrait sortir sous peu, après un cleanup de l’API et l’écriture de documentation.

Premier contact avec Typolight

Lorsque j’ai commencé mes activités de freelance, j’ai rencontré Telly Delalande, avec lequel je travaille régulièrement aujourd’hui. Telly est passionné par un CMS qui s’appelle Typolight, et dont il m’a assuré que c’était le meilleur CMS du monde. Son article a provoqué de telles réactions que j’ai décidé de lancer un troll moi aussi :)

Plus sérieusement, quand Telly m’a parlé de Typolight, j’ai accepté d’y jeter un oeil sans trop y croire. Premier constat : la documentation pour développeur est franchement lacunaire. Ok, qu’à cela ne tienne, “use the source, Luke”. J’ouvre le code pour essayer de comprendre comment tout cela fonctionne. Et là survient la première surprise : c’est bien codé, très bien codé, même. Il y a bien quelques vieilleries PHP-iennes, comme l’absence d’une vraie classe modèle ( la classe Model est un singleton destiné à mapper l’user courant ) et donc la profusion de requêtes sql dans les contrôleurs, mais le tout est propre est agréable à lire (sauf quelques fichiers plus anciens que les autres).

Je décide donc de faire un essai, et de mettre l’extensibilité à l’épreuve.

Les modules

L’extension de Typolight se fait comme dans beaucoup de CMS par l’ajout de modules. C’est donc assez banal, mais ça m’a plu sur le coup comme je venais juste d’essayer Merb dont le concept de modulabilité m’avait beaucoup intéressé ( oui, ca se fait très bien par l’intermédiaire des plugins dans Rails ou Symfony, mais permettre quelque chose et encourager son utilisation dans le design même d’une application sont deux choses aux résultats totalement différents ).

Les modules de Typolight sont donc des répertoires, placés dans system/modules/, et dans lesquels on peut mettre tous les fichiers nécessaires à une fonctionalité : modèles, contrôleurs, vues, css, js, fichier de migration db, fichier de configuration, etc.

Tout de suite, les limitations apparaissent. Un contrôleur dans un module ne gère qu’une seule action. Cependant, l’application étant entièrement orientée objet et pensée pour la surcharge, il m’a été facile de rajouter un classe de contrôleur permettant de gérer plusieurs actions. Tout comme il m’a été possible de rajouter une gestion de routes complètement arbitraire. Tout comme il m’a été possible de rajouter un classe que j’ai nommée EModel, et qui reprend les fonctionnalités classiques d’un modèle dans les frameworks : associations, validations, recherches selon paramètres, etc. Les bases étaient posées.

Utiliser Typolight comme un framework

Au fur et à mesure que mes besoins se précisaient, je rajoutais des fonctionnalités dans mon module “framework” qui me permettait de développer d’autres modules sans sentir de contraites CMS-iennes. Chaque fois, j’étais surpris d’avec quelle facilité c’était faisable. Bien sûr, il faut parcourir le code et le connaître un minimum dans son ensemble pour se permettre des modifications aussi conséquentes, mais c’est chaque fois la même surprise : c’est possible, et proprement en plus.

Aujourd’hui, j’utilise Typolight d’une manière très similaire à mon utilisation de Ruby on Rails. J’ai intégré cucumber et phpspec par l’intermédiaire d’un module “testing“, je fais donc du bdd, à base de user stories suivant lesquelles je déroule mes vues, contrôleurs, modèles et routes dans un soucis de réutilisabilité.

Je me retrouve donc dans la situation où l’argument de manque d’extensibilité est brisé.

Focus!

Dans le même mouvement, je me retrouve avec une pluvalue d’avantages qui relève de tous les inconvénients du framework quand on le compare au CMS : pas de perte de temps à coder des fonctionnalités banales que je ferai de toutes façons moins complètes que celles présentes dans un CMS, développées depuis des années.

C’est là qu’apparaît le point vraiment intéressant : le fait de pouvoir se permettre de se focaliser entièrement et uniquement sur les fonctionnalités spécifiques dont a besoin le client. Cela rend le développement rapide, beaucoup plus rapide. Recoupé avec la possibilité de faire du bdd, cela permet de produire des applications complètes, stables et peu coûteuses.

CMS ou framework? Les deux mon capitaine.

Cela m’amène à me poser la question : en quoi les CMS et les frameworks sont incompatibles? Les développeurs condamnent régulièrement les CMS pour leur manque d’extensibilité, mais il ne s’agit pas là d’une fatalité. C’est simplement un fait courant. Pour ma part, je dirais que le problème est surtout que beaucoup de CMS ont une base largement impérative, avec des require partout, l’OO n’apparaissant que dans la couche intermédiaire de l’application.

Un CMS pensé proprement (la notion de propreté voulant surtout dénoter la conformité aux bonnes pratiques du jour) peut très bien être extensible et peut même être pensé comme un framework.

Je n’irai pas dire que Typolight est ce CMS de rêve, mais il s’en rapproche incroyablement plus que les CMS dont nous avons l’habitude. Il rend en tous cas concrètement possible la fusion entre CMS et framework.

Peut-être est-ce à nous, développeurs, de proposer aujourd’hui des solutions CMS/Framework qui garantissent à la fois la possibilité d’être utilisées par des non-développeurs, de mettre en place en quelques minutes les fonctionnalités courantes, et d’offrir une extensibilité complète.

L’idée est de permettre de définir des règles de conversion pour importer le contenu d’une base de données dans une autre.

Dans son utilisation la plus simple, vous pouvez définir un ensemble de règle traduisant une base de donnée dans une autre, par exemple pour changer de moteur de blog ou encore pour faire passer les données d’une application externe dans un module de CMS.

Il est également possible de s’en servir pour synchroniser une base de donnée. Si les entrées de la base de donnée source ont une clef primaire dont la valeur existe déjà dans la base de donnée de destination, les donnée de cette seconde base de donnée seront mis à jour (en suivant les règles définies).

Enfin, et c’est peut-être le plus intéressant, le framework peut être utilisé pour fusionner des bases de données. Imaginez que vous avez deux applications qui ont fait leur vie chacune de leur côté. Vous aimeriez importer les utilisateurs de l’une dans l’autre, mais il existe déjà des utilisateurs qui ont le même id. Datamith vous permet d’insérer ces utilisateurs tout en préservant les associations (par exemple le champs user_id de la table post).

Pour en savoir plus, je vous invite à voir la page de Datamith, ainsi que sa documentation. Le code est téléchargeable sur Github.

Cette tendance conseille de faire une distinction nette entre le javascript et le HTML (comme on distingue le CSS du HTML) et de ne voir en javascript qu’un “bonus”, ne perturbant pas l’utilisation du site si javascript venait à être désactivé par le navigateur.

Concrètement, cela passe par un développement de l’application excluant javascript, puis par l’implémentation d’une surcouche comportementale (animations, événements) dans un fichier javascript externe.

Il est donc exclu d’inclure de larges portions de javascript dans une balise script du HTML ou de définir dans les balises des attributs d’événements, comme onclick ou onmouseover.

Le problème

Si je veux exécuter la fonction name_clicked() lorsque je clique sur le li avec la classe name, je ferai ainsi avec jQuery :

$( 'li.name' ).click( function(){ name_clicked(); });

Le problème ici est que je ne disposerai d’aucun moyen pour savoir si l’événement à bien été attaché à un li en particulier. Si je clique sur le li et que rien ne se passe, est-ce un problème avec name_clicked() ou avec l’événement? Le seul moyen que j’ai de vérifier est de parsemer mon code de alert() ou de console.log(), ce qui est généralement la solution de dernier recours.

La solution

Ryan Taylor a publié au début du mois une extension pour firebug qui permet de lister les événements ajoutés à un élément du DOM : firebugUJS.

Son fonctionnement est simple : vous inspectez un élément comme d’habitude et vous choisissez dans la fenêtre de l’inspecteur de styles du menu HTML l’onglet Events. Le code du callback de l’événement y est alors présenté.

Limitations

L’extension est encore à ses débuts de développement. Elle ne supporte pour l’instant principalement que jQuery et LowPro (un effort pour rendre Prototype moins obstrusif).

Après une semaine d’essai, j’en suis relativement satisfait (relativement, parce que c’est donc un début et que je passe les problèmes pour cette raison). Cette extension m’a déjà permis de gagner du temps, mais il y a encore quelques petites choses à corriger. En particulier, les événements n’apparaissent parfois pas (il faut recharger la page une seconde fois), une quantité importante d’informations plus utiles au développeur de l’extension qu’à moi apparaissent dans la partie console de firebug (ce qui est tout à fait excusable) et surtout : il m’est déjà arrivé deux fois de devoir désactiver l’extension parce qu’elle faisait planter une application qui utilisait lourdement javascript (piwik la première fois, l’ajout d’image dans wordpress la seconde fois).

Malgré cela, je continue d’utiliser cette extension car je fais un usage intensif des événements js et qu’elle m’a déjà permis de gagner beaucoup de temps. Si ce n’est pas votre cas, vous voudrez probablement attendre une version plus stable.

Une affaire à suivre, donc :)

Outre cela, il y a deux changements majeurs à noter, sur lesquels je voudrais revenir : Sizzle et .live() .

Le nouveau sélecteur Sizzle

John Resig nous avait déjà promis un nouveau moteur de sélection, Sizzle. Il promettait qu’il serait environ quatre fois plus rapide que celui des autres frameworks. Si on en croit les benchmarks publiés, ce n’est bien sûr pas le cas mais il n’en reste pas moins que ce moteur est plus rapide que les autres (et même beaucoup plus rapide que ceux de Prototype et Mootools).

Mais si cela est intéressant en soi, il y a une autre surprise derrière Sizzle, relativement inatendue et qui me semble d’un grand intérêt : il est réalisé de manière indépendante à jQuery et un appel à été lancé aux développeurs des autres frameworks pour y contribuer.

Le but de Sizzle est donc à la fois d’être d’une performance sans égal et de faire converger les énergies (l’un entraînant l’autre et vice-versa). C’est une belle initiative, nous verrons ce que cela donnera. On peut soit s’attendre à une incompatibilité totale de points de vues, et ce ne sera que “le sélecteur de jQuery qui peut aussi être utilisé tout seul”, soit s’attendre à voir émerger de ceci un standard sur la sélection en javascript. Time will tell…

Les Live events

C’est ici, à mon avis, le changement le plus excitant. Ce n’est pas tout à fait révolutionnaire parce qu’il ne s’agit en fait que d’intégrer le plugin Live Query de Brandon Aaron. Néanmoins, l’intégrer dans le core de jQuery va permettre d’en faire une utilisation plus naturelle et systématique (et ne plus se poser la question : “est-ce que ça vaut le coup que j’intègre un plugin juste pour cette petite fonctionalité que je veux rajouter?”).

En quoi consiste ces live events? Lorsque vous attachez un événement, vous l’attachez à un élément du DOM. Il faut donc que cet élément existe. Considérons ce bout de code :

$( '#menu li' ).click( function(){ $(this).une_fonction(); } );
$( '#menu' ).append( '
	<li>nouvelle option</li>
' );

Le nouveau li ici n’aura pas l’événement voulu attaché, seuls les autres executeront une_fonction() lorsqu’ils seront clickés.

Avec la fonction .live(), vous attachez l’événement non plus à un élément du DOM mais à un sélecteur (du moins, c’est l’impression donnée à l’usage, je passe l’implémentation technique). Ainsi, vous pouvez faire :

$( '#menu li' ).live( 'click', function(){ $(this).une_fonction(); } );
$( '#menu' ).append( '
	<li>;nouvelle option</li>
' );

Ici, le nouveau li répondra à l’événement défini. Pour annuler le live event, il suffit de passer .die() au même sélecteur. De plus, die() permet de choisir quel événement supprimer : tous, tous ceux qui correspondent à un type d’événement particulier ou encore tous ceux qui corespondent à une fonction particulière, soit :

$( '#content .popup' ).die() ;
$( '#content .popup' ).die( 'click' ) ;
$( '#content .popup' ).die( 'click', turnBackgroundDark ) ;

La où cela devient vraiment intéressant, c’est quand on combine live() avec la puissance des sélecteurs. Ainsi, imaginons qu’on ait une liste d’utilisateurs, certains en-ligne et d’autres hors-ligne, avec des fonctions ajax qui vérifient si les utilisateurs arrivent ou partent et modifient leur status en conséquence. Nous voulons que l’utilisateur puisse démarrer une conversation avec les utilisateurs en ligne :

$( 'ul#users li:contains( 'en-ligne' ) ).live( 'click', function(){ startChat(this); } );

L’événement click sera automatiquement ajouté et supprimé selon le status de l’utilisateur.

Dans ce tutoriel, nous verrons comment créer un module backend dans Typolight pour gérer des ressources simples. Par ressource, nous entendons une entité dotées d’attributs, stockées dans la base de donnée et avec laquelle l’application peut interagir. Les actions basiques que l’application peut accomplir sur ces ressources correspondent au paradigme CRUD : créer, lire, modifier, effacer. C’est précisément ces actions que recouvre un module backend.

Pré-requis:

• vous devez avoir des connaissances de base de PHP
• vous devez avoir des connaissances de base de MySQL (ou du moteur de db que vous utilisez)
• vous devez être à l’aise avec le fonctionnement de l’interface de Typolight

Il est fortement recommandé que vous réalisiez les différentes étapes en même temps que votre lecture de ce tutoriel.

Conception des ressources

La première étape est de se représenter clairement les ressources qu’on va utiliser. Cela offre l’avantage de pouvoir utiliser l’interface de création de module de Typolight pour écrire automatiquement le squelette des fichiers.

Pour le tutoriel, nous prendrons l’exemple suivant.

Nous réalisons un site pour une entreprise disposant de plusieurs filiales. L’entreprise propose de multiples services, et chaque filiale propose quelques uns de ces services. Un service, par ailleurs, peut être proposé par plusieurs filiales. De services et des filiales peuvent apparaître ou disparaître. Une filiale peut voir sa liste de services proposés se modifier.

Ceux qui ont l’habitude de travailler sur des ressources auront repéré ici une relation many_to_many ( généralement réalisée grâce à une table de jointure ) entre les filiales et les services. On peut aussi y voir une relation filiales has_many services, et c’est ce que nous utiliserons, car has_many est mieux supporté par Typolight ( on pourra en outre par la suite pallier à cette insuffisance en utilisant les modèles ).

Pour ceux qui n’ont pas l’habitude de travailler sur les relations, cela signifie simplement qu’il faudra, dans notre base de donnée, un attribut de filiales permettant de lister les ids des services concernés (c’est ainsi que Typolight procède), ce qui s’exprime par : une filiale has many (a plusieurs) services.

Les autres attributs étant plus simples, nous pouvons nous représenter l’allure de nos ressources. Nous aurons donc deux types de ressources, filiales et services avec les attributs suivants :

Filiales :

• nom
• adresse
• ville
• téléphone
• mail
• services

Services :

• nom
• description
• tarif

Cela nous suffit pour démarrer.

Création automatique du squelette du module

Afin de gagner du temps, nous utilisons le module “créateur de modules” présent dans la section “système” des menus de l’interface backend. Ce module permet de créer le squelette des fichiers dont vous aurez besoin par la suite.

Il est difficile de savoir exactement tous les fichiers dont on va avoir besoin, mais on peut ensuite dupliquer un fichier existant pour faire une nouvelle classe. Pour cette raison, je vous conseille de toujours créer un module frontend et les fichiers de langues, même si vous n’avez pour l’instant que la partie backend clairement en tête.

Une fois que vous avez renseigné les informations d’identification de l’extension, cochez “ajouter un module back-office”. Parmi les trois champs textes qui vous sont proposés, vous ne vous servirez la plupart du temps que du second.

Pour accélérer l’écriture d’un module backend, Typolight offre la possibilité d’utiliser des DCA ( Data Configuration Array ). Il s’agit en fait de tableaux PHP dont les différents éléments définissent la manière dont une table sql doit être représentée en back-office, et quelles opérations peuvent être réalisées dessus. Autrement dit : pour peu que vous traitiez des ressources, les DCA font tout le boulot.

Pour créer automatiquement les fichiers DCA relatifs à une table sql, et pour créer le fichier .sql de définition de cette table par la même occasion, donnez simplement le nom de cette table dans le champs “Tables du module back office” ( vous pouvez séparer plusieurs tables par des virgules ). Dans le cas de notre module, nous rentrons donc : “tl_filiere_services,tl_filiere_filiales”.

Le champs “Classes du module back office” permet de créer des modules écrit en PHP standard, si vous avez des besoins vraiment spécifiques que les DCA ne couvrent pas, ou si votre module n’implique pas des ressources. Le champs “Modèles du module back office” est utilisé pour créer les vues que ces modules emploieront ( généralement préfixé par “be_” ). Nous nous focalisons pour cette fois sur la gestion des ressources et nous n’avons donc pas besoin de ces deux champs, vous pouvez les laisser vide.

Comme précisé plus haut, nous allons aussi ajouter un module frontend, bien que nous ne nous en serviront pas pour l’instant. Le champs “Classes du module front office” concerne les contrôleurs. C’est généralement ce type de fichier qui concentre la plus grosse partie d’une extension. Les vues utilisées par ces contrôleurs sont définies dans “Modèles du module front office” ( il ne faut pas ici confondre le terme “modèle” avec le modèle de MVC, il s’agit en fait des vues ). Le champs “Tables du module front office” permet de lister des tables sql qui seront ajoutées dans la base de donnée, mais pour lesquelles des fichiers DCA ne seront pas créés. Nous créons donc, pour disposer ensuite du squelette, le contrôleur FiliereFrontend et la vue fe_filiere.

Une fois les informations de votre module complétées, sauvegarder et fermer, et créer les fichiers en cliquant sur l’icône correspondante.

Création de la déclaration SQL

Vous disposez maintenant des fichiers nécessaires, installés dans system/modules/. Nous allons commencer par nous occuper de la définition sql de nos ressources. Cela se fait dans le fichier config/database.sql du module.

Les champs `pid` et `sorting`, parmi les champs ajoutés automatiquement, ne nous serviront pas. Le premier sert à contenir l’id du parent, dans les relations de type belongs to. Le second est utilisé lorsque l’utilisateur doit pouvoir définir un ordre arbitraire, comme dans le cas des éléments de contenus ou des articles. Nous pouvons donc supprimer ces deux champs dans les deux déclarations (n’oubliez pas de supprimer la clef pid aussi).

Le champs `tstamp` est automatiquement mis à jour lorsque vous sauvegardez une ressource, avant de pouvoir retrouver la date de dernière modification. Il peut être utile de rajouter par ailleurs un champs `created_at`.

Nous pouvons maintenant commencer à ajouter nos propres champs.

Attention tricky : lorsque vous éditez les déclarations de table. Le script install.php est assez exigeant sur leur formatage. Si vous mettez des espaces en trop ou en moins, il continuera de vous dire obstinément que la base de donnée n’est pas à jour quand même elle le sera.

Vous devez déjà également vous faire une idée de quel type d’élément de formulaire concernera le champs. Voici quelques exemples :

input type text,
chemin de fichier:          varchar(255) NOT NULL default '',
textarea:                   text NULL,
checkbox:                   char(1) NOT NULL default '',
liste de checkboxes,
select multiple,
liste de input type text:   blob NULL,
date:                       int(10) unsigned NOT NULL default '0'
                            (les dates sont stockées sous forme de timestamp unix)

En reprenant la description des ressources que nous avons vue dans la première partie de ce tutoriel, les définitions sql seront donc :

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

--
-- Table `tl_filiere_services`
-- 
 
CREATE TABLE `tl_filiere_services` (
  `id` int(10) UNSIGNED NOT NULL AUTO_INCREMENT,
  `tstamp` int(10) UNSIGNED NOT NULL DEFAULT '0',
  `name` varchar(255) NOT NULL DEFAULT '',
  `description` text NULL,
  `price` varchar(255) NOT NULL DEFAULT '',
  PRIMARY KEY  (`id`)
) ENGINE=MyISAM DEFAULT CHARSET=utf8;
 
-- --------------------------------------------------------
 
--
-- Table `tl_filiere_filiales`
-- 
 
CREATE TABLE `tl_filiere_filiales` (
  `id` int(10) UNSIGNED NOT NULL AUTO_INCREMENT,
  `tstamp` int(10) UNSIGNED NOT NULL DEFAULT '0',
  `name` varchar(255) NOT NULL DEFAULT '',
  `city` varchar(255) NOT NULL DEFAULT '',
  `phone` varchar(255) NOT NULL DEFAULT '',
  `email` varchar(255) NOT NULL DEFAULT '',
  `services` blob NULL,
  PRIMARY KEY  (`id`)
) ENGINE=MyISAM DEFAULT CHARSET=utf8;

Le DCA

C’est ici que se fait la plus grosse partie du travail, dans le DCA des tables. Nous allons commencer par nous occuper du DCA de tl_filiere_filiales.

Un DCA est un énorme tableau PHP, composé de nombreux tableaux imbriqués ( ça vous rappelle des souvenirs? :) ). L’avantage majeure est de permettre de créer des modules très rapidement. L’inconvénient majeur est d’être particulièrement indébugable. La plupart du temps, une erreur dans le DCA se traduit par une erreur dans la classe DC_Table ou (pire encore) par rien du tout, sinon que “ça ne marche pas”, et les logs restent muets sur le problème. J’ai pris l’habitude de dire : “le truc génial dans les modules Typolight, c’est les DCA. Le truc horrible dans les modules Typolight, c’est les DCA.”. Dans les premiers temps, les DCA vous feront perdre plus de temps qu’en gagner, mais je trouve personnellement que ça en vaut la peine, tant tout est facilité une fois qu’on les a en main. Pour faire ses armes avec les DCA, le mieux à faire et de bien prendre soin de les générer par le créateur de module et de se référer aux nombreux DCA présents dans system/modules/backend/dca pour avoir des points de comparaison. Vous réaliserez bientôt à quel point Typolight est une application exigeante lorsqu’il s’agit de développer avec.

Vous trouverez des informations fort utiles dans la section développement de la documentation de Typolight ( en anglais ).

Voici une explication générale des principales clefs de premier niveau d’un DCA :
config: les options générales du module. De nombreux options différentes y sont regroupées : la détermination des tables parent et enfants, les callbacks lors des actions destructives sur les ressources, les limitations de ces opérations, etc.
list: la manières dont les ressources seront listées ( affichage de l’ensemble des ressources ). Selon quel(s) attribut(s) on les classe? Est-ce que c’est une simple liste? Un arbre? Quelles informations pour chaque ressource apparaissent dans cette liste? Quelles actions peuvent être exécutées? Y a-t-il un panneau de navigation? Si oui, que propose-t-il?
palettes,subpalettes: ces options concernent plus particulièrement la gestion d’une ressource isolée. Quels sont les différents champs qui seront éditables, et dans quel ordre seront-ils disposés? Certains champs ne doivent apparaître que si un autre champs a une valeur précise (on ne modifie pas la source d’un fichier si on n’a pas coché “ajouter un fichier”). Les subpalettes permettent de déterminer ces sections annexes du formulaire.
fields: le coeur du DCA. Si ‘palettes’ décident quels champs apparaîtront, ‘fields’ décide ce que seront ces champs. Un textarea? Un input text? Une liste de checkboxes?

Plusieurs options dans les DCA permettent de fournir les données en passant une fonction, sous la forme d’un tableau array( ‘classe’, ‘méthode’ ). Bien que la classe appelée puisse être n’importe quelle classe accessible à l’application, il est d’usage de rajouter une classe directement dans le fichier du DCA, en lui donnant le nom de la table sql concernée et en la faisant hériter de Backend. Cela fait particulièrement sens si la méthode en question n’est vraiment utile que dans le cadre du DCA, comme par exemple les méthodes servant à déterminer les informations présentées dans la liste des ressources.

Détermination des palettes

Puisque nous avons déjà commencé à penser les éléments de formulaires liés aux champs, nous allons commencer par la clef ‘palettes’ et la clef ‘fields’. Si vous comptez faire d’importantes modifications dans ‘config’ et ‘list’, leurs valeurs par défaut vous permettrons quand même de tester ‘fields’.

Le tableau de la clef  ‘palettes’ doit au moins comporter une clef ‘default’. Sa valeur est une chaîne de caractères représentant dans l’ordre les différents champs qui seront présentés, en utilisant le nom du champs dans la base de données. Dans notre DCA de tl_filiere_services, nous auront donc : ‘name;description,price;’. Les noms de champs peuvent être séparés par des virgules ou des points virgules. La différence est que le point virgule sépare des groupes, en traçant une ligne. C’est une notation qu’on retrouvera plusieurs fois dans Typolight.

Outre la clef ‘default’, il peut y avoir également une clef ‘__selector__’. Les selectors servent à modifier dynamiquement le formulaire de la ressource, selon les champs déclarés dans le tableau fourni en valeur de cette clef. Il y a deux types valides de sélecteurs : ceux dont le champs est représenté par une checkbox et les autres. Le sélecteur par checkbox sera une subpalette, le sélecteur normal sera plusieurs nouvelles palettes.

Dans le premier cas, le sélecteur est associé à une subpalette, qui liste les éléments à rajouter. Dans le second cas, une palette est ajoutée pour chaque valeur que peut prendre le champs concerné. Il est en outre possible de faire des palettes propres à plusieurs sélecteurs string en donnant au nom de la palette la liste des valeurs concaténées, comme par exemple la palette “flashexternal” de tl_module, pour type => flash et source => external. C’est assez complexe, mais on ne s’en sert heureusement pratiquement jamais.

Bien souvent, la seule palette “default” suffit, et c’est d’ailleurs ce que nous allons utiliser. Nous pouvons supprimer la clef “subpalettes”. La clef “palettes”, elle, devient :

'palettes' => array
(
  'default' => 'name;description,price;'
),

Définition des champs

Nous avons donc ici trois champs à définir. Chaque champs est défini par un tableau associatif dont la clef la plus importante est ‘inputType’. Vous trouverez une liste des clefs utilisables dans la documentation pour développeurs. Encore une fois, vous êtes fortement invités à aller voir les DCA déjà existants pour vous en inspirer.

La clef ‘label’ servira à déterminer, dans les fichiers de langue, le texte présenté comme nom du champs et la description qui en est faite si l’utilisateur backend est en mode explain.

La clef ‘exclude’ permet de désactiver par défaut le champs pour les non-administrateurs. Il faut manuellement leur définir des droits pour ce champs pour qu’ils puissent le modifier. C’est une bonne pratique que de définir cette propriété sur tous les champs, pour être sûr que la base de donnée ne soit pas accessible involontairement.

La clef ‘inputType’ définit quel type d’élément de formulaire sera utilisé. Les éléments de formulaire appartiennent à la classe Widget. Vous pouvez utiliser tous ceux qui sont déjà définis dans d’autres modules ( notamment dans system/modules/backend ) ou en créer vous même. Les ‘inputTypes’ les plus fréquents sont : ‘text’, ‘textarea’, ’select’, ‘checkbox’, ‘radio’…

La clef ‘eval’ permet de préciser le fonctionnement du widget. On peut aussi passer l’option “mandatory” pour rendre le champs obligatoire, l’option “rte” pour rajouter un éditeur wysiwyg sur un textarea, “rgxp” pour valider un champs text selon une expression régulière ( malheureusement prédéfinie ), etc. Vous trouverez une liste des options possible ici : http://dev.typolight.org/wiki/DevelopmentEvaluation .

Voici ce que nous aurons pour tl_filiere_services

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

'fields' => array
(
  'name' => array
  (
    'label'        => &$GLOBALS['TL_LANG']['tl_filiere_services']['name'],
    'exclude'      => true,
    'inputType'    => 'text',
    'eval'         => array('mandatory'=>true, 'maxlength'=>255)
  ),
  'description' => array
  (
    'label'        => &$GLOBALS['TL_LANG']['tl_filiere_services']['description'],
    'exclude'      => true,
    'inputType'    => 'textarea',
    'eval'         => array('rte' => 'tinyMCE' )
  ),
  'price' => array
  (
    'label'        => &$GLOBALS['TL_LANG']['tl_filiere_services']['price'],
    'exclude'      => true,
    'inputType'    => 'text',
    'eval'         => array('mandatory'=>true, 'maxlength'=>255, 'rgxp' => 'digit')
  )
)

‘name’ est donc un input de type text, obligatoire avec 255 caractères maximum, ‘description’ est un textarea avec un éditeur wysiwyg et price est un input de type text, obligatoire, de 255 caractères maximum composés uniquement de chiffres.

Premiers tests, config.php

À ce point, il est bon de s’assurer que tout fonctionne correctement. Commencez par lancer install.php pour mettre à jour la base de donnée.

Pour activer un module, il faut le charger dans le tableau de configuration globale par l’intermédiaire de config/config.php . Nous voulons pour l’instant juste tester le module backend de tl_filiere_services, nous rajoutons donc une entrée à $GLOBALS[ 'BE_MOD' ] dans la catégorie ‘content’ ( cela aura pour effet de faire apparaître le module dans la section “contenu” de la sidebar du backend ).

$GLOBALS[ 'BE_MOD' ][ 'content' ][ 'tl_filiere_services' ] = array(
  'tables' => array( 'tl_filiere_services' )
);

Le fait d’utiliser la clef ‘tables’ stipule que nous allons utiliser des DCA. La valeur est un tableau pour qu’il soit possible de préciser plusieurs tables dans le cas d’une présentation sous la forme parent/enfants.

D’autres options peuvent être précisées, comme vous le voyez dans les commentaires du fichier créé automatiquement. ‘icon’ est le chemin de l’icône qui sera utilisé à côté du lien dans la sidebar du backend, ’stylesheet’ et ‘javascript’ permettent de rajouter des styles et scripts persos. ‘callback’ permet de définir la classe de module backend qui sera utilisé lorsqu’on décide de faire un module sans DCA et ‘key’ permet de rajouter ses actions personnalisées ( l’équivalent de ['list']['operations'] dans un DCA ) si on veut utiliser autre chose que le CRUD par défaut.

Nous pouvons maintenant faire un premier test, en nous rendant dans l’interface backend. Si tout se passe bien, vous voyez apparaître “tl_filiere_services” dans la section “contenu” de la sidebar. Nous donnerons un nom plus correct en utilisant les fichiers de langues. De même, dans la liste des ressources, le bouton “nouveau” n’a pas de label. Cela sera déterminé également dans les fichiers de langues, nous allons nous contenter de vérifier pour l’instant que le CRUD fonctionne correctement.

Créez quelques ressources, éditez-les, effacez-les. Puis passez à la suite quand vous serez assuré que tout fonctionne.

Paramétrage général du DCA

Nous allons ensuite revenir sur le fichier DCA de tl_filiere_services. Nos ressources étant relativement simples, nous n’avons pas besoin de rajouter quoi que ce soit dans ‘config’. Au pire, vous aurez besoin des callbacks. Il s’agit de tableau à deux entrées, classe et méthode, qui seront appelé lors d’événements particuliers ( save, delete, load ). Cela peut être utile si par exemple vous voulez vous assurer qu’une url est atteignable lorsque vous la sauvegardez, ou encore que vous voulez effacer un fichier uploadé propre à la ressource lorsque vous l’effacez. Les autres options, pour la plupart, concernent les relations parent/enfant ou à des besoins très spécifiques et rares ( je vous laisse vous référer au guide du développeur pour des informations complètes ).

La clef ‘list’ est la seconde clef la plus important du DCA. Elle vous permet de définir comment la liste des ressources sera présentée. ’sorting’ et ‘label’ sont d’une importance cruciale pour cela. ‘global_operations’ et ‘operations’ n’ont la plupart du temps pas à être changée, et offrent les actions classiques de CRUD.

vous trouverez la documentation de la clef ‘list’ ici :

’sorting’ sert à déterminer comment les ressources seront classées. Le mode permet de choisir si les ressources seront simplement placées les unes à la suite des autres, ou par groupe selon leur parent, ou par une ordre défini par l’utilisateur (requiert le champs ’sorting’ dans la table) ou encore sous forme d’arbre…

‘flag’ permet de définir un second niveau de classement : ascendant, descendant, alphabétique, par date… Le classement sera effectué sur le ou les champs indiqués dans le array de la clef ‘fields’.

Si vous désirez ajouter un panneau de navigation, c’est également ici que cela se fait ( un exemple de ceci sera donnée dans le DCA de tl_filiere_filiales ).

La clef ‘label’ permet de déterminer quelles informations seront présentées pour chaque ressource dans la liste des ressources. Les champs montrés seront déterminés par ‘fields’ et leur formatage sera déterminé par ‘format’, qui prend le même type de string que printf(). Si vous désirez quelque chose de plus complexe, en particulier si vous avez besoin de manipuler les données des champs plutôt que de les afficher tels quels, vous pouvez utiliser un callback avec ‘label_callback’. La méthode utilisées devra renvoyer un string, qui sera ajouté à la suite du texte déjà fourni par format et fields, si précisé.

tip: Si vous devez fournir beaucoup de contenu, vous pouvez limiter la taille d’un block en lui donnant comme classes limit_height et hN, où N est la hauteur en pixel. Cela aura pour effet de mettre une flèche clickable pour afficher l’ensemble du contenu et de le réduire à la taille choisi par défaut.

Dans notre cas, nous allons classer les services par ordre alphabétique en montrant simplement leur nom. Étant donné que les services ont peu d’informations et que celles-ci sont relativement uniques, nous n’avons pas vraiment besoin de l’opération “copy” et nous la supprimons donc.

Voici donc notre DCA au final :

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89

$GLOBALS['TL_DCA']['tl_filiere_services'] = array
(
  // Config
  'config' => array
  (
    'dataContainer'    => 'Table',
    'enableVersioning' => true
  ),
 
  // List
  'list' => array
  (
    'sorting' => array
    (
      'mode'    => 1,
      'fields'  => array('name'),
      'flag'    => 1
    ),
    'label' => array
    (
      'fields' => array('name'),
      'format' => '%s'
    ),
    'global_operations' => array
    (
      'all' => array
      (
        'label'       => &$GLOBALS['TL_LANG']['MSC']['all'],
        'href'        => 'act=select',
        'class'       => 'header_edit_all',
        'attributes'  => 'onclick="Backend.getScrollOffset();"'
      )
    ),
    'operations' => array
    (
      'edit' => array
      (
        'label' => &$GLOBALS['TL_LANG']['tl_filiere_services']['edit'],
        'href'  => 'act=edit',
        'icon'  => 'edit.gif'
      ),
      'delete' => array
      (
        'label'       => &$GLOBALS['TL_LANG']['tl_filiere_services']['delete'],
        'href'        => 'act=delete',
        'icon'        => 'delete.gif',
        'attributes'  => 'onclick="if (!confirm(\'' . $GLOBALS['TL_LANG']['MSC']['deleteConfirm'] . '\')) return false; Backend.getScrollOffset();"'
      ),
      'show' => array
      (
        'label' => &$GLOBALS['TL_LANG']['tl_filiere_services']['show'],
        'href'  => 'act=show',
        'icon'  => 'show.gif'
      )
    )
  ),
 
  // Palettes
  'palettes' => array
  (
    'default' => 'name;description,price;'
  ),
 
  // Fields
  'fields' => array
  (
    'name' => array
    (
      'label'       => &$GLOBALS['TL_LANG']['tl_filiere_services']['name'],
      'exclude'     => true,
      'inputType'   => 'text',
      'eval'        => array('mandatory'=>true, 'maxlength'=>255)
    ),
    'description' => array
    (
      'label'      => &$GLOBALS['TL_LANG']['tl_filiere_services']['description'],
      'exclude'    => true,
      'inputType'  => 'textarea',
      'eval'       => array('rte' => 'tinyMCE' )
    ),
    'price' => array
    (
      'label'      => &$GLOBALS['TL_LANG']['tl_filiere_services']['price'],
      'exclude'    => true,
      'inputType'  => 'text',
      'eval'       => array('maxlength'=>255, 'rgxp' => 'digit')
    )
  )
);

tl_filiere_filiales

Nous allons maintenant pouvoir nous occuper du DCA de tl_filiere_filiales :

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115

$GLOBALS['TL_DCA']['tl_filiere_filiales'] = array
(
  // Config
  'config' => array
  (
    'dataContainer'    => 'Table',
    'enableVersioning' => true
  ),
 
  // List
  'list' => array
  (
    'sorting' => array
    (
      'mode'        => 1,
      'fields'      => array('name'),
      'flag'        => 1,
      'panelLayout' => 'filter,search,limit;'
    ),
    'label' => array
    (
      'fields' => array('name', 'city'),
      'format' => '%s @ %s'
    ),
    'global_operations' => array
    (
      'all' => array
      (
        'label'       => &$GLOBALS['TL_LANG']['MSC']['all'],
        'href'        => 'act=select',
        'class'       => 'header_edit_all',
        'attributes'  => 'onclick="Backend.getScrollOffset();"'
      )
    ),
    'operations' => array
    (
      'edit' => array
      (
        'label' => &$GLOBALS['TL_LANG']['tl_filiere_filiales']['edit'],
        'href'  => 'act=edit',
        'icon'  => 'edit.gif'
      ),
      'copy' => array
      (
        'label' => &$GLOBALS['TL_LANG']['tl_filiere_filiales']['copy'],
        'href'  => 'act=copy',
        'icon'  => 'copy.gif'
      ),
      'delete' => array
      (
        'label'      => &$GLOBALS['TL_LANG']['tl_filiere_filiales']['delete'],
        'href'       => 'act=delete',
        'icon'       => 'delete.gif',
        'attributes' => 'onclick="if (!confirm(\'' . $GLOBALS['TL_LANG']['MSC']['deleteConfirm'] . '\')) return false; Backend.getScrollOffset();"'
      ),
      'show' => array
      (
        'label' => &$GLOBALS['TL_LANG']['tl_filiere_filiales']['show'],
        'href'  => 'act=show',
        'icon'  => 'show.gif'
      )
    )
  ),
 
  // Palettes
  'palettes' => array
  (
    'default' => 'name;city,phone,email;services;'
  ),
 
  // Fields
  'fields' => array
  (
    'name' => array
    (
      'label'     => &$GLOBALS['TL_LANG']['tl_filiere_filiales']['name'],
      'exclude'   => true,
      'search'    => true,
      'inputType' => 'text',
      'eval'      => array('mandatory'=>true, 'maxlength'=>255)
    ),
    'city' => array
    (
      'label'     => &$GLOBALS['TL_LANG']['tl_filiere_filiales']['city'],
      'exclude'   => true,
      'filter'    => true,
      'search'    => true,
      'inputType' => 'text',
      'eval'      => array('mandatory'=>true, 'maxlength'=>255)
    ),
    'phone' => array
    (
      'label'      => &$GLOBALS['TL_LANG']['tl_filiere_filiales']['phone'],
      'exclude'    => true,
      'inputType'  => 'text',
      'eval'       => array('mandatory'=>true, 'maxlength'=>255)
    ),
    'email' => array
    (
      'label'      => &$GLOBALS['TL_LANG']['tl_filiere_filiales']['email'],
      'exclude'    => true,
      'search'     => true,
      'inputType'  => 'text',
      'eval'       => array('mandatory'=>true, 'maxlength'=>255, 'rgxp'=>'email')
    ),
    'services' => array
    (
      'label'      => &$GLOBALS['TL_LANG']['tl_filiere_filiales']['services'],
      'exclude'    => true,
      'inputType'  => 'checkboxWizard',
      'foreignKey' => 'tl_filiere_services.name',
      'eval'       => array('multiple'=>true)
    )
  )
);

Nous retrouvons ici en substance ce que nous avons déjà vu avec le DCA précédent. Les quatre premières champs sont de type texte. Le champs ‘email’ est validé par une expression régulière s’assurant que cette adresse est légale.

Le champs ’services’ est de type ‘checkboxWizard’. Il s’agit d’un widget propre à Typolight qui crée une liste de checkboxes. Leur valeur est déterminée par la clef ‘foreignKey’. Cette clef sert à définir une table et un champs. Une checkbox sera créée pour chaque entrée de cette table. Le label de la checkbox sera la valeur du champs indiqué et la valeur de la checkbox sera l’id de l’entrée. Les valeurs des checkboxes sur ON seront stockée en tant que array serialisé dans la base de donnée ( d’où le type blob pour `services` dans la définition sql de la table tl_filiere_filiales ).

Si une filiale n’avait dû avoir qu’un seul service, nous aurions pu utiliser ’select’ comme inputType plutôt que checkboxWizard, pour utiliser un select classique. Un select peut se référer de la même manière à une table et l’un de ses champs pour déterminer sa valeur et son contenu texte. Il est possible également de lui passer arbitrairement des valeurs avec la clef ‘options’, ou d’utiliser un callback avec ‘options_callback’.

Nous voyons également ici l’usage de panelLayout, présent dans ['list']['sorting']. Quatre options sont disponibles : search, sort, filter et limit. Vous pouvez préciser leur disposition en les plaçant dans l’ordre que vous voulez, dans un string. Les séparer par des virgules les met les uns à la suite des autres, utiliser un point virgule fait passer à la ligne.

Pour déterminer qu’un champs peut être filtré, il suffit de placer ‘filter’ => true dans sa déclaration. De même, pour déterminer qu’il peut être cherché, il faut y mettre ’search’ => true. ‘limit’ ajoute un pager à la page.

Retour sur le fichier de configuration.

Il faut maintenant ajouter ce nouveau module dans le fichier de configuration. Comme nous en avons deux, il peut être intéressant de les grouper. Plutôt que de simplement les mettre dans la section ‘Contenu’, nous allons créer une nouvelle section, ‘Filière’. Nous utiliserons le nom du module ( dans mon cas, ‘filiere’ ) dans le fichier de configuration, et le fichier de langue se chargera d’y attribuer la valeur ‘Filière’ pour le français.

$GLOBALS[ 'BE_MOD' ][ 'filiere' ] = array
(
  'tl_filiere_services' => array
  (
    'tables' => array( 'tl_filiere_services' )
  ),
  'tl_filiere_filiales' => array
  (
    'tables' => array( 'tl_filiere_filiales' )
  ),
);

Cela remplace donc ce que nous avions mis dans le fichier de configuration précédemment. La nouvelle section sera ajoutée à la fin de la liste. Il est possible de la placer plus précisément avec la fonction array_insert(). Si nous avions voulu le mettre en première position, cela aura donné :

array_insert( $GLOBALS[ 'BE_MOD' ], 0, array
  (
    'filiere'  => array
    (
      'tl_filiere_services' => array
      (
        'tables' => array( 'tl_filiere_services' )
      ),
      'tl_filiere_filiales' => array
      (
        'tables' => array( 'tl_filiere_filiales' )
      ),
    )
  )
);

Écriture des fichiers de langue

Il ne reste plus qu’à créer les fichiers de langue. Si vous avez utilisé le créateur de modules et que vous avez spécifié les langues que vous souhaitez maintenir, les fichiers ont été créés automatiquement dans languages/. Nous allons nous concentrer sur languages/fr/.

Dans ce dossier, comme dans tout dossier de langue, vous trouverez par défaut les fichiers suivants :
- default.php : un fichier fourre-tout où vous pouvez mettre tout ce qui ne rentre pas ailleurs. Utile, sémantiquement, pour mettre les définitions de langues qui peuvent être partagées entre plusieurs extensions.
- modules.php : le fichier de langue général, permettant de donner une nom aux sections et modules dans la sidebar du back-office et en divers endroits.
- un fichier de langue par dca : sert à définir le nom des champs, les noms des boutons et les divers contenus textes internationalisables utilisés par le module.

Nous n’utiliserons pas ici default.php. Dans modules.php, nous aurons :

1
2
3

$GLOBALS['TL_LANG']['MOD']['filiere'] = 'Fillières';
$GLOBALS['TL_LANG']['MOD']['tl_filiere_filiales'] = array('Filliales', 'Gérez les informations relatives à vos filiales.');
$GLOBALS['TL_LANG']['MOD']['tl_filiere_services'] = array('Services', 'Gérez les informations relatives à vos services.');

La première entrée corespond au nom de la section que nous avons utilisé dans le fichier config.php. Les deux suivantes représentent les deux DCA. Leur valeur est un tableau à deux entrées, la première étant le titre, la seconde la description. Cette description est notament utilisées dans l’accueil du back-office, dans la section principale.

Dans le fichier tl_filiere_services.php ( toujours dans languages/fr/ ), nous avons :

1
2
3
4
5
6
7
8
9
10
11
12
13
14

/**
 * Fields
 */
$GLOBALS['TL_LANG']['tl_filiere_services']['name'] = array('Nom', 'Donnez un nom à ce service.');
$GLOBALS['TL_LANG']['tl_filiere_services']['description'] = array('Description', 'Décrivez le service.');
$GLOBALS['TL_LANG']['tl_filiere_services']['price'] = array('Tarif', 'Entrez la valeur numérique du tarif, sans précisez la devise, en séparant la décimale par un point. Exemple: "19.99"');
 
/**
 * Buttons
 */
$GLOBALS['TL_LANG']['tl_filiere_services']['new']    = array('Nouveau service', 'Cliquez ici pour créer un nouveau service');
$GLOBALS['TL_LANG']['tl_filiere_services']['edit']   = array('Modifier', 'Cliquez ici pour modifier les informations relatives à ce service.');
$GLOBALS['TL_LANG']['tl_filiere_services']['delete'] = array('Effacer', 'Cliquez ici pour effacer le service.');
$GLOBALS['TL_LANG']['tl_filiere_services']['show']   = array('Voir', 'Cliquez ici pour afficher les informations relatives à ce service.');

Les champs fields sont ceux utilisés dans le DCA pour représenter les différents input. On y associe un tableau à deux entrées, le premier étant le titre, le second étant la description placée en dessous du widget si l’utilisateur à choisi d’avoir l’aide affichée.

Le même principe s’applique pour les boutons : le titre en première valeur, la description ( placée dans l’attribut title du lien ) en seconde valeur.

Vous pouvez également placer ici les textes de langue utilisés par votre DCA, comme par exemple les options fixes d’un select ( un squelette est placé dans le fichier lorsqu’il est créé automatiquement, dans la partie “References” du fichier ).

En dernier lieu, voici le fichier tl_filiere_filiales.php :

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

/**
 * Fields
 */
$GLOBALS['TL_LANG']['tl_filiere_filiales']['name'] = array('Nom', 'Donnez le nom de cette filiale.');
$GLOBALS['TL_LANG']['tl_filiere_filiales']['city'] = array('Ville', 'Donnez la ville de cette filiale.');
$GLOBALS['TL_LANG']['tl_filiere_filiales']['phone'] = array('Téléphone', 'Quel est le numéro de téléphone de cette filiale?');
$GLOBALS['TL_LANG']['tl_filiere_filiales']['email'] = array('Email', 'Donnez l\adresse email de cette filiale.');
$GLOBALS['TL_LANG']['tl_filiere_filiales']['services'] = array('Services', 'Liste des services que cette filiale propose.');
 
/**
 * Buttons
 */
$GLOBALS['TL_LANG']['tl_filiere_filiales']['new']    = array('Nouvelle filiale', 'Cliquez ici pour créer une nouvelle filiale.');
$GLOBALS['TL_LANG']['tl_filiere_filiales']['edit']   = array('Modifier', 'Cliquez ici pour modifier les informations de cette filiale.');
$GLOBALS['TL_LANG']['tl_filiere_filiales']['copy']   = array('Dupliquer', 'Cliquez ici pour créer une nouvelle filiale sur la base des informations de celle-ci.');
$GLOBALS['TL_LANG']['tl_filiere_filiales']['delete'] = array('Effacer', 'Cliquez ici pour effacer cette filiale.');
$GLOBALS['TL_LANG']['tl_filiere_filiales']['show']   = array('Voir', 'Cliquez ici pour voir les informations de cette filiale.');

Il ne vous reste plus qu’à faire l’équivalent de ces fichiers pour chaque langue que vous voudrez maintenir.

Vous trouverez les fichiers de ce que nous venons de faire ici. Certains fichiers sont vides, ils sont relatifs aux modules frontend et seront utilisés dans un autre tutoriel. En effet, si vous disposez maintenant de quoi gérer basiquement des ressources en back-office, elles sont en l’état totalement inaccessibles au visiteur de votre site. Il va donc s’agir maintenant de coder un module frontend permettant d’utiliser ces ressources. Je reviendrai d’abord dans le prochain tuto sur l’utilisation des modèles. Ensuite, nous verrons les modules frontend. Enfin, nous reviendront plus en profondeur sur les modules backend. La suite au prochain épisode, merci de m’avoir lu.