Tutoriel "créer un champ Bazar custom"


Introduction


Ce tutoriel permet d'ajouter un champ Bazar custom pour ajouter dans une fiche un lien vers la fiche.

Pré-requis


  • Avoir accès aux fichiers d'un YesWiki (soit en local, soit via ftp).
  • Avoir quelques bases de programmation (niveau débutant suffisant).
  • Connaître les bases du html

Instructions

1. se rendre dans le dossier `custom/` 2. créer si nécessaire le dossier `fields/` ce qui donne l'adresse complète `custom/fields/` 3. créer un fichier texte se nommant `LinkToEntryField.php`, ce qui donne le chemin complet `custom/fields/LinkToEntryField.php`. _Dans YesWiki, nous avons pour convention de nommer la fin des fichiers de code pour les champs avec `Field.php` et de les placer dans le dossier `fields/` de l'extension concernée._ 4. Modifier le fichier en ajoutant en au début - `<?php` pour indiquer que c'est un fichier php - `namespace YesWiki\Custom\Field;` pour indiquer que c'est un champ de custom (remplacer `Custom` par le nom de votre extension si vous travaillez dans le dossier d'une extension) - ajouter `use Psr\Container\ContainerInterface;`et `use YesWiki\Bazar\Field\BazarField;` qui sont deux lignes nécessaires pour indiquer à l'exécuteur php les noms complets des classes `ContainerInterface`et `BazarField`. - puis mettre le code de définition de la classe. **Il est important que le nom de la classe soit le même que le nom du fichier** ```php class LinkToEntryField extends BazarField { } ``` Vous devriez avoir ceci: ```php <?php namespace YesWiki\Custom\Field; use Psr\Container\ContainerInterface; use YesWiki\Bazar\Field\BazarField; class LinkToEntryField extends BazarField { } ``` 6. Ajouter une annotation de classe pour indiquer le nom que le champ aura dans les formulaires, en copiant le texte suivant avant la définition de la classe : ```php /** * @Field({"linktoentry","lienverslafiche"}) */ ``` Vous obtenez ceci : ```php <?php namespace YesWiki\Custom\Field; use Psr\Container\ContainerInterface; use YesWiki\Bazar\Field\BazarField; /** * @Field({"linktoentry","lienverslafiche"}) */ class LinkToEntryField extends BazarField { } ``` Nous avons choisi ici que les mots `linktoentry` et `lienverslafiche` seront reliés à ce champ custom. Vous pouvez ne laisser qu'un seul mot, modifier les mots à votre convenance et en ajouter autant que vous voulez, séparés par des virgule, entourés par des guillemets, en faisant attention de ne pas utiliser un mot déjà affecté à un autre champ. 7. Nous ajoutons le contructeur (la fontion qui permet de contruire le champ) dans la classe. Ici, il ne fait qu'appeler le contructeur de la classe mère `BazarField` mais il efface aussi le nom de `propertyName` (vu que nous n'avons pas besoin de sauvegarder des données, pas besoin de `propertyName`). `propertyName` est défini dans la classe mère BazarField. ```php class LinkToEntryField extends BazarField { public function __construct(array $values, ContainerInterface $services) { parent::__construct($values, $services); $this->propertyName = null ; } } ``` 8. Ajouter ensuite la fonction qui définit le formulaire de saisie pour ce champ (ici rien, `null`) ```php protected function renderInput($entry) { // No input need to be displayed for field return null; } ``` 9. Ajouter ensuite la fonction qui prépare les données à sauvegarder (ici rien, `[]` = un tableau vide) ```php public function formatValuesBeforeSave($entry) { // Return no value to save return []; } ``` 10. Ajouter ensuite la fonction affiche le lien lors de l'accès à la fiche ```php protected function renderStatic($entry) { return $this->render("@custom/field/link-to-entry.twig", [ 'entry_id' => $entry['id_fiche'], ]); } ``` Cette fonction appelle un autre fichier qui va définir le code html. Nous passons un paramètre à ce fichier : `entry_id`. `@custom/fields` permet d'indiquer que le fichier est ranger dans le dossier `custom/templates/custom/fields`. `@tags/inputs/mon-fichiers.twig` aurait indiqué que le fichier `mon-fichiers.twig` se situe dans le dossier `tools/tags/templates/inputs`. Par convention, le dossier `fields/` contient les fichiers `.twig` pour la fonction `renderStatic` et le dossier `inputs/` ceux pour la fonction `renderInput`. Le code complet du fichier est donc: ```php <?php namespace YesWiki\Custom\Field; use Psr\Container\ContainerInterface; use YesWiki\Bazar\Field\BazarField; /** * @Field({"linktoentry","lienverslafiche"}) */ class LinkToEntryField extends BazarField { public function __construct(array $values, ContainerInterface $services) { parent::__construct($values, $services); $this->propertyName = null ; } protected function renderInput($entry) { // No input need to be displayed for field return null; } public function formatValuesBeforeSave($entry) { // Return no value to save return []; } protected function renderStatic($entry) { return $this->render("@custom/fields/link-to-entry.twig", [ 'entry_id' => $entry['id_fiche'], ]); } } ``` 11. pour que tout ceci fonctionne, il faut aussi définir le fichier .twig, le modèle de code html. - se rendre dans le dossier `custom` - créer si nécessaire le dossier `templates` - dans ce nouveau dossier, créer ci nécessaire le dossier `custom` - dans ce nouveau dossier, créer ci nécessaire le dossier `fields` - créer le fichier `link-to-entry.twig` dans ce dossier en faisant attention à ce que son no msoit identique à celui utilisé précédemment. - le chemin complet du fichier est donc : `custom/templates/custom/fields/link-to-entry.twig` - y copier le code suivant : ```twig <a href="{{ url({tag:entry_id}) }}" title="Afficher la fiche">Lien vers la fiche</a> ``` Ici , nous mettons le lien vers la fiche. Il est généré grâce à la fonction `url()` qui récupère le paramètre `entry_id` fournit par le php. Noter que cette fonction est entourée de `{{` et `}}` qui est une convention de `.twig` pour indiquer qu'il faut afficher le contenu. 12. Pour utiliser ce champ,: - se rendre à la page `https://www.example.fr/?Bazar`, - créer ou modifier un formulaire - ajouter un champ `custom`(ne pas confondre avec `custom html`). - paramètre 0 : `linktoentry` 13. afficher une fiche de ce formulaire pour constater la présence du lien vers cette fiche