functions.php
Le fichier function.php
du composant est crucial dans la définition de la logique de traitement des données et de la configuration des champs ACF qui seront utilisés dans l'interface administrateur de WordPress.
Afin d'expliquer ce fichier, nous allons prendre pour exemple le composant Gallerie : /Components/subcomponents_website/Gallerie
Le fichier function.php
est toujours composé de 3 parties obligatoires :
1. Espace de noms et importations
namespace Flynt\Components\Gallerie;
use Flynt\FieldVariables;
use Flynt\Utils\Options;
// use Timber\Term;
// use Timber\Image;
// ...
namespace
Déclare l'espace de noms pour le fichier, permettant l'organisation logique du code et évitant les conflits de nommage avec d'autres parties du thème ou des plugins.use
Les déclarations use au début du fichier permettent d'inclure d'autres classes ou fonctions de divers espaces de noms. Ceci est crucial pour la modularité et la réutilisabilité du code.use Flynt\FieldVariables
Importe la classeFieldVariables
du namespace Flynt. Cette classe est utilisée pour accéder à des variables de champ prédéfinies et des configurations utilisées dans les champs ACF (obligatoire pour ajouter des acf).use Flynt\Utils\Options
Importe la classeOptions
qui pourrait fournir des méthodes utilitaires pour gérer les options du composant.use Timber\Term
use Timber\Image
Ici, deux autres exemples permetant d'importer les classesTerm
ouImage
du plugin Timber. Cela permetant, suivant les besoin de traiter et manipuler des termes taxonomiques, des images...
2. Fonctionnalité du Composant
add_filter('Flynt/addComponentData?name=Gallerie', function ($data) {
// ... Code pour traiter les données $data du composant
});
Cette fonction ajoute un filtre à WordPress qui permet de manipuler les données avant qu'elles ne soient rendues.
- Dans ce cas (pour le composant
Gallerie
se référer au fichier/Components/subcomponents_website/Gallerie/function.php
), nous vérifions les dimensions et l'orientation d'une image et ajustons les valeurs si l'image est en mode "portrait".
Les données peuvent y être manipulées en php
avant d'êtres affichées via le fichier "vue" en twig
, une fois que la contribution aura été effectuée en administration (exeption des champs avec une valeur par défaut renseignée, qui seront directement accessibles).
Les données des champs personnalisés ACF sont donc disponibles sous la forme d'un tableau php dans la variable $data
3. Définition des Champs ACF
La fonction getACFLayout()
définit la structure ACF (Advanced Custom Fields) du composant Gallerie
. Elle retourne un tableau de configuration ACF qui détermine comment les champs doivent être affichés et gérés dans l'interface d'édition de WordPress.
function getACFLayout()
{
return [
'name' => 'Gallerie',
'label' => 'Gallerie d\'images',
'sub_fields' => [
// Onglets et Champs acf à ajouter ici
]
]
}
Dans notre thème, nous utiliserons une configuration uniforme pour tous les composants, en trois parties de champs ACF.
Vous remarquerez, dans l'administration que les composants possèdent 3 onglets :
- Général
Ici seront tous les champs ACF liés au composant. Dans notre exempleGallerie
, se trouve un champ répéteur d'images. - Options
Cet onglet permet d'ajouter facilement des champs d'options utilisés sur la plupart des composants. Cela sera souvent utilisé pour donner la possibilité d'ajouter un "id" ou des "class" dans lehtml
, de gérer la valeur du titre, d'utiliser un mode sombre ... - Espacements
Choix des marges, internes et externes du composant, afin d'agencer la page en fonction du besoin (selon les espacements de la charte graphique SNCF).
Ces 3 parties ACF, seront séparées par des champs de type Onglet
.
3.1 Général
Voici la façon d'ajouter des champs ACF au composant. Ce code ci-dessous représente la premiere partie des champs à ajouter dans les sub_fields
vu précédemment.
Cela va créer l'onglet Général
. Vous pourrez y ajouter tous les champs personnalisés liés à votre composant.
// SUB FIELDS
[
'label' => 'Général',
'name' => 'generalTab',
'type' => 'tab',
'placement' => 'top',
'endpoint' => 0,
'wpml_cf_preferences' => 1, // 1:copy, 2:translatable, 3:copy-once
],
[
'label' => 'Images',
'name' => 'items',
'type' => 'repeater',
'collapsed' => 1,
'min' => 0,
'layout' => 'row', // row, table, block
'button_label' => 'Ajouter une image',
'wpml_cf_preferences' => 1, // 1:copy, 2:translatable, 3:copy-once
'sub_fields' => [
[
'label' => 'Image',
'name' => 'image',
'type' => 'image',
'return_format' => 'array',
'preview_size' => 'thumbnail',
'library' => 'all',
'mime_types' => 'gif,jpg,jpeg,png,svg',
'wpml_cf_preferences' => 1, // 1:copy, 2:translatable, 3:copy-once
],
]
]
- La première partie (
'label' => 'Général'
) permet de définir notre premier onglet. - La suite, dans notre exemple du composant
Gallerie
nous ajoutons un champ typerepeater
avec un sous-champ de typeimage
.
3.2 Options
Ce code ci-dessous représente la seconde partie des champs à ajouter dans les sub_fields
vu précédemment.
Cela va créer l'onglet Options
. Vous pourrez y ajouter facilement des champs globaux, avec un nommage spécifique permetant leur utilisation automatique dans les templates twig (id, class, valeur du titre ...).
// OPTIONS
[
'label' => 'Options',
'name' => 'optionsTab',
'type' => 'tab',
'placement' => 'top',
'endpoint' => 0,
'wpml_cf_preferences' => 1,
],
[
'label' => '',
'name' => 'options',
'type' => 'group',
'layout' => 'row',
'wpml_cf_preferences' => 1,
'sub_fields' => [
FieldVariables\getGlobalOption([
'getClassOption',
'getIdOption',
// ['getTitleValue','h2'],
// 'getAlignCenterContent',
]),
]
],
- La première partie (
'label' => 'Options'
) permet de définir notre second onglet. - La suite, dans notre exemple du composant
Gallerie
nous incluons les deux champs permettant de récupérer une liste declass
ainsi qu'unid
. - En commentaire, un exemple permetant d'ajouter un champ "Valeur du titre", avec une valeur par défaut réglée sur
h2
Vous trouverez la liste des options disponibles à ajouter dans le fichier <votre-projet>/inc/utilities/fieldVariables.php
.
3.3 Espacements
Ce code ci-dessous représente la dernière partie des champs à ajouter dans les sub_fields
vu précédemment.
Cela va créer l'onglet Espacements
. Un simple appel Php va ajouter cet onglet et ses sous-champ au composant. Cela intégrera aussi automatiquement les classes html liées au espacements visuel dans le fichier twig
votre composant.
// ESPACEMENTS
FieldVariables\getMarginOption(),
Vous pourrez également si nécessaire appliquer des valeurs par défaut sur les 4 types de marges :
// ESPACEMENTS
FieldVariables\getMarginOption([
'mt'=>'mt-bigger',
'mb'=>'mb-bigger',
'pt'=>'pt-bigger',
'pb'=>'pb-bigger'
] ),