Les tableaux HTML sont indispensables à la présentation de données, Drupal a prévu des themes par défaut de mise en forme pour afficher les données extraites de la base. C'est la fonction theme() qui se charge de cette mise en forme. On peut utiliser theme('item-list', $data) dans les blocks (on le verra dans un chapitre ultérieur et theme('table', $data) dans les pages. Enfin, nous verrons deux autres outils de mises en forme de tableaux, le pager et le tablesort. Le but de ce chapitre 3bis est d'étendre le concept de theming de données par un exemple réutilisable ou coment mettre en forme des données tabulaires pour un affichage classique.

Les extenders

Drupal 7 enrichit les requetes à la bdd par des extender, ce sont des methodes qui agissent sur l'objet requete (d'où le grand interet de Drupal 7 qui s'enrichit d'un véritable environnement objet) pour pouvoir rendre celles-ci véritablement dynamique. On les appelle dans la requete par exemple comme ceci:

$query = db_select('node', 'n')->extend('PagerDefault')->limit(10);

on peut bien sur créer soit même ses propres extenders, ce sont des classes qui héritent de SelectQueryExtender

Exemple avec l'extender PagerDefault : source http://api.drupal.org/api/drupal/includes--pager.inc/class/PagerDefault/7

<?php
class PagerDefault extends SelectQueryExtender {

  /**
   * The highest element we've autogenerated so far.
   *
   * @var int
   */
  static $maxElement = 0;

  /**
   * The number of elements per page to allow.
   *
   * @var int
   */
  protected $limit = 10;

  /**
   * The unique ID of this pager on this page.
   *
   * @var int
   */
  protected $element = NULL;

  /**
   * The count query that will be used for this pager.
   *
   * @var SelectQueryInterface
   */
  protected $customCountQuery = FALSE;

  public function __construct(SelectQueryInterface $query, DatabaseConnection $connection) {
    parent::__construct($query, $connection);

    // Add pager tag. Do this here to ensure that it is always added before
    // preExecute() is called.
    $this->addTag('pager');
  }

  /**
   * Override the execute method.
   *
   * Before we run the query, we need to add pager-based range() instructions
   * to it.
   */
  public function execute() {

    // Add convenience tag to mark that this is an extended query. We have to
    // do this in the constructor to ensure that it is set before preExecute()
    // gets called.
    if (!$this->preExecute($this)) {
      return NULL;
    }

    // A NULL limit is the "kill switch" for pager queries.
    if (empty($this->limit)) {
      return;
    }
    $this->ensureElement();

    $total_items = $this->getCountQuery()->execute()->fetchField();
    $current_page = pager_default_initialize($total_items, $this->limit, $this->element);
    $this->range($current_page * $this->limit, $this->limit);

    // Now that we've added our pager-based range instructions, run the query normally.
    return $this->query->execute();
  }

  /**
   * Ensure that there is an element associated with this query.
   * If an element was not specified previously, then the value of the
   * $maxElement counter is taken, after which the counter is incremented.
   *
   * After running this method, access $this->element to get the element for this
   * query.
   */
  protected function ensureElement() {
    if (!isset($this->element)) {
      $this->element = self::$maxElement++;
    }
  }

  /**
   * Specify the count query object to use for this pager.
   *
   * You will rarely need to specify a count query directly.  If not specified,
   * one is generated off of the pager query itself.
   *
   * @param SelectQueryInterface $query
   *   The count query object.  It must return a single row with a single column,
   *   which is the total number of records.
   */
  public function setCountQuery(SelectQueryInterface $query) {
    $this->customCountQuery = $query;
  }

  /**
   * Retrieve the count query for this pager.
   *
   * The count query may be specified manually or, by default, taken from the
   * query we are extending.
   *
   * @return SelectQueryInterface
   *   A count query object.
   */
  public function getCountQuery() {
    if ($this->customCountQuery) {
      return $this->customCountQuery;
    }
    else {
      return $this->query->countQuery();
    }
  }

