Section: Utiliser le contrôleur CRUD
| « Récupération des paramètres HTTP | ^ Développement d'un module | Un contrôleur pour REST » |
− Table des matières
Introduction ¶
Un contrôleur (jControllerDaoCrud) est fourni avec jelix pour faire du CRUD. CRUD veut dire Create, Read, Update, Delete. En substance, c'est un contrôleur qui contient toutes les actions pour créer, lire, mettre à jour et effacer un enregistrement d'une table, et lister les enregistrements de cette table. Il lui faut en gros pour fonctionner, le nom d'un fichier DAO et d'un fichier jForms. Il s'occupe du reste.
C'est donc un contrôleur permettant de mettre en place rapidement une gestion d'un enregistrement de table.
Note : ce contrôleur ne fonctionne que pour les tables avec une clé primaire simple. Si votre table possède une clé primaire composée de deux champs il faut utiliser jControllerDaoCrudDfk. Pour le reste vous devrez faire votre propre contrôleur.
Création d'un CRUD ¶
Pour l'utiliser, il faut créer un contrôleur dans votre module, qui hérite non pas de jController, mais de jControllerDaoCrud. Exemple, dans un fichier samplecrud.classic.php
class sampleCrudCtrl extends jControllerDaoCrud {
}
Il faut ensuite lui indiquer un DAO qui utilise la table que l'on veut gérer, et un fichier jforms, qui permettra d'afficher le formulaire d'édition d'un enregistrement. Cela se fait au travers des propriétés $dao et $form :
class sampleCrudCtrl extends jControllerDaoCrud {
protected $dao = 'testapp~products';
protected $form = 'testapp~products';
}
Et c'est tout ! En imaginant que ce contrôleur se trouve dans le module main, affichez alors la page
index.php/main/samplecrud/index
Vous avez alors toutes les pages qu'il faut pour gérer les enregistrements de la table.
Important : par défaut, le controleur récupère la réponse HTML définie dans jelix, c'est à dire qu'il vous faut faire une réponse HTML personnalisée. Si vous n'en avez pas, rien ne s'affichera. Si vous ne voulez pas faire de réponse personnalisée (ce qui est dommage), il faudra configurer le contrôleur.
Note : vous pouvez aussi utiliser la commande jelix createdaocrud qui vous permet de créer à la fois le contrôleur, le dao et le formulaire, en indiquant la table que l'on veut gérer.
php jelix.php --myapp createdaocrud le_module la_table le_nom_du_controleur
Voir l'aide de cette commande (php jelix.php help createdaocrud) pour les options.
Personnalisation du contrôleur ¶
Il se peut que le comportement par défaut du contrôleur et des affichages des pages ne correspondent pas à ce que vous voulez, et qu'il faille faire des choses au niveau du formulaire (pré remplir à la main des listbox par exemple). Voici donc ce qui est possible de faire.
Indiquer le profil jDb ¶
Si il faut utiliser un profil de connexion spécifique, indiquez le dans la propriété $dbProfil :
protected $dbProfile = 'admin';
Configurer la réponse ¶
Par défaut, comme il a été dit plus haut, le contrôleur récupère la réponse HTML par défaut. Cela se fait dans la méthode _getResponse() du contrôleur :
protected function _getResponse(){
return $this->getResponse('html');
}
L'objet réponse renvoyé par cette méthode est alors utilisé par toutes les actions du contrôleur CRUD.
Comme vous le voyez, rien n'est fait au niveau de la réponse (à part dans chaque action l'assignation d'un contenu principal dans la variable de template "MAIN"). Ainsi, pas de déclaration de template principal (bodyTpl), pas de feuille de style ou autre. Le contrôleur s'attend en effet à ce que l'objet renvoyé par getResponse soit un objet réponse crée par vos soins et communs à tous vos contrôleurs.
Si vous voulez donc changer ça, redéfinissez donc cette méthode en y ajoutant ce que vous voulez. Exemple:
protected function _getResponse(){
$rep = $this->getResponse('html');
$rep->addCSSLink('admin.css');
$rep->body->assignZone('menu', 'adminmenu');
return $rep;
}
Ainsi la page de liste des enregistrements, de vue et d'édition d'un enregistrement etc auront une feuille de style admin.css et un menu qui est généré par la zone adminmenu.
Si vous voulez modifier la réponse pour des pages spécifiques du contrôleur, vous pouvez redéfinir ces méthodes :
- _index($resp, $tpl): pour la page de la liste des enregistrements
- _view($form, $resp, $tpl): pour la page des détails d'un enregistrement
- _create($form, $resp, $tpl) : pour la page d'édition d'un nouvel enregistrement
- _editUpdate($form, $resp, $tpl): pour la page d'édition d'un enregistrement existant.
Dans chacune de ses méthodes, vous recevez la réponse à modifier dans le paramètre $resp.
Configurer le formulaire ¶
Si vous voulez modifier dynamiquement le formulaire, pour par exemple ajouter ou désactiver des champs de saisie, vous pouvez redéfinir les deux méthodes _createForm and _getForm, qui doivent appeler respectivement jForms::create() et jForms::get() (Vous ne devez pas appeler jForms::fill()).
Par défaut, ces méthodes sont :
protected function _createForm($formId = null) {
return jForms::create($this->form, $formId);
}
protected function _getForm($formId = null) {
return jForms::get($this->form, $formId);
}
Si vous voulez modifier le formulaire durant des actions spécifiques, redéfinissez les méthodes _view, _create et _editUpdate décrites précédement.
Définir les templates ¶
Les templates par défaut utilisés par le contrôleur sont indiqués dans les propriétés :
protected $listTemplate = 'jelix~crud_list';
protected $editTemplate = 'jelix~crud_edit';
protected $viewTemplate = 'jelix~crud_view';
Vous pouvez bien sûr les surcharger dans un thème, soit en indiquer d'autres que vous aurez crées dans vos propres modules.
Variables de template ¶
Voir les sources des templates par défaut (dans lib/jelix/core-modules/jelix/templates) pour connaitre la liste des variables de template.
Le template de la liste des enregistrements aura les variables spécifiques suivantes :
- list : liste des résultats (renvoyé par le dao)
- primarykey : le nom de la clé primaire
- properties : la liste des propriétés à afficher
- controls : la liste des contrôles du formulaire jforms, permettant donc d'obtenir le libellé de chaque en-tête de colonne de chaque propriété.
- listPageSize : la valeur de $listPageSize
- page : la valeur du paramètre url "offset", indiquant le numéro d'ordre du premier enregistrement à afficher dans la liste.
- recordCount : le nombre d'enregistrements au total
- offsetParameterName : le nom du paramètre url pour l'offset (valeur de la propriété $offsetParameterName)
Ajouter d'autres variables ¶
Si vous voulez déclarer des variables de template supplémentaires, vous pouvez redéfinir les méthodes _index, _view, _create et _editUpdate décrites plus haut. Dans ces méthodes, vous pouvez utiliser les méthodes et propriétés de l'objet jTpl qui vous est donné en paramètres.
Intégration des templates dans la réponse ¶
Chaque action d'affichage du contrôleur CRUD utilise un template, dont le contenu sera assigné au template principal de la réponse dans la variable de template MAIN. En d'autres termes, chaque action fait l'équivalent de :
$rep->body->assign('MAIN', $resultatTemplateAction);
Si vous voulez que ce soit dans une variable de template autre que MAIN, vous pouvez changer la propriété $templateAssign :
class sampleCrudCtrl extends jControllerDaoCrud {
//...
protected $templateAssign = 'AUTRE';
//...
}
Page liste des enregistrements ¶
Elle est affichée par l'action index. Des propriétés du contrôleur CRUD permettent de configurer l'affichage de la liste.
Nombre d'enregistrements par page ¶
Il est défini par la propriété $listPageSize :
protected $listPageSize = 20;
Liste des propriétés ¶
Par défaut, toutes les propriétés du DAO sont affichées. Si vous voulez restreindre, indiquez la liste des propriétés à afficher dans propertiesForList :
protected $propertiesForList = array('titre','date_creation','auteur');
Ordre et critères d'affichage ¶
Il n'y a pas d'ordre spécifique pour afficher les enregistrements. Pour forcer un ordre précis, indiquez la liste des propriétés du dao qui serviront d'ordre, et le sens :
protected $propertiesForRecordsOrder = array('date'=>'desc', 'title'=>'asc');
Si ce n'est pas suffisant, vous pouvez redéfinir la méthode _indexSetConditions(), qui accepte en paramètre un objet jDaoConditions que vous pouvez compléter pour spécifier des critères de sélections des enregistrements à afficher, l'ordre d'affichage..
Configuration avancée de la liste ¶
La méthode index appelle une méthode protégée _index que vous pouvez redéfinir pour personnaliser l'affichage. Cette méthode reçoit l'objet réponse instancié et l'objet template utilisé pour afficher la liste. Vous pouvez donc en profiter pour finir de configurer la réponse et ajouter éventuellement des variables de templates.
Page création d'un enregistrement ¶
Elle est affichée par les actions precreate, create, savecreate.
L'action precreate crée et prépare le formulaire puis redirige vers l'action create. L'action create affiche le formulaire pour éditer le nouvel enregistrement, et envoi les données vers l'action savecreate. Cette dernière action vérifie le contenu du formulaire, et enregistre les données si c'est ok.
En plus de la méthode _create indiquée plus haut pour personnaliser l'affichage, vous pouvez aussi redéfinir les autres méthodes:
- _preCreate($form): pour préparer le formulaire juste après sa création.
- _checkData($form, $calltype): pour vérifier des données supplémentaires. Cette méthode est aussi appelée par la méthode saveupdate (voir plus bas).
- _beforeSaveCreate($form, $form_daorec): pour faire des choses juste avant la sauvegarde du nouvel enregistrement.
- _afterCreate($form, $id, $resp): pour faire des traitements après la sauvegarde.
Page mise à jour d'un enregistrement ¶
Elle est affichée et gérée par les actions preupdate, editupdate et saveupdate.
Le processus suit le même schéma que pour la création d'un enregistrement. preupdate crée et prépare le formulaire et redirige vers l'action editupdate. L'action editupdate affiche le formulaire pour éditer l'enregistrement, et envoi les données vers l'action saveupdate. Cette dernière action vérifie le contenu du formulaire, et enregistre les données si c'est ok.
En plus de la méthode _update indiquée plus haut pour personnaliser l'affichage, vous pouvez aussi redéfinir les autres méthodes:
- _preUpdate($form): pour préparer le formulaire juste après sa création.
- _checkData($form, $calltype): pour vérifier des données supplémentaires.
- _beforeSaveUpdate($form, $form_daorec, $id): pour faire des choses juste avant la sauvegarde de l'enregistrement.
- _afterUpdate($form, $id, $resp): pour faire des traitements après la sauvegarde.
Page destruction d'un enregistrement ¶
Elle est affichée par l'action delete. Vous pouvez redéfinir la méthode _delete pour faire des traitements additionnels.
Configurer les URLS ¶
Si vous avez activé les urls significatives, voici le contenu que vous pouvez mettre dans le fichier urls.xml du module, dans l’hypothèse ici où le contrôleur s'appelle "mycrud" et que l'on veut avoir des urls vers ce contrôleur qui commencent par "thedata" :
<url pathinfo="/thedata/" action="mycrud:index" />
<url pathinfo="/thedata/view/:id" action="mycrud:view" />
<url pathinfo="/thedata/precreate" action="mycrud:precreate" />
<url pathinfo="/thedata/create" action="mycrud:create" />
<url pathinfo="/thedata/savecreate" action="mycrud:savecreate" />
<url pathinfo="/thedata/preedit/:id" action="mycrud:preupdate" />
<url pathinfo="/thedata/edit/:id" action="mycrud:editupdate" />
<url pathinfo="/thedata/save/:id" action="mycrud:saveupdate" />
<url pathinfo="/thedata/delete/:id" action="mycrud:delete" />
Il y a donc en tout 9 actions donc 9 urls à définir.
