Skip to main content

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

/Components/subcomponents_website/Gallerie/functions.php
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 classe FieldVariables 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 classe Options 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 classes Term ou Image du plugin Timber. Cela permetant, suivant les besoin de traiter et manipuler des termes taxonomiques, des images...

2. Fonctionnalité du Composant

/Components/subcomponents_website/Gallerie/functions.php
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).

tip

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.

/Components/subcomponents_website/Gallerie/functions.php
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 :

Onglets ACF d'un composant

  1. Général
    Ici seront tous les champs ACF liés au composant. Dans notre exemple Gallerie, se trouve un champ répéteur d'images.
  2. 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 le html, de gérer la valeur du titre, d'utiliser un mode sombre ...
  3. 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.

/Components/subcomponents_website/Gallerie/functions.php
// 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 type repeater avec un sous-champ de type image.

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 ...).

/Components/subcomponents_website/Gallerie/functions.php
// 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 de class ainsi qu'un id.
  • En commentaire, un exemple permetant d'ajouter un champ "Valeur du titre", avec une valeur par défaut réglée sur h2
tip

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.

/Components/subcomponents_website/Gallerie/functions.php
// ESPACEMENTS
FieldVariables\getMarginOption(),

Vous pourrez également si nécessaire appliquer des valeurs par défaut sur les 4 types de marges :

/Components/subcomponents_website/Gallerie/functions.php
// ESPACEMENTS
FieldVariables\getMarginOption([
'mt'=>'mt-bigger',
'mb'=>'mb-bigger',
'pt'=>'pt-bigger',
'pb'=>'pb-bigger'
] ),