mars 31

Réflexion autour de l’admin-generator symfony

Chose promise, chose due. Voici la premier article d’une longue série sur les différentes approches de développement et le web en général.

Cette article fait suite à trois événements :

La conférence BeZend et une réflexion sur l’admin-generator
Un article publié chez Maxime
Un sujet interne à Crumblr

Comme vous pouvez vous en douter, cet article tournera essentiellement autour de l’admin-generator de symfony.

1. Présentation de l’admin-generator

Faisons simple pour cette explication, l’admin-generator vous permet très simplement via le biais d’une simple commande symfony de créer une interface d’administration pour votre site. Cela se passe de la façon suivante dans votre terminal. Je pars du principe que vous avez déjà généré votre projet et que vous avez déjà construit votre base de donnée, formulaires, votre model…

1.1 Création d’un module avec l’admin-generator

Première étape, nous allons créer une application pour le backoffice :

php symfony generate:app backend

Puis après créer un module géré par l’admin-generator

php symfony doctrine:generate-admin backend matable --module=le nom du module

Et voila, tout est créé. Comme vous pourrez le constater, la démarche est relativement simple. Le résultat obtenu sera proche de l’exemple ci-dessous :

D’autres exemples sur le tutoriel Jobeet

1.2 Les fonctionnalités de l’admin-generator

L’admin-generator vous créer donc une interface graphique complète avec un certains nombres de fonctionalitées attendues dans un backoffice :

Une interface graphique complète
Un CRUD complet (Create – Read – Update – Delete)
Des filtres
Des actions batchs/lists
Des messages de validations/erreurs
Une pagination

Ajoutez ensuite à cette liste la possibilité de personnaliser très simplement les différents éléments de l’interface via un fichier generator.yml.

1.3 Conclusion

Rapidement, nous pouvons tirer une première conclusion : l’admin-generator est très simple de création. Rien à redire à ce niveau.

Mais l’admin-gen est-il une solution idéale ?

2. L’aspet graphique

Une petite pensée pour ce cher LoL Guru

Il est très facile pour une personne technique de négliger un backoffice sur le plan graphique. Personnellement, tous mes backoffice sont accessible par mes clients. Il faut donc pouvoir livrer quelque chose de correct graphiquement à ce niveau et il m’a donc fallu me pencher très rapidement sur ce problème.

Graphiquement, il faut tout d’abord distinguer deux éléments : le template global de l’application et le template de chacun des modules. Il est donc possible dans un premier temps d’appliquer un style graphique via le fichier apps/backend/templates/layout.php. Cela permettra déjà d’offrir une cure de jouvence à l’interface créée par l’admin-generator.

De la même façon, vous pouvez personnaliser l’admin-generator via le fichier apps/backend/config/view.yml en ajoutant un fichier css qui viendrais remplacer certaines propriétés. Par exemple pour déplacer les filtres en haut du document et pour agrandir les champs input text, il vous suffira très simplement d’appliquer les styles suivants :

#sf_admin_bar { float: none; margin: 0 0 20px 0; }
#sf_admin_container input[type=text] {
width: 400px;
}

La encore, rien de bien compliqué. Vous pourrez donc personnaliser un certains nombres d’éléments de cette façon.

2.1 Oui mais moi, je veux vraiment tout personnaliser !

C’est un peu la que tout commence à se gâter. Si l’envie vous prenais de commencer à vouloir personnaliser les templates, vous pourriez vous apercevoir d’une chose : Il n’y a aucun fichier dans le repertoire templates des modules générés.

wow.

Mais ils sont ou alors ?

Et voila, nous venons de poser le doigt sur le principal inconvénient de l’admin-generator. La simplicité a donc bel et bien un revers. Il vous faudra en effet surcharger un certain nombre d’éléments de l’admin-generator pour pouvoir en profiter pleinement. Et pour retrouver tout ses fichiers, il vous faudra aller dans le repertoire cache de votre application et les ouvrir tour à tour pour mettre le doigt sur le contenu de l’élément concerné.

Cela peut être très simple, la personnalisation minimale étant à mon sens étant celle du fichier generator.yml dans le module concerné afin de réorganiser l’affichage.

Autre exemple avec un plugin must-have. Pour personnaliser le formulaire d’authentification de sfDoctrineGuardPlugin, il vous faudra créer un répertoire templates dans un module sfGuardAuth pour enfin faire un fichier signinSuccess.php qui vous permettra de reprendre le code.

