Table des matières

Tutoriel : Comment créer un CRUD

Vous apprendrez dans cet article, comment créer un CRUD à l'aide des classes jForms et jDao de Jelix.

Ce texte a pour origine la discussion du forum: initFromDao() et saveToDao() et une discussion du journal de ljouanneau. Ainsi que le code qu'on retrouve dans les tests unitaires fournis dans Jelix.

Pour faciliter l'apprentissage tout le code sera fourni.

Ce tutoriel n'est pas destiné à créer un outil de production mais peut servir de base à votre développement.

Vous pouvez télécharger le code de ce tutoriel aux formats zip ou gzip.

Pré-requis

Les exemples de ce tutoriel fonctionnent avec la version Jelix 1.0.2 et les suivantes.

Vous devez avoir fait le Mini Tutoriel et le Tutoriel principal pour être à l'aise avec Jelix. Nous utiliserons le même type d'installation que celle du Mini Tutoriel. Nous vous conseillons fortement la lecture des chapitres concernant jForms et jDao du manuel de Jelix.

Création de l'application

Dans un premier temps on crée une application, si ce n'est pas déjà fait. C'est à dire on crée l'application et le module/action par défaut. Pour réaliser cette tâche vous devez ouvrir une console ou une fenêtre 'invite de commandes' pour travailler en ligne de commandes et vous devez vous déplacer dans le répertoire jelix/lib/jelix-scripts/. Nous prenons pour acquis que vous avez placé Jelix à la racine du serveur pour permettre un appel semblable à http://localhost/jelix/.

À cet endroit vous tapez et ne fermez pas la console :

  #l'application s'appelle ici "chat"
  php jelix.php --chat createapp

Votre fichier de configuration var/config/index/config.ini.php devrait avoir les valeurs suivantes:

  startModule = "chat"
  startAction = "default:index"

Votre fichier de configuration var/config/defaultconfig.ini.php devrait avoir les valeurs suivantes:

  [urlengine]
  engine        = simple
  multiview     = off
  basePath  = ""

Vous devez maintenant dire à Jelix quelle base de données vous désirez utiliser.

Vous devez maintenant créer une table dans votre base de données avec le script suivant:

CREATE TABLE `forms` (
  `pk` INT(11) NOT NULL AUTO_INCREMENT,
  `nom` VARCHAR(100) NOT NULL,
  `prenom` VARCHAR(100) NOT NULL,
  PRIMARY KEY  (`pk`)
) TYPE=MyISAM ;

Une fois que vous avez créé votre table, vous pourrez créer le fichier jDao et jForms. Pour réaliser cette tâche vous devez être dans la console et taper la commande createdaocrud, qui crééra en plus un contrôleur :

php jelix.php --chat createdaocrud chat forms

“forms” est ici le nom de la table.

Vous aurez alors dans le module chat les fichiers :

Le fichier daos/forms.dao.xml devrait ressembler à ceci :

<?xml version="1.0" encoding="UTF-8"?>
<dao xmlns="http://jelix.org/ns/dao/1.0">
    <datasources>
        <primarytable name="forms" realname="forms" primarykey="pk" />
    </datasources>
    <record>
       <property name="pk" fieldname="pk" datatype="autoincrement"/>
       <property name="nom" fieldname="nom" datatype="string" required="true" maxlength="100"/>
       <property name="prenom" fieldname="prenom" datatype="string" required="true" maxlength="100"/>
    </record>
</dao>

Quant au fichier forms/forms.form.xml :

<?xml version="1.0" encoding="utf-8"?>
<form xmlns="http://jelix.org/ns/forms/1.0">
  <input ref="nom" required="true" maxlength="100">
	  <label>nom</label>
  </input>
  <input ref="prenom" required="true" maxlength="100">
	  <label>prenom</label>
  </input>
  <submit ref="_submit">
	  <label>ok</label>
  </submit>
</form>

Il y a ici deux champs de saisie simples, faisant référence aux valeurs dont les noms sont respectivement “nom”, “prenom”. Ces noms doivent correspondre aux propriétés d'un DAO quand on veut utiliser un formulaire conjointement avec un DAO, comme c'est le cas dans ce tutoriel.

Notez aussi les libellés associés aux champs de saisies. Ils seront utilisés pour l'affichage du formulaire HTML généré.

Le contrôleur

La commande createdaocrud a créé un fichier controllers/forms.classic.php avec le code suivant :

<?php
 
class formsCtrl extends jControllerDaoCrud {
 
    protected $dao = 'chat~forms';
 
    protected $form = 'chat~forms';
 
    protected $dbProfil = '';
 
}
?>

Simple non ? :-) Notez que le contrôleur hérite de jControllerDaoCrud qui prend toute une cinématique CRUD en charge. On peut le personnaliser, c'est ce qu'on va voir.

Le template main

Pour pouvoir afficher le contrôleur, il faut d'abord spécifier quel template principal on veut utiliser. Dans ce tutoriel, nous n'avons pas réalisé d'objet réponse commun à toute l'application, comme expliqué là, aussi nous nous contenterons de modifier le contrôleur directement.

Créons donc le fichier qui servira de template principal. Il est nommé main.tpl et sera placé dans le répertoire jelix/chat/modules/chat/templates/.

<div>
<h3>Exemple de l'utilisation du jDao et jForm</h3>
{$MAIN}
 
</div>
<p><a href="{jurl 'chat~forms:index'}">Afficher la liste</a></p>

