Listes d'objets : classe d'action listItems

Principes

Une classe abstraite Action_ListItems utilise le paginateur de Zend et implémente l'interface adapteur Zend_Paginator_Adapter_Interface. Concrètement, la classe gère la récupération du nombre total d'objets de la liste, l'affichage des objets n à n+p et des liens de navigation dans la liste paginée (précédent, suivant, etc).

Action_ListItems propose des méthodes qui permettent de personnaliser la liste qui sera créée. Avantage, une liste de base est réalisée de façon très rapide. Le nom de l'action (qui figure dans l'URL) peut être choisi mais c'est toujours la méthode listItems qui doit lui correspondre. Inconvénent on est obligé de créer une classe dérivée par type de liste qu'on veut réaliser. Imaginons par exemple que je veuille faire les listes listePublic, listeMembres, listeAdmin qui listent toutes des objets Toto mais avec des vues différentes selon les cas. On est alors obligé de créer 3 classes qui dérivent d'une action listItems puisque les méthodes de "configuration" auront toujours le même nom et ne peuvent donc différer. On pourra cependant peut-être avoir des solutions si la configuration de ces listes est similaire (voir plus bas). =>TODO

Fonctionnement, configuration et variables d'affichage

La méthode options_listItems est à spécifier pour déterminer les droits sur l'action. La méthode principale do_listItems gère les paramètres GET pour savoir quelle page afficher, instancie un Zend_Paginator et passe au template d'affichage les variables nécessaires pour l'affichage. Le template utilisé reçoit alors des variables qui peuvent être spécifiées selon le type de liste voulu. On peut aussi y ajouter un tableau de variables, comme pour l'utilisation classique d'un template.

Configuration de base

Options de pagination

La méthode getPagesOptions reytourne un tableau avec le nombre d'item par page -par défaut 10, constante PER_PAGE- et le nombre de liens à mettre dans le paginateur -par défaut 7, constante MAX_LINKS. Exemple où l'on ne change que le nombre d'items par page :

  protected function getPagesOptions() {
    return array(
      'itemsPerPage' => PER_PAGE,
      'pageRange' => MAX_LINKS,
    );
  }

Requête de base

La méthode getBasicQuery définit la requête SydonieQuery à utiliser. La requête par défaut étant définie comme suit :

  protected function getBasicQuery() {
    return new SydonieQuery_Query(array(
      new SydonieQuery_Entity('instance', $this->class),
      new SydonieQuery_Rights('instance', 'read'),
      new SydonieQuery_Return('instance')
    ));
  }

Templates à utiliser

Les méthodes getTemplateName, getItemTemplateName, getHeaderTemplateName définissent les noms des templates à utiliser. Par défaut il s'agit des templates listItems, item et listItems_header.

Variables complémentaires pour le template

La méthode getTemplateParams permet de spoécifier un tableau de paramètres à passer au template (sous la forme de paires nom => valeur, cf. utilisation de display()). Ces paramètres seront ajoutés aux variables du template qui sont créées pat la méthode do_listItems.

Variables non modifiables du template

• paginator : objet Zend_Paginator, indispensable pour la pagination...
• action : nom de l'action du listItems (spécifié dans le fichier actions.xml)
• filtersActionUrl : URL de l'action que les filtres utilisent (par défaut le même que pour afficher la liste)

Variables configurables du template et méthodes associées

basicVars

basicVars est tableau des données GET à ajouter dans l'URL des liens de pagination. Est fourni par la méthode getBasicVars. Sert par exemple pour lister des objets en ayant un type donné. Le code ci-dessous sert par exemple pour lister des catastrophes appartenant à une catégorie donnée, il faut donc passer l'identifiant de la catégorie dans les paramètres GET de tous les liens de pagination :

  protected function getBasicVars() {
    $vars = array();
    $categoryId = $this->controllerData->getDataGetKey('categoryId');
    if ($categoryId !== SYDONIE_NO_KEY) {
      $vars['categoryId'] = $categoryId;
    }
    return $vars;
  }

filters

filters contient les filtres à afficher pour restreindre la liste à afficher. La méthode getFilters fourni cette liste (vide par défaut). Les filtres sont des objets qui permettent de créer leur propre formulaire. Il suffit donc de spécifier les objets Filter à utiliser, par exemple pour filtrer la liste sur le titre :

  protected function getFilters() {
    return array(
    		new Filter_Text('nom_du_filtre', 'title.text')
    );
  }

displayFilters

displayFilters est un booléen pour déterminer si le formulaire des filtres doit être affiché. Modifiable avec la méthode displayFilters() qui, par défaut, retourne vrai si la liste des filtres est non vide.

actionLinkList

Le template par défaut crée des liens pour chaque objet de la liste. Par défaut les liens vers les actions view, edit, delete sont créés (selon les droits de l'utilisateur). actionLinkList est la liste des actions pour lesquelles il faut créer un lien. La méthode getActionsLinkList permet de changer cette liste :

  protected function getActionLinkList() {
    return array('view', 'changeDisaster', 'edit', 'delete');
  }

displayClassActions

displayClassActions est un booléen pour indiquer si un lien pour créer un objet doit être ajouté (dans le template de base). Vaut true par défaut et peut être changé avec la méthode displayClassActions().

headerTemplateName

headerTemplateName est le nom du template utilisé pour le titre ou l'en-tête de la liste. Par défaut sa valeur est listItems_header et il peut être spécifié avec la méthode getHeaderTemplateName().

itemTemplateName

itemTemplateName est le nom du template utilisé pour chaque item de la liste. Par défaut sa valeur est item et il peut être spécifié avec la méthode getItemTemplateName()

TO DO

• documenter la structure du template listItems et du template paginator
• documenter le displayAll() pour les recherches
• ajouter le choix du template paginator
• ajouter le choix du template actionLinks
• ajouter le choix du template classActions
• ajouter le choix du template filters
• ranger les templates dans un dossier templates/listItems et mettre les noms dans templates.xml
• ajouter les fonctionnalités de pagination ajax
• faire un tableau résumant les méthjodes à utiliser
• mettre un exemple concret