Contrôles avancés pour widgets Elementor : repeater, responsive, conditions

Développer un widget Elementor qui se contente d’un champ texte et d’une couleur ne demande pas grand-chose. Les choses se corsent dès que le widget doit accepter une liste d’éléments modifiable par l’utilisateur, s’adapter différemment sur mobile, ou masquer certains réglages selon le contexte. C’est exactement ce que couvrent trois outils du framework de contrôles d’Elementor : le Repeater, les contrôles responsive, et les conditions d’affichage.

Cet article détaille leur fonctionnement avec un exemple concret : un widget « Équipe » qui affiche une liste de membres, chacun avec un nom, un rôle, et une icône optionnelle. Le code présenté est fonctionnel et respecte les conventions du framework de contrôles d’Elementor, tel qu’il s’utilise dans register_controls().

Le Repeater, pour les listes d’éléments répétés

La classe \Elementor\Repeater permet de créer un groupe de contrôles que l’utilisateur peut dupliquer autant de fois que nécessaire depuis l’interface : une ligne par membre d’équipe, par témoignage, par élément de FAQ, etc. Chaque instance du repeater conserve son propre jeu de valeurs, indépendant des autres lignes.

Le principe consiste à instancier un objet Repeater, à lui ajouter des contrôles comme on le ferait sur un widget classique, puis à injecter la liste de ces contrôles dans un contrôle parent de type Controls_Manager::REPEATER, via add_control().

Contrôles responsive et conditions d’affichage

La méthode add_responsive_control() fonctionne comme add_control(), à un détail près : Elementor génère automatiquement une version du réglage pour chaque appareil (ordinateur, tablette, mobile), avec les icônes de bascule correspondantes dans l’interface. Elle est particulièrement utile pour des valeurs comme le nombre de colonnes, l’espacement ou l’alignement, qui doivent souvent différer entre desktop et mobile.

La clé condition, disponible sur n’importe quel contrôle, permet de n’afficher ce contrôle que si un autre contrôle du même groupe possède une valeur donnée. C’est ce mécanisme qui permet, par exemple, de ne montrer le sélecteur d’icône que si l’utilisateur a activé l’option « Afficher une icône » juste au-dessus.

<?php
use Elementor\Widget_Base;
use Elementor\Controls_Manager;
use Elementor\Repeater;

class Team_Members_Widget extends Widget_Base {

    public function get_name() {
        return 'team-members';
    }

    public function get_title() {
        return __( 'Équipe', 'wpmoderne' );
    }

    public function get_icon() {
        return 'eicon-person';
    }

    public function get_categories() {
        return [ 'general' ];
    }

    protected function register_controls() {

        $this->start_controls_section(
            'section_members',
            [
                'label' => __( 'Membres', 'wpmoderne' ),
            ]
        );

        $repeater = new Repeater();

        $repeater->add_control(
            'member_name',
            [
                'label'   => __( 'Nom', 'wpmoderne' ),
                'type'    => Controls_Manager::TEXT,
                'default' => __( 'Nom du membre', 'wpmoderne' ),
            ]
        );

        $repeater->add_control(
            'member_role',
            [
                'label'   => __( 'Rôle', 'wpmoderne' ),
                'type'    => Controls_Manager::TEXT,
                'default' => __( 'Poste occupé', 'wpmoderne' ),
            ]
        );

        $repeater->add_control(
            'show_icon',
            [
                'label'        => __( 'Afficher une icône', 'wpmoderne' ),
                'type'         => Controls_Manager::SWITCHER,
                'label_on'     => __( 'Oui', 'wpmoderne' ),
                'label_off'    => __( 'Non', 'wpmoderne' ),
                'return_value' => 'yes',
                'default'      => '',
            ]
        );

        $repeater->add_control(
            'member_icon',
            [
                'label'     => __( 'Icône', 'wpmoderne' ),
                'type'      => Controls_Manager::ICONS,
                'condition' => [
                    'show_icon' => 'yes',
                ],
            ]
        );

        $this->add_control(
            'members',
            [
                'label'       => __( 'Liste des membres', 'wpmoderne' ),
                'type'        => Controls_Manager::REPEATER,
                'fields'      => $repeater->get_controls(),
                'default'     => [],
                'title_field' => '{{{ member_name }}}',
            ]
        );

        $this->add_responsive_control(
            'columns',
            [
                'label'   => __( 'Colonnes', 'wpmoderne' ),
                'type'    => Controls_Manager::SELECT,
                'default' => '3',
                'tablet_default' => '2',
                'mobile_default' => '1',
                'options' => [
                    '1' => '1',
                    '2' => '2',
                    '3' => '3',
                    '4' => '4',
                ],
                'selectors' => [
                    '{{WRAPPER}} .team-grid' => 'grid-template-columns: repeat({{VALUE}}, 1fr);',
                ],
            ]
        );

        $this->end_controls_section();
    }
}

Les types de contrôles les plus courants

La classe Controls_Manager centralise les constantes correspondant aux types de contrôles disponibles. Sur la plupart des widgets, quelques types reviennent sans cesse :

• Controls_Manager::TEXT pour un champ texte simple, comme un titre ou une légende.
• Controls_Manager::SELECT pour une liste déroulante avec un ensemble fixe d’options.
• Controls_Manager::ICONS pour le sélecteur d’icônes intégré, qui ouvre la bibliothèque d’icônes du site.
• Controls_Manager::SWITCHER pour un interrupteur booléen, souvent utilisé comme condition pour un autre contrôle.
• Controls_Manager::REPEATER pour intégrer un groupe de contrôles répétable, comme démontré plus haut.

Chaque type accepte ses propres options spécifiques (la liste options pour un SELECT, les libellés label_on/label_off pour un SWITCHER), documentées dans le code source du framework de contrôles. Le plus efficace, pour découvrir les options disponibles d’un type donné, reste d’observer comment les widgets natifs d’Elementor les utilisent.

Pièges fréquents à éviter

Quelques erreurs reviennent régulièrement chez les développeurs qui découvrent ce framework de contrôles :

• Oublier d’appeler get_controls() sur l’instance du Repeater avant de l’injecter dans fields : sans cet appel, Elementor reçoit un objet au lieu d’un tableau et lève une erreur.
• Définir une condition qui référence un nom de contrôle mal orthographié : la condition échoue silencieusement, sans message d’erreur visible, ce qui rend le débogage plus long.
• Multiplier les contrôles responsive sur des propriétés qui n’ont, dans les faits, jamais besoin de changer entre desktop et mobile : chaque contrôle responsive ajouté alourdit un peu plus le panneau de réglages pour l’utilisateur final.

Testez toujours un nouveau contrôle avec le bouton de réinitialisation d’Elementor (l’icône en forme de flèche circulaire à côté du champ). Si la valeur ne revient pas au default défini dans le code, c’est souvent le signe d’une clé mal nommée dans le tableau de configuration.

En résumé

Repeater, contrôles responsive et conditions d’affichage forment le socle technique qui distingue un widget Elementor amateur d’un widget réellement confortable à utiliser au quotidien. Ils demandent un peu de rigueur dans la structuration du code PHP, mais une fois assimilés, ils se combinent facilement pour construire des interfaces de réglage aussi riches que celles des widgets natifs du builder.