  /**
   * Specify the maximum number of elements per page for this query.
   *
   * The default if not specified is 10 items per page.
   *
   * @param $limit
   *   An integer specifying the number of elements per page.  If passed a false
   *   value (FALSE, 0, NULL), the pager is disabled.
   */
  public function limit($limit = 10) {
    $this->limit = $limit;
    return $this;
  }

  /**
   * Specify the element ID for this pager query.
   *
   * The element is used to differentiate different pager queries on the same
   * page so that they may be operated independently.  If you do not specify an
   * element, every pager query on the page will get a unique element.  If for
   * whatever reason you want to explicitly define an element for a given query,
   * you may do so here.
   *
   * Setting the element here also increments the static $maxElement counter,
   * which is used for determining the $element when there's none specified.
   *
   * Note that no collision detection is done when setting an element ID
   * explicitly, so it is possible for two pagers to end up using the same ID
   * if both are set explicitly.
   *
   * @param $element
   */
  public function element($element) {
    $this->element = $element;
    if ($element >= self::$maxElement) {
      self::$maxElement = $element + 1;
    }
    return $this;
  }
}
?>

Ainsi vous voyez dans le code la méthode limit (par default 10) appelée dans notre exemple par ->limit(10). Vous pouvez fouillez la doc, vous trouverez pas mal de possibilités pour customiser le PagerDefault (attention, jamais dans le source) ou pour construire votre propre extender. Je n'ai pas d'exemple en tête, mais si j'ai une idée, je vous ne ferai part (peut être quand on attaquera le cas pratique)

TableSort est le deuxième extender que nous allons utiliser permet de faire un tri sur les en-têtes du tableau, c'est également bien pratique et une fonction très web2.0 mais qui en fait ne fait pas appel au côté client. On peut trouver facilement la même chose ne javascript (avec jquery par exemple) mais je vous montre les méthodes Drupal après tout !!

la fonction theme_table

Sa doc est ici http://api.drupal.org/api/drupal/includes--theme.inc/function/theme_table. Elle s'appelle également de la manière suivante : theme('table',$data);

$data est un tableau associatif dont les clés sont:

