====== Tutoriel : Comment créer un CRUD ======

Vous apprendrez dans cet article, comment créer un CRUD à l'aide des classes [[http://docs.jelix.org/fr/manuel-1.0/jforms|jForms]] et [[http://docs.jelix.org/fr/manuel-1.0/daos|jDao]] de Jelix. 

Ce texte a pour origine la discussion du forum:
[[http://jelix.org/forums/read.php?5,888|initFromDao() et saveToDao()]]
et une [[http://ljouanneau.com/blog/2007/06/02/679-jforms-en-bonne-voie|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 
[[http://download.jelix.org/forge/tutors/crud_jelix-1.0.2/chat.zip|zip]] ou 
[[http://download.jelix.org/forge/tutors/crud_jelix-1.0.2/chat.tar.gz|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 [[http://docs.jelix.org/fr/manuel-1.0/jforms|jForms]] et [[http://docs.jelix.org/fr/manuel-1.0/daos|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 :

<code bash>
  #l'application s'appelle ici "chat"
  php jelix.php --chat createapp

</code>

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

<code ini>
  startModule = "chat"
  startAction = "default:index"
</code>

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

<code ini>
  [urlengine]
  engine        = simple
  multiview     = off
  basePath  = ""
</code>

Vous devez maintenant dire à Jelix quelle base de données vous désirez utiliser.      
  * Ouvrez le fichier //var/config/dbprofils.ini.php// 
  * Activez et décommentez les lignes correspondant à votre type de base de données
  * Donnez le nom de votre base de données à l'endroit approprié

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

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 ;

</code>

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 :

<code bash>
php jelix.php --chat createdaocrud chat forms
</code>

"forms" est ici le nom de la table.

Vous aurez alors dans le module chat les fichiers :
  * //daos/forms.dao.xml//
  * //forms/forms.form.xml//
  * //controllers/forms.classic.php//

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

<code xml>

<?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>

</code>

Quant au fichier //forms/forms.form.xml// :

<code 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>

</code>

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 :  

<code php>

<?php

class formsCtrl extends jControllerDaoCrud {

    protected $dao = 'chat~forms';

    protected $form = 'chat~forms';

    protected $dbProfil = '';

}
?>

</code>


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, [[http://docs.jelix.org/fr/manuel-1.0/traitements_communs|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///.

<code html>

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

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) :

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


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.

<code html>

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

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.

<code html>

{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>
</code>


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/.
<code html>

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

</code>




===== Final =====

Il faut maintenant indiquer ces nouveaux templates dans le controleur :

<code php>
    protected $listTemplate = 'chat~list';
    protected $editTemplate = 'chat~edit';
    protected $viewTemplate = 'chat~view';

</code>

Ce qui donne au final :

<code php>

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;
    }

}
</code>

Vous pouvez maintenant afficher la page.


----
   * [[fr:tutoriels:|Retour au sommaire des tutoriels]]