[Contribution de David Lambauer]{class="badge informative" title="David Lambauer"}

référence system.xml

Le fichier system.xml vous permet de gérer la configuration du système Commerce. Utilisez cette rubrique comme référence générale pour le fichier system.xml. Le fichier system.xml se trouve sous etc/adminhtml/system.xml dans une extension Commerce 2 donnée.

Le fragment de code suivant affiche le squelette nu du fichier :

<?xml version="1.0" ?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Config:etc/system_file.xsd">
    <system>
        <!-- PLACE YOUR MODULE SPECIFIC CONFIGURATION HERE -->
    </system>
</config>

Onglets // Sections // Groupes // Champs

Dans le fichier system.xml, il est possible de définir quatre types différents d’entités, qui sont liées les unes aux autres. La section suivante décrit la relation entre les onglets, les sections, les groupes et les champs. La capture d’écran suivante affiche la configuration du système Commerce 2 dans le serveur principal d’administration.
Les carrés rouges représentent les différents types définis dans le fichier system.xml :

Les onglets sont utilisés pour fractionner sémantiquement différentes zones de configuration. Chaque onglet peut contenir une ou plusieurs sections, qui peuvent également être référencées sous forme de sous-menus. Une section contient un ou plusieurs groupes.
Chaque groupe répertorie un ou plusieurs champs. Vous pouvez également utiliser un groupe pour ajouter une description générale pour les champs suivants. Comme mentionné, chaque groupe peut comporter un ou plusieurs champs. Les champs sont la plus petite entité
dans le contexte de configuration du système.

Onglets

Une balise <tab> fait référence à un onglet existant ou nouveau dans la configuration du système.

Référence d’attribut d’onglet

Une balise <tab> peut avoir les attributs suivants :

Référence du noeud de tabulation

Une balise <tab> peut avoir l’enfant suivant :

Exemple : créer un onglet

Le fragment de code suivant illustre la création d’un nouvel onglet avec des exemples de données.

<?xml version="1.0" ?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Config:etc/system_file.xsd">
    <system>
        <tab id="A_UNIQUE_ID" translate="label" class="a-custom-css-class-to-style-this-tab" sortOrder="10">
            <label>A meaningful label</label>
        </tab>
    </system>
</config>

Le fragment de code ci-dessus crée un nouvel onglet avec l’identifiant A_UNIQUE_ID. Comme l’attribut translate est défini et référence le libellé, le noeud label peut être traduit. Pendant le processus de rendu, la classe CSS a-custom-css-class-to-style-this-tab sera appliquée à l’élément d’HTML créé pour cet onglet.
L’attribut sortOrder avec la valeur 10 définit la position de l’onglet dans la liste de tous les onglets lors du rendu.

Sections

Une balise <section> fait référence à une section existante ou nouvelle dans la configuration du système.

Référence d’attribut de section

Une balise <section> peut avoir les attributs suivants :

Référence de noeud de section

Une balise <section> peut avoir les enfants suivants :

Exemple : créer une section et l’affecter à un onglet

Le fragment de code suivant illustre l’utilisation de base de la création d’une section.

<?xml version="1.0" ?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Config:etc/system_file.xsd">
    <system>
        <tab id="A_UNIQUE_ID" translate="label" class="a-custom-css-class-to-style-this-tab" sortOrder="10">
            <label>A meaningful label</label>
        </tab>

        <section id="A_UNIQUE_SECTION_ID" showInDefault="1" showInWebsite="0" showInStore="1" sortOrder="10" translate="label">
            <label>A meaningful section label</label>
            <tab>A_UNIQUE_ID</tab>
            <resource>VENDOR_MODULE::path_to_the_acl_resource</resource>
        </section>
    </system>
</config>

La section décrite ci-dessus définit l’ID A_UNIQUE_SECTION_ID, qui est visible dans la vue de configuration par défaut et dans un contexte de magasin. Le noeud label peut être traduit. La section est associée à l’onglet avec l’ID A_UNIQUE_ID. La section n'est accessible que par les utilisateurs disposant des autorisations définies dans l'ACL VENDOR_MODULE::path_to_the_acl_resource.

