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