Heureusement pour nous, il existe une liste de tous les templates utilisés :

_assets.php Rendre lees CSS et les JS pour les utiliser dans les Templates
_filters.php Rendre la zone des filtres
_filtersfield.php Rendre un seul champ du filtre
_flashes.php Rendre les messages flash
_form.php Afficher le formulaire
_form_actions.php Afficher les actions du formulaire
_form_field.php Afficher un seul champ du formulaire
_form_fieldset.php Afficher un jeu de champs du formulaire
_form_footer.php Afficher le formulaire pied de page
_form_header.php Afficher le formulaire d’entête
_list.php Afficher la liste
_list_actions.php Afficher les actions de la liste
_list_batch_actions.php Afficher les actions batch de la liste
_list_field_boolean.php Afficher un seul champ booléen dans la liste
_list_footer.php Afficher le pied de page de la liste
_list_header.php Afficher l’entête de la liste
_list_td_actions.php Afficher les actions d’un objet pour une ligne
_list_tdbatchactions.php Afficher le checkbox pour une ligne
_list_td_stacked.php Afficher le layout stacked pour une ligne
_list_td_tabular.php Afficher un seul champ pour la liste
_list_th_stacked.php Afficher un seul nom de colonne pour l’entête
_list_th_tabular.php Afficher un seul nom de colonne pour l’entête
_pagination.php Afficher la pagination de la liste
editSuccess.php Afficher la vue edit
indexSuccess.php Afficher la vue list
newSuccess.php Afficher la vue new

Cela représente donc un certain nombre de fichiers et il vous faudra prendre en compte la problématique qui pour faire simple sera la suivante :

Est-ce que j’ai un ou plusieurs templates à surcharger ?
Est-ce que cette modification est redondante à l’ensemble des modules ?

Enfin et pour conclure avec cette partie, ce travail de personnalisation complète du backoffice n’est fondamentalement pas plus complexe que pour le backoffice d’un Joomla, d’un Drupal, d’un WordPress et j’en passe. Si vous savez intégrer pour votre front-office, vous saurez le faire pour le back-office.

3. Coté code maintenant

N’y allons pas par quatre chemins, la encore vous aurez le bonheur de trouver des fichiers actions.class.php complètement vide qui vous permettront de surcharger tout ce que vous pourrez retrouver dans les fichiers stockés dans le cache.

La liste complète des actions est la suivante (attention les traductions sont un peu aléatoires ) :

executeIndex() Action de la vue list
executeFilter() Mettre à jour les filtres
executeNew() Action de la vue new
executeCreate() Création d’un enregistrement
executeEdit() Edition d’un enregistrement
executeUpdate() Mise à jour d’un enregistrement
executeDelete() Supprimer un enregistrement
executeBatch() Executer une action batch
executeBatchDelete() Executer l’action batch _delete
processForm() Processer le formulaire emploi
getFilters() Retourner le filtre actuel
setFilters() Définir le filtre
getPager() Retourner la pagination de la liste
getPage() Obtenir la page de la pagination
setPage() Définir la page de la pagination
buildQuery() Construire la requête pour la liste
addSortQuery() Ajouter la requête de tri pour la liste
getSort() Retourner la colonne triée actuelle
setSort() Définit la colonne triée actuelle

La encore, beaucoup d’éléments à prendre en compte.

3.1 Les formulaires et relations

Qui dit backoffice dit interraction avec la base de donnée et donc beaucoup de formulaires ce qui me permet de répondre à l’une des plus belles idioties entendue au Be-Zend sur l’admin-generator : Non, un module créé avec l’admin-generator n’intérragie pas forcément avec une seule des tables de votre base de donnée. Je tairais même le nom de l’auteur de cette remarque afin de préserver sa réputation (jusqu’à ce que les vidéos arrivent).

Créer un module via la commande doctrine:generate-admin c’est très basiquement créer un module avec un template généré et des fonctions prédéfinies. Vous pouvez donc intéragir de la même façon qu’avec un module classique et vous pourrez avec un seul formulaire “en apparence” travailler avec un nombre X de tables avec autant de formulaires. Je vous conseille d’ailleurs d’aller lire un article de Niko expliquant les embedForms et embedRelations.