Groupes

La balise <group> sert à regrouper les champs.

Référence d’attribut de groupe

Une balise <group> peut avoir les attributs suivants :

Référence de noeud de groupe

Une balise <group> peut avoir les enfants suivants :

Exemple : créer un groupe pour une section donnée

Le fragment de code suivant illustre l’utilisation de base de la création d’un groupe.

<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Config:etc/system_file.xsd">
    <system>
        <tab id="A_UNIQUE_ID" translate="label" class="a-custom-css-class-to-style-this-tab" sortOrder="10">
            <label>A meaningful label</label>
        </tab>

        <section id="A_UNIQUE_SECTION_ID" showInDefault="1" showInWebsite="0" showInStore="1" sortOrder="10" translate="label">
            <label>A meaningful section label</label>
            <tab>A_UNIQUE_ID</tab>
            <resource>VENDOR_MODULE::path_to_the_acl_resource</resource>

            <group id="A_UNIQUE_GROUP_ID" translate="label comment" sortOrder="10" showInDefault="1" showInWebsite="0" showInStore="1">
                <label>A meaningful group label</label>
                <comment>An additional comment helping users to understand the effect when configuring the fields defined in this group.</comment>
                <!-- Add your fields here. -->
            </group>
        </section>
    </system>
</config>

Le groupe décrit ci-dessus définit l’ID A_UNIQUE_GROUP_ID, qui est visible dans la vue de configuration par défaut et dans un contexte de magasin. Les balises label et comment sont toutes deux marquées comme traduisibles.

Champs

La balise <field>-est utilisée dans les balises <group>-pour définir des valeurs de configuration spécifiques.

Référence d’attribut de champ

Une balise <field> peut avoir les attributs suivants :

Référence de type de champ

Une balise <field> peut avoir les valeurs suivantes pour l’attribut type="" :

Il est également possible de créer un type de champ personnalisé. Cela est souvent effectué lorsqu’un bouton spécial, avec une action, est requis. Pour ce faire, deux éléments principaux sont nécessaires :

Le bloc lui-même nécessite, au minimum, une méthode __construct et une méthode getElementHtml(). Magento_OfflineShipping est un exemple simple de type personnalisé.

Par exemple, dans le module OfflineShipping, le bouton Exporter est défini dans Magento\OfflineShipping\Block\Adminhtml\Form\Field\Export et la définition du champ ressemble à ce qui suit :

<field id="export" translate="label" type="Magento\OfflineShipping\Block\Adminhtml\Form\Field\Export" sortOrder="5" showInDefault="0" showInWebsite="1" showInStore="0">
    <label>Export</label>
</field>

Référence du noeud de champ

Une balise <field> peut avoir les enfants suivants :

Exemple : créer deux champs dans un groupe donné

<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Config:etc/system_file.xsd">
    <system>
        <tab id="A_UNIQUE_ID" translate="label" class="a-custom-css-class-to-style-this-tab" sortOrder="10">
            <label>A meaningful label</label>
        </tab>

        <section id="A_UNIQUE_SECTION_ID" showInDefault="1" showInWebsite="0" showInStore="1" sortOrder="10" translate="label">
            <label>A meaningful section label</label>
            <tab>A_UNIQUE_ID</tab>
            <resource>VENDOR_MODULE::path_to_the_acl_resource</resource>

            <group id="A_UNIQUE_GROUP_ID" translate="label" sortOrder="10" showInDefault="1" showInWebsite="0" showInStore="1">
                <label>A meaningful group label</label>
                <comment>An additional comment helping users to understand the effect when configuring the fields defined in this group.</comment>

                <field id="A_UNIQUE_FIELD_ID" translate="label" sortOrder="10" showInDefault="0" showInWebsite="0" showInStore="1" type="select">
                    <label>Feature Flag Example</label>
                    <comment>This field is an example for a basic yes or no select.</comment>
                    <tooltip>Usually these kinds of fields are used to enable or disable a given feature. Other fields might be dependent to this and will only appear if this field is set to yes.</tooltip>
                    <source_model>Magento\Config\Model\Config\Source\Yesno</source_model>
                </field>

                <field id="ANOTHER_UNIQUE_FIELD_ID" translate="label" sortOrder="10" showInDefault="0" showInWebsite="0" showInStore="1" type="text">
                    <label>A meaningful field label</label>
                    <comment>A descriptive text explaining this configuration field.</comment>
                    <tooltip>Another possible frontend element that also can be used to describe the meaning of this field. Will be displayed as a small icon beside the field.</tooltip>
                    <validate>required-entry no-whitespace</validate> <!-- Field is required and must not contain any whitespace. -->
                    <if_module_enabled>VENDOR_MODULE</if_module_enabled>
                    <depends> <!-- This field will only be visible if the field with the id A_UNIQUE_FIELD_ID is set to value 1 -->
                        <field id="A_UNIQUE_FIELD_ID">1</field>
                    </depends>
                </field>
            </group>
        </section>
    </system>