• header : un tableau qui contient les entêtes, soit un tableau simple, exemple 'header' => array(t('Title'), t('Type'), t('Created')) soit un tableau associatif dont les clés sont 'data', 'field', 'sort' et ce qu'on veut comme attribut html comme 'colspan' pour pouvoir regrouper des cellules.
• rows : ce sont nos lignes de données, c'est donc un tableaux de lignes et chaque ligne est un tableau de cellules ou un tableau associatif dont les clés permettent de spécifier , 'data' la ligne de données ou un tableau permettant de spécifier chaque cellule ainsi que la classe CSS, le colspan etc.., 'class' une classe CSS et 'no-stripping' de ne pas avoir l'alternance de lignes de fond.. Un peu compliqué comme ça mais lisez la doc, on s'en sort, la plupart des erreurs viennent de la structure des arrays.
• attributes : un tableau d'attributs HTML à appliquer à la balise
  comme par exemple 'attributes' => array('class'=>array('monjolitableau'), 'border =>'1px solid black')
• caption : une chaine qui s'applique à la balise HTML
  
• colgroups: Un tableau de groupes de colonnes. Chaque élément du tableau peut être soit:
  • Un tableau de colonnes, dont chacune est un tableau associatif d'attributs HTML appliquée à l'élément COL.
  • Un tableau de clés appliqués à l'élément COLGROUP, qui doit inclure une clé "data". Pour ajouter des attributs aux éléments COL, définissez la clé "data" avec un tableau de colonnes, dont chacune est un tableau associatif d'attributs HTML.

  Un exemple:

  <?php
      $colgroup = array(
        // COLGROUP with one COL element.
        array(
          array(
            'class' => array('funky'), // Attribute for the COL element.
          ),
        ),
        // Colgroup with attributes and inner COL elements.
        array(
          'data' => array(
            array(
              'class' => array('funky'), // Attribute for the COL element.
            ),
          ),
          'class' => array('jazzy'), // Attribute for the COLGROUP element.
        ),
      );
      ?>

  Ces balises facultatives sont utilisées pour grouper et définir des propriétés sur les colonnes d'une table. Par exemple, on peut facilement grouper trois colonnes et appliquer le même style de fond à toutes.

• sticky : pour que les en-têtes du tableau soient collants, c'est à dire tout le temps affiché (javascript)
• empty : Une chaine à afficher si la cellule est vide

Exemple

On repart sur notre exemple d'articles hebdomadaires: la callback de la page commence de la manière suivante :

<?php
function articles_hebdo_page_callback(){
$today = getdate();    //Date il y a une semaine
$start_time = mktime(0, 0, 0,$today['mon'],($today['mday'] - 7), $today['year']);    //Obtient tous les messages depuis une semaine jusqu'à aujourd'hui.
$end_time = time();
?>

On définit les entetes et les champs à récuperer dans la BDD

 <?php
$header = array(
    array('data' => t('Title'), 'field' => 'title', 'sort' => 'asc'),
    array('data' => t('Node ID'), 'field' => 'nid'),
    array('data' => t('Type'), 'field' => 'type'),
    array('data' => t('Created'), 'field' => 'created'),
    array('data' => t('Published')),
    );
$fields = array ('nid', 'title', 'type', 'created', 'status');
?>

On récupère les données via la fonction _articles_hebdo_contents($header, $fields)

 <?php
$results = _articles_hebdo_contents($header, $fields); // on récupère les données
?>

La fameuse fonction avec les extenders PagerDefault (anciennement une focntion pager_query dans Drupal 6) et Tablesort (anciennement une chaine à rajouter à la chaine sql dans Drupal 6)

 <?php
/**
 * fonction de chargement des articles de la semaine
 * @param :
 * $header : un tableau d'entêtes
 * $fields : les champs associés
 *
 * @return
 *   Un  objet SelectQuery
 */
function _articles_hebdo_contents($header = array(), $fields = array()){
//Date d'aujourd'hui
$today = getdate();
//Date il y a une semaine
$start_time = mktime(0, 0, 0,$today['mon'],($today['mday'] - 7), $today['year']);
//Obtient tous les messages depuis une semaine jusqu'à aujourd'hui.
$end_time = time();

//Utilise le databaseAPI pour trouver les resultats
$query = db_select('node', 'n')
->extend('PagerDefault')->limit(10)
->condition('status', 1) //Publié.
->condition('type', 'article')
->condition('created', array($start_time, $end_time), 'BETWEEN')
->extend('TableSort')->orderBy('created', 'DESC') //Tri du plus recent au plus ancien.
->fields('n', $fields)
->execute();
return $query; 
}
?>

On prépare un tableau pour les lignes et on fait une boucle sur les résultats de la fonction _articles_hebdo_contents($header, $fields)

 <?php
$rows = array();
foreach ($results as $node) {
    $rows[] = array(
        'data' => array(
            l($node->title, 'node/'. $node->nid .'/view'),
            $node->nid,
            $node->type,
            format_date($node->created,'custom','d/m/Y','Europe/Paris','fr'),
            $node->status
            )
    );
}
?>

Il nous reste plus qu'à préparer la fonction theme_table et le pager

 <?php
$data = array(
    'header' => $header,
    'rows' => $rows,
    'sticky' => TRUE,
    'caption' =>'<h3>'.t('Articles de la semaine du ').strftime('%d/%m',$start_time).t(' au ').strftime('%d/%m',$end_time).'</h3>',
    'attributes' => array('class' => array('mytable')),
    'empty' => t('Données non disponibles')
    );
$content = theme('table', $data);
$content .= theme('pager');
return $content;
?>

Conclusion

Voila en quelques lignes une mise en forme parfaite, il reste à faire la feuille CSS pour une apparence personnalisée. Je note qu'on peut utiliser une fonction de thème ou un template intermédiaire entre la callback et la fonction theme_table, c'est le genre de chose qu'on pourrait faire pour la page des utilisateurs récemment inscrits et connectés par exemple. Je met les sources de l'exemple de l'article en fichier attaché. Faites des essais surtout pour les attributs et les colspan et si quelque chose ne marche pas, regardez le source de la fonction theme_table, c'est le meilleur moyen d'apprendre comment le truc fonctionne