Créer un enhancer ################# 1. Définition dans le fichier :file:`metadata` ============================================== Les metadata d'un enhancer sont décrites dans la :ref:`documentation d'API `. 2. [Back-office] Créer un contrôleur pour l'enhancer ==================================================== Pour gérer la popup de configuration et la prévisualisation de l'enhancer, nous avons besoin d'un contrôleur. Créez donc le fichier :file:`mon_appli::classes/controller/admin/enhancer.ctrl.php` en étendant le ``Controller_Admin_Enhancer`` adéquat. .. code-block:: php array( 'mon_appli' => array( 'dialog' => array( 'contentUrl' => 'admin/mon_appli/enhancer/popup', 'ajax' => true, ), ), ), ); Ici, la popup fera appel à la méthode ``action_popup()`` de la classe ``Mon\Appli\Controller_Admin_Enhancer``. Ce dernier est prévu pour fonctionner en Ajax. Comme pour toute modification du fichier :file:`metadata.config.php`, il faut aller appliquer les changements depuis le gestionnaire d'applications. Désormais, lorsqu'on ajoute notre enhancer dans un WYSIWYG, une popup s'affiche, mais il n'y a aucune option à configurer ! Le contrôleur standard que nous avons étendu prévoit d'être configuré pour ajouter les options de l'enhancer. Rendez-vous dans le fichier de configuration :file:`mon_appli::config/controller/admin/enhancer.config.php` : .. code-block:: php :emphasize-lines: 4-13 array( 'item_per_page' => array( 'label' => __('Item per page:'), 'form' => array( 'type' => 'text', 'value' => 10, // This is only the default ), ), ), ); La syntaxe des ``fields`` est identique à celle du fichier de configuration du CRUD, avec possibilité de mettre des renderers. Lorsque vous configurez uniquement les ``fields`` et que vous n'avez pas renseigné ``popup.layout``, le contrôleur en ajoute un automatiquement pour vous avec cette configuration : .. code-block:: php :emphasize-lines: 4-16 array( 'layout' => array( 'fields' => array( 'view' => 'nos::form/fields', 'params' => array( 'fields' => array(/* Liste de tous les champs renseignés dans 'fields' */), 'begin' => ' ', 'end' => ' ', ), ), ), ), ); Si vous souhaitez modifier ce ``layout`` par défaut (par exemple rajouter une 2e vue pour inclure du JavaScript), vous **devez** le renseigner en totalité (et remettre la vue ``nos::form/fields`` si vous en avez besoin). À l'intérieur des vues, les variables suivantes sont disponibles : - ``$enhancer_args`` : l'ancienne configuration de l'enhancer ; - ``$fieldset`` : lorsque vous avez renseignés des ``fields``, un ``Fieldset`` est créé dans cette variable. .. _app_create/enhancer/preview: Modifier la prévisualisation ---------------------------- .. image:: images/metadata_enhancer.png :alt: L'enhancer « Formulaire » :align: center La prévisualisation ajoutée dans le WYSIWYG est chargée en faisant appel à la valeur ``previewUrl`` configurée dans le fichier :file:`metadata.config.php`. Généralement, vous ferez appel au même contrôleur que celui de la popup, mais en appelant la méthode ``action_preview()`` au lieu de ``action_popup()``. La vue fournie par défaut utilise une icône, un titre (les valeurs par défaut reprennent l'icône 64*64 de l'application, ainsi que le titre de l'enhancer) et un ``layout`` (fichiers de vues additionnels appelés). :file:`mon_appli::config/controller/admin/enhancer.config.php` : .. code-block:: php :emphasize-lines: 8-18 array( // Ce qu'on avait configuré plus tôt ), // Configuration de la prévisualisation 'preview' => array( // (facultatif) vue à utiliser pour le rendu (valeur par défaut en exemple) //'view' => 'nos::admin/enhancer/preview', // (facultatif) fichiers de vues additionnels (inclus par la view au-dessus) //'layout' => array(), 'params' => array( // (optionnel) reprend le titre de l'enhancer par défaut 'title' => "Mon super enhancer", // 'icon' (optionnel) reprend celui de l'application en taille 64*64 par défaut ), ), ); À noter qu'il est possible de spécifier une fonction de callback à la fois pour le titre ou pour l'icône. Elle recoit alors un paramètre : la configuration de l'enhancer ``$enhancer_args``. Par exemple, pour l'enhancer « Formulaire », le titre du formulaire sélectionné s'affiche. .. _app_create/enhancer/front: 3. [Front-office] Afficher votre contenu sur le site ==================================================== Une fois la page enregistrée et publiée, l'enhancer va s'exprimer sur le site. Le contenu sera généré par le contrôleur configuré dans une des clés ``enhancer`` ou ``urlEnhancer`` du fichier :file:`metadata.config.php` (selon si on voulait un enhancer simple ou un URL enhancer). N'oubliez pas de prendre en compte les changements dans le gestionnaires d'applications si vous faites des modification sur ce fichier. Par exemple, l'application « Formulaires » a pour configuration ``noviusos_form/front/main`` ce qui fera appel à la méthode ``action_main()`` du ``Controller_Front`` de l'application ``noviusos_form`` (qui correspond en fait au contrôleur ``Nos\Form\Controller_Front``). Cette action prend en paramètre le tableau de configuration qui a été défini dans la popup de configuration ``$enhancer_args``. Créons le contrôleur :file:`mon_appli::controller/front.ctrl.php` .. code-block:: php main_controller->getEnhancerUrl();``. Ensuite, le contrôleur peut générer du contenu différent en fonction de l'URL demandée. Voici un exemple (simplifié) tiré de l'application « Blog » : .. code-block:: php $enhancer_url == 'category/ski' (sans .html) $enhancer_url = $this->main_controller->getEnhancerUrl(); $segments = explode('/', $enhancer_url); if (empty($enhancer_url)) { // URL 'mon/blog.html' (URL de la page sur laquelle a été ajouté l'enhancer) // Affichage de la liste des billets (page 1) } else if (count($segments) == 1) { // URL 'mon/blog/toto.html' // Affichage du billet de blog 'toto' } else if (count($segments) == 2) { if ($segments[0] == 'page') { // URL 'mon/blog/page/2.html' $page = $segments[1]; // Affichage de la page 2 de la liste des billets } else if ($segments[0] == 'category') { // URL 'mon/blog/category/ski.html' $category = $segments[1]; // Affichage de la liste des billets de la catégorie 'ski' } } // L'URL demandé n'est pas gérée par cet enhancer (erreur 404 pour cet enhancer) throw new \Nos\NotFoundException(); } } .. _app_create/enhancers: Lorsque l'enhancer gère des URL pour certains modèles (ORM), c'est lui qui connait la procédure de génération des ces dernières. Pour ce faire, il faut alors implémenter une méthode statique ``getUrlEnhanced()`` qui va s'en occuper : .. code-block:: php :emphasize-lines: 7-29 virtual_name()).'.html'; break; // URL pour la liste des billets d'une catégorie (avec optionnellement une page) case 'Nos\Blog\Model_Category' : return 'category/'.urlencode($item->virtual_name()).($page > 1 ? '/'.$page : '').'.html'; break; } } return false; } } Cette fonction est liée à la ``Behaviour_Urlenhancer`` et aux méthodes ``url()`` et ``urls()`` des modèles. Pour voir comment les configurer, il faut se référer à la :ref:`documentation d'API associée `. Exemple : .. code-block:: php url(array('page' => 2)); ``$url`` aura pour valeur ``mon/blog/category/ski/2.html``. Si on décompose : - ``mon/blog`` : URL de la page sur laquelle est présent l'enhancer ; - ``ski`` : URL virtuelle de la catégorie ayant pour ID 1 ; - ``2`` : numéro de page demandée dans les paramètes.