</config>

L’exemple ci-dessus crée deux champs, visibles/configurables par défaut et en mode magasin. Les deux champs ont un commentaire et une info-bulle pour décrire leur objectif à l’utilisateur. Le noeud label peut être traduit.
Le champ avec l’identifiant ANOTHER_UNIQUE_FIELD_ID est visible lorsque le module donné dans if_module_enabled est activé globalement. Le champ valide également sa valeur par rapport aux règles required-entry et no-whitespace.
Le champ avec l’identifiant A_UNIQUE_FIELD_ID définit un modèle source différent qui fournit les valeurs Yes et No.

Modèles sources courants

Les modèles sources suivants sont fournis par Commerce 2 Core. En général, il existe beaucoup d’autres modèles sources ; la liste suivante décrit les modèles les plus courants. N’oubliez pas que ces modèles source ont besoin que l’attribut de champ type soit défini sur select pour fonctionner correctement.

Validation de champ

Une ou plusieurs classes validator peuvent être affectées à un champ pour s’assurer que l’entrée de l’utilisateur respecte les exigences de l’extension. Les règles de validation peuvent être appliquées avec la balise <validate>.
L’exemple suivant valide un champ et ajoute plusieurs règles de validation différentes.

<field id="A_CUSTOM_IDENTIFIER" showInDefault="1" showInWebsite="0" showInStore="1">
    <validate>required-entry validate-clean-url no-whitespace</validate>
</field>

Les règles de validation suivantes sont disponibles :

Valeurs par défaut

Les valeurs par défaut des champs peuvent être définies dans le fichier etc/config.xml du module en spécifiant la valeur par défaut dans le noeud section/group/field_ID.

Exemple : définition de la valeur par défaut pour ANOTHER_UNIQUE_FIELD_ID (périmètre par défaut)

<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Store:etc/config.xsd">
    <default>
        <A_UNIQUE_SECTION_ID>
            <A_UNIQUE_GROUP_ID>
                <ANOTHER_UNIQUE_FIELD_ID>This is the default value</ANOTHER_UNIQUE_FIELD_ID>
            </A_UNIQUE_GROUP_ID>
        </A_UNIQUE_SECTION_ID>
    </default>
</config>

Exemple : définition de la valeur par défaut pour ANOTHER_UNIQUE_FIELD_ID (périmètre du site web)

À l’aide de la balise websites, spécifiez la valeur par défaut d’un site web spécifique.

<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Store:etc/config.xsd">
    <websites>
        <WEBSITE_CODE>
            <A_UNIQUE_SECTION_ID>
                <A_UNIQUE_GROUP_ID>
                    <ANOTHER_UNIQUE_FIELD_ID>This is the default value</ANOTHER_UNIQUE_FIELD_ID>
                </A_UNIQUE_GROUP_ID>
            </A_UNIQUE_SECTION_ID>
        </WEBSITE_CODE>
    </websites>
</config>