Qui sommes nous ?
a
M

Suivez nous

Acceuil > Tous nos articles Magento & Ecommerce > Magento 2 : switcherConfig – Créer des champs dépendants en XML pur

Magento 2 : switcherConfig – Créer des champs dépendants en XML pur

Qu’est-ce que switcherConfig ?

switcherConfig est un outil puissant des UI Components Magento qui permet de définir des règles pour contrôler le comportement d’un champ en fonction de la valeur d’un autre champ, sans écrire une seule ligne de JavaScript. Concrètement, vous pouvez afficher/masquer des champs, modifier leur validation, les activer/désactiver, ou exécuter d’autres actions en fonction de sélections utilisateur.

C’est particulièrement utile dans les formulaires du back-office (BO) Magento, où les dépendances entre champs sont fréquentes.

Structure XML de switcherConfig

Intégration dans le formulaire

Le switcherConfig s’ajoute dans le nœud <settings> de votre champ déclencheur (généralement un select ou un radio):

<field name="country">
  <argument name="data" xsi:type="array">
    <item name="config" xsi:type="array">
      <item name="formElement" xsi:type="string">select</item>
      <item name="component" xsi:type="string">Magento_Ui/js/form/element/select</item>
      <item name="options" xsi:type="array">
        <item name="0" xsi:type="array">
          <item name="value" xsi:type="string">FR</item>
          <item name="label" xsi:type="string" translate="true">France</item>
        </item>
        <item name="1" xsi:type="array">
          <item name="value" xsi:type="string">US</item>
          <item name="label" xsi:type="string" translate="true">États-Unis</item>
        </item>
      </item>
    </item>
  </argument>
  <settings>
    <switcherConfig>
      <enabled>true</enabled>
      <rules>
        <!-- Les règles vont ici -->
      </rules>
    </switcherConfig>
  </settings>
</field>

Anatomie d’une règle

Chaque règle est déclarée comme un élément numéroté dans le tableau rules. Important : commencez toujours à 0, sinon Magento risque de planter :

<rules>
  <item name="0" xsi:type="array">
    <item name="value" xsi:type="string">FR</item>
    <item name="actions" xsi:type="array">
      <item name="0" xsi:type="array">
        <item name="target" xsi:type="string">namespace.namespace.fieldset.field_name</item>
        <item name="callback" xsi:type="string">show</item>
      </item>
      <item name="1" xsi:type="array">
        <item name="target" xsi:type="string">namespace.namespace.fieldset.other_field</item>
        <item name="callback" xsi:type="string">hide</item>
      </item>
    </item>
  </item>
  <item name="1" xsi:type="array">
    <item name="value" xsi:type="string">US</item>
    <item name="actions" xsi:type="array">
      <item name="0" xsi:type="array">
        <item name="target" xsi:type="string">namespace.namespace.fieldset.field_name</item>
        <item name="callback" xsi:type="string">hide</item>
      </item>
    </item>
  </item>
</rules>

Éléments clés :

  • value : la valeur du champ déclencheur qui déclenche cette règle.
  • target : le chemin complet du champ cible au format namespace.namespace.fieldset.field_name. Le namespace est doublé (ex. : dumfr_customernew_form.dumfr_customernew_form)
  • callback : l’action à exécuter sur le champ cible (voir section suivante). params (optionnel) : paramètres à passer au callback.

Callbacks disponibles

Les callbacks les plus courants sont :

  • show : affiche le champ cible.
  • hide : masque le champ cible.
  • enable : active le champ cible.
  • disable : désactive le champ cible.
  • setValidation : modifie les règles de validation du champ cible.

Exemple pour setValidation :

<item name="0" xsi:type="array">
  <item name="target" xsi:type="string">dumfr_customernew_form.dumfr_customernew_form.company_fieldset.vat_id</item>
  <item name="callback" xsi:type="string">setValidation</item>
  <item name="params" xsi:type="array">
    <item name="0" xsi:type="string">required-entry</item>
    <item name="1" xsi:type="boolean">true</item>
  </item>
</item>

Ici, on ajoute la validation required-entry au champ vat_id lorsque la règle est déclenchée.

Limitations et contournements

Limitation 1 : Correspondance exacte de valeur

Par défaut, switcherConfig ne déclenche une règle que si la valeur correspond exactement. Pour un select avec des centaines d’options, c’est peu pratique. Utilisez un wildcard * en étendant la mixin :

define([
    'Magento_Ui/js/form/switcher'
], function (Switcher) {
    'use strict';

    return function (switcher) {
        return switcher.extend({
            applyRule: function (rule, value) {
                if (rule.value === '*') {
                    rule.actions.forEach(this.applyAction, this);
                    return;
                }

                return this._super(rule, value);
            }
        });
    };
});

Puis déclarez cette mixin dans votre requirejs-config.js :

    config: {
        mixins: {
            'Magento_Ui/js/form/switcher': {
                'Dummy_Backend/js/form/switcher-mixin': true
            }
        }
    }

Vous pouvez alors utiliser :

<item name="value" xsi:type="string">*</item>
<item name="actions" xsi:type="array">
  <!-- Cette règle s'applique pour TOUTE valeur -->
</item>

Limitation 2 : Impossible de modifier directement le required

Le callback setValidation ne permet pas de changer directement l’attribut required d’un champ. Pour contourner cela, utilisez la mixin ci dessus sur Magento_Ui/js/form/switcher :

// Vendor/Module/view/adminhtml/web/js/form/switcher-mixin.js
define([
    'Magento_Ui/js/form/switcher',
    'uiRegistry'
], function (Switcher, registry) {
    'use strict';

    return function (switcher) {
        return switcher.extend({
            applyAction: function (action) {
                this._super(action);
 
                // adapt false according rules (if required used and value linked)
                registry.get(action.target, function (target) {
                  target.required(false);
                   target.validate()
                });
            }
        });
    };
});

Pourquoi le changement de required-entry ne marche pas ? tout simplement parce que dans le setValidation de magento on trouve :

            if (changed) {
                this.required(!!rules['required-entry']);
                this.validate();
            }

Et cette portion de code ne prend pas en compte la nouvelle règle

Bonnes pratiques

  • Testez vos chemins de target : une erreur dans le chemin namespace.namespace.fieldset.field rendra la règle silencieuse et inefficace.
  • Commencez l’indexation à 0 : toujours utiliser <item name="0"...> pour la première règle, sinon Magento plante.
  • Utilisez des mixins pour étendre : plutôt que de modifier le core, créez des mixins pour ajouter des callbacks personnalisés ou des wildcards.
  • Combinez plusieurs actions : une seule règle peut déclencher plusieurs actions sur différents champs.

En résumé : switcherConfig est un outil XML puissant pour gérer les dépendances entre champs sans JavaScript. Avec quelques mixins bien placées, vous pouvez dépasser ses limitations natives et créer des formulaires dynamiques et sophistiqués.