[Contribution David Lambauer]{class="badge informative" title="David Lambauer"} [PaaS uniquement]{class="badge informative" title="S’applique uniquement aux projets Adobe Commerce on Cloud (infrastructure PaaS gérée par Adobe) et aux projets On-premise."}

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 présente 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 d’entités différents, qui sont liés les uns 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 sur le serveur principal d’administration.
Des carrés rouges indiquent 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 en tant que 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 avoir un ou plusieurs champs. Les champs sont la plus petite entité
dans le contexte de configuration du système.

Onglets

Un <tab>-Tag fait référence à un onglet existant ou à un nouvel onglet de la configuration du système.

Référence d’attribut d’onglet

Une <tab>-balise peut avoir les attributs suivants :

Référence du nœud d’onglet

Une <tab>-balise 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 onglet avec l’identifiant A_UNIQUE_ID. Comme l’attribut translate est défini et référence le libellé, l’attribut label est traduisible. Pendant le processus de rendu, la classe CSS a-custom-css-class-to-style-this-tab sera appliquée à l’élément HTML qui a été 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 de la configuration du système.

Référence d’attribut de section

Une <section>-balise peut avoir les attributs suivants :

Référence du nœud de section

Une <section>-balise peut avoir les enfants suivants :

Exemple : créez une section et affectez-la à 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 le A_UNIQUE_SECTION_ID d’ID. Il est visible dans la vue de configuration par défaut et dans un contexte de magasin. Le label-nœud 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 qui disposent des autorisations définies dans la VENDOR_MODULE::path_to_the_acl_resource ACL.

Groupes

La <group>-balise est utilisée pour regrouper des champs.

Référence d’attribut de groupe

Une <group>-balise peut avoir les attributs suivants :

Référence du nœud du groupe

Une <group>-balise 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 le A_UNIQUE_GROUP_ID d’ID. Il est visible dans la vue de configuration par défaut et dans un contexte de magasin. Les label et les comment sont marqués comme traduisibles.

Champs

La <field>-balise est utilisée à l’intérieur des <group>-balises pour définir des valeurs de configuration spécifiques.

Référence d’attribut de champ

Une <field>-balise peut avoir les attributs suivants :

Référence du type de champ

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

Il est également possible de créer un type de champ personnalisé. Cela est souvent fait 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 un procédé de __construct et un procédé de 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 se présente comme 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 nœud de champ

Une <field>-balise 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 dans la vue par défaut et dans la vue de magasin. Les deux champs comportent un commentaire et une info-bulle pour décrire leur objectif à l’utilisateur. Le label-nœud peut être traduit.
Le champ portant l’identifiant ANOTHER_UNIQUE_FIELD_ID est visible lorsque le module donné dans l’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 définit A_UNIQUE_FIELD_ID un modèle source différent qui fournit les valeurs Yes et No.

Modèles sources courants

Les modèles sources ci-dessous sont fournis par Commerce 2 Core. En général, il existe beaucoup plus de modèles sources ; la liste suivante décrit les plus courants. Gardez à l’esprit que ces modèles source nécessitent que l’attribut de champ type soit défini sur select pour fonctionner correctement.

Validation de champ

Une ou plusieurs classes de validation peuvent être attribuées à un champ pour s’assurer que l’entrée de l’utilisateur répond aux 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 disponibles sont les suivantes :

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 nœud section/group/field_ID .

Exemple : définition de la valeur par défaut pour ANOTHER_UNIQUE_FIELD_ID (Étendue 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 (étendue 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>