Ensuite on va surcharger la méthode _getResponse() du contrôleur (qui est spécifique à jControllerDaoCrud et dans laquelle vous pouvez personnaliser la réponse) :

    protected function _getResponse(){
        $rep = $this->getResponse('html');
        $rep->bodyTpl = 'chat~main';
        return $rep;
    }

Le contrôleur est maintenant tout à fait opérationnel. Vous pouvez taper http://localhost/jelix/chat/www/index.php?module=chat&action=forms:index par exemple.

Cependant les templates de base utilisés pour la liste, l'édition et le détail sont plutôt simplistes. On va donc en refaire.

Le template liste

Ce template va afficher la liste des enregistrements. Il est nommé list.tpl et sera créé dans le répertoire /jelix/chat/modules/chat/templates/. Le template est initialisé avec la variable $list qui contient une liste d'enregistrement à afficher. jControllerDaoCrud gère aussi l'affichage par page (20 enregistrements par page par défaut), c'est pourquoi il y a aussi les variables de templates $recordCount, $page, $listPageSize et $offsetParameterName que l'on utilisera pour afficher une série de liens vers chaque page. Il y a aussi les variables $listAction, $viewAction, $editAction, $createAction et $deleteAction, contenant les diverses actions du controleur.

<p>Liste des fiches</p> 
{if $list->rowCount()}
  <table border="1">
  {foreach $list as $record}
    <tr>
    <td>{$record->nom|eschtml}</td>
    <td>{$record->prenom|eschtml}</td>
    <td>
        <a href="{jurl $viewAction,  array('id'=>$record->pk)}">voir</a>
        <a href="{jurl $editAction,  array('id'=>$record->pk)}">éditer</a>
        <a href="{jurl $deleteAction, array('id'=>$record->pk)}">détruire</a>
    </td>
    </tr>
  {/foreach}
  </table>
 
   <div>Pages : {pagelinks $listAction, array(),  $recordCount, $page, $listPageSize, $offsetParameterName }</div>
{else}
  <p>La liste est vide</p>
{/if}
 
<p><a href="{jurl $createAction}">Créer une nouvelle fiche</a>.</p>

Vous remarquerez l'utilisation du plugin pagelinks pour afficher les liens des pages de liste, et du modificateur “eschtml” qui fait en fait un htmlspecialchars sur le contenu qu'on lui donne.

Attention : la méthode rowCount, utilisant les fonctions natives des bases de données dans PHP pour récupérer un nombre d'enregistrement, n'est pas toujours fiable (voir les avertissements dans la documentation de PHP). Il est préférable, soit de faire soit même un SELECT COUNT(), soit de récupérer tous les enregistrements dans un tableau et faire un count() dessus.

Le template edit

Créez le fichier template qui permet l'édition d'un enregistrement. Il est nommé edit.tpl et doit être créé dans le répertoire jelix/chat/modules/chat/templates/. Ce template est utilisé à la fois pour l'édition d'un enregistrement existant, que la création d'un enregistrement. Pour savoir dans quel cas on est, il suffit de tester la variable $id qui contient l'identifiant de l'enregistrement.

Il y a aussi la variable $form, qui contient un objet jForms, et la variable $submitAction qui contient le nom de l'action où poster le formulaire.

{if $id == null}
 
<h1>Créer une nouvelle fiche</h1>
{formfull $form, $submitAction}
 
{else}
 
<h1>Modification de la fiche {$id}</h1>
 
{form $form, $submitAction, array('id'=>$id)}
<fieldset>
   <legend>Votre identité</legend>
    <p>{ctrl_label 'prenom'} 
       {ctrl_control 'prenom'}</p>
 
    <p>{ctrl_label 'nom'} 
       {ctrl_control 'nom'}</p>
</fieldset>
<p>{formsubmit}</p>
{/form}
 
{/if}
 
<p><a href="{jurl $listAction}">Annuler et retourner à la liste</a>.</p>

Notez l'affichage différent pour la création et la mise à jour : c'est simplement pour que vous voyez les deux façons de générer un formulaire avec jForms, la première, avec formfull étant totalement automatique, mais peu personnalisable contrairement à la deuxième.

Le template view

Créez le fichier template qui affichera un enregistrement. Il est nommé view.tpl et doit être créé dans le répertoire /jelix/chat/modules/chat/templates/.

<p>Affichage de l'enregistrement {$id}/p> 
 
{formdatafull $form}
 
<ul>
    <li><a href="{jurl $editAction, array('id'=>$id)}">Modifier</a></li>
    <li><a href="{jurl $deleteAction, array('id'=>$id)}" onclick="return confirm('{@jelix~crud.confirm.deletion@}')">Effacer</a></li>
    <li><a href="{jurl $listAction}">Liste</a></li>
</ul>

Final

Il faut maintenant indiquer ces nouveaux templates dans le controleur :

    protected $listTemplate = 'chat~list';
    protected $editTemplate = 'chat~edit';
    protected $viewTemplate = 'chat~view';

Ce qui donne au final :

class formsCtrl extends jControllerDaoCrud {
 
    protected $dao = 'chat~forms';
 
    protected $form = 'chat~forms';
 
    protected $dbProfil = '';
 
    protected $listTemplate = 'chat~list';
    protected $editTemplate = 'chat~edit';
    protected $viewTemplate = 'chat~view';
 
 
    protected function _getResponse(){
        $rep = $this->getResponse('html');
        $rep->bodyTpl = 'chat~main';
        return $rep;
    }
 
}

Vous pouvez maintenant afficher la page.