Un embedForm pourra donc être intégré via le generator.yml en l’appelant tout simplement par son nom. Tous les champs seront appelés et vous pourrez très simplement les exploiter. Une même page d’édition/création pourra par exemple vous permettre de travailler sur votre table post et votre table seo pour une plus grande souplesse. La limite étant uniquement humaine : est-ce que vos formulaires à ralonge ne vont pas déstabiliser l’utilisateur ? (ce qui sera d’autant plus vrai dans le cadre de l’utilisation de plusieurs langue via I18n)

Inutile de le préciser, l’ensemble des champsdes formulaire sont bien évidemment personnalisable via les fichiers correpondant dans /lib/form/doctrine/xxxForm.class.php

3.2 Les actions batch et list

La encore, tout est très simple. Nous retrouvons vraiment une philosophie symfony dans l’admin generator. Créer une action batch/list consiste donc en un minimum de deux étapes :

Ajout d’un batch dans le fichier generator.yml
Création de l’action correpondante dans le fichier actions.class.php de type : public function executeBatchXXX(sfWebRequest $request) { } OU public function executeListXXX(sfWebRequest $request) { }

Cerise sur le gateau, le code que vous ferez à travers vos batchs/lists pourra être utilisé pour créer une tache symfony avec très peu de code à modifier. Cela permettra par exemple de pouvoir appeler une tache automatiquement via Cron tout en offrant la possibilité à l’utilisateur de faire la même chose via une action batch/list.

3.3 Et ce n’est pas fini

Vous pouvez rapidement faire un tour de l’ensemble des possibilités dans le chapitre dédié à l’admin-generator du tutoriel Jobeet.

4. Alors l’admin-generator killer admin ?

Par moments oui tandis que d’autres non.

Comme vous avez pu le remarquer, un nombre conséquent de possibilités sont facilement accessible via l’admin-generator mais cela implique un nombre plus ou moins important de changements. Il faudra donc avant tout chose peser le pour et le contre vis à vis du projet.

A quoi va me servir l’admin-generator (interaction complète avec le front comme un CMS ou partielle comme Jobeet par exemple)
Quel va être le niveau de personnalisation graphique ?
Quel sont les attentes en terme de fonctionnalités à surcharger ?

Les réponses à ces différentes questions vous permettront d’établir un pourcentage variable allant (à mon niveau) de 10% à presque 70% d’éléments à surcharger. L’utilisation de l’admin-generator doit donc être un élément réfléchi dont il faut peser l’impact et penser l’utilisation. Dans le cadre d’applications simples, l’admin-generator sera un outil idéal vous permettant de gagner énormément de temps mais si vous devez commencer à ajouter des fonctionnalités importantes ou de l’AJAX par exemple, les surcharges pourront devenir très importantes et le routage pourra même être impacté. Dans ce cas, un backoffice créé de toute pièce sera donc plus adapté.

Quant à la mixité admin-generator/module classique, j’ai un peu de mal à y croire car il faudra expliquer les différences graphiques entre les templates maison et ceux générés. Pour mettre à niveau le tout, il faudra donc prévoir la personnalisation de l’ensemble et donc la encore un certain nombre d’heures de travail.

Quoi qu’il en soit, l’admin-generator n’est pas à sous-estimer car il peut rendre service dans de nombreux cas en vous permettant de gagner énormément de temps. Après tout, c’est exactement ce à quoi il destiné.

By Alexandre

Comments

joujouta avril 26th

je veux personnaliser le formulaire dans _edit-form, je désire remplacer une zone texte par une liste déroulante avec des éléments fixés mais ce que j’obtient toujours à la place de ces éléments les id comment puis je procéder ?!! ainsi que j’aime bien savoir ou je peux mettre mes tests pour la validation de mes champs svp aider moi car j’aurai bientot la soutenance et j’ai pas encore terminé mon application
jaycreation septembre 1st

merci beaucoup. l’admin générator est une des possibilité de symfony que je maitrise le moins bien. C’est un très bon article qui va beaucoup m’aider.
maria juillet 18th

je veux ajouter des champs dans la liste
sf août 18th

slt à tous, j’ai executer les commandes de génération de l’application backend, et les modules. la génération d’un module, crée un répertoire au nom du module, qui contient 4 sous-répertoires. un parmi ces derniers porte le nom templates ce dernier est vide. donc la génération que j’ai fait n’a pas crée des templates, c-a-d le module est vide. je sais pas où est le problème, et je demande vous aides svp.