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

> Repeater, contrôles responsive, conditions d'affichage : un tutoriel PHP concret pour construire des widgets Elementor sur mesure vraiment confortables à utiliser.

- Auteur : Clément Hadrot
- Publié le : 2021-04-15
- Mis à jour le : 2021-04-15
- Catégorie : Elementor
- URL : https://wpmoderne.dev.wordpress-developpement.fr/elementor/controles-avances-widgets-elementor-repeater-responsive-conditions/

## L’essentiel

- Construire un Repeater avec la classe Repeater d'Elementor
- Ajouter des réglages responsive avec add_responsive_control
- Masquer un contrôle selon la valeur d'un autre

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();
    }
}
```

> L'essentiel à retenir : Construire un Repeater avec la classe Repeater d'Elementor ; Ajouter des réglages responsive avec add_responsive_control ; Masquer un contrôle selon la valeur d'un autre

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