component

La fonction component permet d'afficher un composant réutilisable dans l'écosystème Elementum.

Utilisation

{{ component(nom_du_composant, arguments, projet) }}

Exemple pratique

{{ component('card', {
    'title': 'Titre de la carte',
    'content': 'Contenu de la carte',
    'image': 'chemin/vers/image.jpg'
}) }}

Paramètres

Paramètre	Type	Description
name	string	Requis. Nom du composant à afficher. Le fichier doit se trouver dans views/components/nom_du_composant.html.twig
args	array	Optionnel. Tableau associatif des variables à passer au composant. Par défaut : []
project_name	string|false	Optionnel. Nom du projet contenant le composant. Valeurs acceptées : false (thème courant), "child", slug d'un plugin, ou nom du thème. Par défaut : false

Emplacement des composants

attention

Les composants doivent être placés dans le dossier views/components/ de votre projet et doivent avoir l'extension .html.twig.

Exemple de structure :

views/
  components/
    card.html.twig
    button.html.twig
    header.html.twig

Résolution du projet (project_name)

Le paramètre project_name détermine dans quel projet Elementum chercher le composant :

Valeur	Résolution
false (défaut)	Thème parent actif (get_template_directory())
"child"	Thème enfant actif (get_stylesheet_directory())
"theme"	Alias explicite du thème parent
slug d'un plugin	Dossier du plugin (wp-content/plugins/<slug>)

{# Composant dans le thème enfant #}
{{ component('custom-hero', {}, 'child') }}

{# Composant dans un plugin #}
{{ component('pricing-table', data, 'mon-plugin') }}

Normalisation des arguments

La fonction accepte différents types pour le paramètre args et les normalise automatiquement en tableau associatif avant de les passer au template :

Type reçu	Comportement
array	Passé tel quel
stdClass	Converti via get_object_vars()
Tout autre objet	Converti via cast (array)
Scalaire (string, int…)	Encapsulé dans ['value' => …]

{# Toutes ces formes sont valides #}
{{ component('card', { title: 'Mon titre' }) }}
{{ component('card', cardData) }}      {# cardData peut être un objet #}
{{ component('card', 'valeur simple') }} {# disponible via {{ value }} dans le template #}

Pipeline d'extensibilité — #[Hook]

Chaque appel à component() passe automatiquement par le service twig.hook. Cela signifie qu'un contrôleur peut surcharger le template ou enrichir les variables d'un composant via l'attribut #[Hook], sans modifier le code source du thème.

Le nom du hook généré correspond au chemin du composant avec / remplacé par . :

• component('front-page/about') → hook front-page.about
• component('card') → hook card

app/Controller/HooksController.php

use Elementum\Attributes\Hook;

class HooksController extends Controller
{
    #[Hook('front-page.about', '@child/about-custom.html.twig')]
    public function about(array $args): array
    {
        return [
            ...$args,
            'subtitle' => 'Contenu injecté depuis le thème enfant',
        ];
    }
}

astuce

Pour les cas simples où vous voulez juste un point d'extension avant/après un composant (sans le surcharger), utilisez plutôt hook() :

{{ hook('before.about') }}
{{ component('front-page/about', about) }}
{{ hook('after.about') }}

Bonnes pratiques

• Utilisez des noms de composants descriptifs en kebab-case (ex: user-profile-card)
• Privilégiez la composition de plusieurs petits composants plutôt que des composants trop complexes
• Passez toujours un tableau associatif en args pour nommer explicitement les variables disponibles dans le template
• Utilisez #[Hook] dans un thème enfant pour étendre un composant du thème parent sans le modifier