[Ein Beitrag von David Lambauer]{class="badge informative" title="David Lambauer"} [Nur PaaS]{class="badge informative" title="Gilt nur für Adobe Commerce in Cloud-Projekten (von Adobe verwaltete PaaS-Infrastruktur) und lokale Projekte."}

System.Xml-Referenz

Mit der system.xml können Sie die Commerce-Systemkonfiguration verwalten. Verwenden Sie dieses Thema als allgemeine Referenz für die system.xml. Die system.xml befindet sich unter etc/adminhtml/system.xml in einer bestimmten Commerce 2-Erweiterung.

Das folgende Codefragment zeigt das bloße Skelett der Datei:

<?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>

Registerkarten // Abschnitte // Gruppen // Felder

In der system.xml-Datei können vier verschiedene Typen von Entitäten definiert werden, die miteinander verknüpft sind. Im folgenden Abschnitt wird die Beziehung zwischen Registerkarten, Abschnitten, Gruppen und Feldern beschrieben. Der folgende Screenshot zeigt die Commerce 2-Systemkonfiguration im Admin-Backend.
Die roten Quadrate kennzeichnen die verschiedenen Typen, die in der system.xml definiert sind:

Registerkarten werden verwendet, um verschiedene Konfigurationsbereiche semantisch aufzuteilen. Jede Registerkarte kann einen oder mehrere Abschnitte enthalten, die auch als Untermenüs referenziert werden können. Ein Abschnitt enthält eine oder mehrere Gruppen.
Jede Gruppe listet ein oder mehrere Felder auf. Sie können auch eine Gruppe verwenden, um eine allgemeine Beschreibung für die folgenden Felder hinzuzufügen. Wie bereits erwähnt, kann jede Gruppe ein oder mehrere Felder enthalten. Felder sind die kleinste Entität
im Systemkonfigurationskontext.

Registerkarten

Ein <tab>-Tag verweist entweder auf eine vorhandene oder eine neue Registerkarte in der Systemkonfiguration.

Attributverweis für Registerkarte

Ein <tab>-Tag kann die folgenden Attribute aufweisen:

Tab-Knotenreferenz

Ein <tab>-Tag kann das folgende untergeordnete Element haben:

Beispiel: Erstellen einer Registerkarte

Das folgende Codefragment veranschaulicht die Erstellung einer neuen Registerkarte mit Beispieldaten.

<?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>

Der obige Ausschnitt erstellt eine neue Registerkarte mit der A_UNIQUE_ID. Da das translate-Attribut definiert ist und auf die Beschriftung verweist, ist der label-Knoten übersetzbar. Während des Renderings wird die CSS-Klasse a-custom-css-class-to-style-this-tab auf das HTML-Element angewendet, das für diese Registerkarte erstellt wurde.
Das sortOrder-Attribut mit dem Wert 10 definiert die Position der Registerkarte in der Liste aller Registerkarten, wenn sie gerendert wird.

Abschnitte

Ein <section>-Tag verweist entweder auf einen vorhandenen oder einen neuen Abschnitt in der Systemkonfiguration.

Abschnittsattributverweis

Ein <section>-Tag kann die folgenden Attribute aufweisen:

Knotenreferenz des Abschnitts

Ein <section>-Tag kann die folgenden untergeordneten Elemente aufweisen:

Beispiel: Abschnitt erstellen und einer Registerkarte zuweisen

Das folgende Codefragment veranschaulicht die grundlegende Verwendung beim Erstellen eines neuen Abschnitts.

<?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>

Der oben beschriebene Abschnitt definiert die ID A_UNIQUE_SECTION_ID, ist in der Standardkonfigurationsansicht und in einem Store-Kontext sichtbar. Der label-Knoten ist übersetzbar. Der Abschnitt ist mit der Registerkarte mit der ID A_UNIQUE_ID verknüpft. Der Abschnitt kann nur von Benutzern aufgerufen werden, die über die in der ACL-VENDOR_MODULE::path_to_the_acl_resource definierten Berechtigungen verfügen.

Gruppen

Der <group>-Tag wird verwendet, um Felder zu gruppieren.

Gruppenattributverweis

Ein <group>-Tag kann die folgenden Attribute aufweisen:

Gruppenknoten-Referenz

Ein <group>-Tag kann die folgenden untergeordneten Elemente aufweisen:

Beispiel: Erstellen einer Gruppe für einen bestimmten Abschnitt

Das folgende Codefragment veranschaulicht die grundlegende Verwendung beim Erstellen einer neuen Gruppe.

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

Die oben beschriebene Gruppe definiert die ID A_UNIQUE_GROUP_ID und ist in der Standardkonfigurationsansicht und in einem Store-Kontext sichtbar. Sowohl die label als auch die comment werden als übersetzbar markiert.

Felder

Der <field>-Tag wird innerhalb von <group>-Tags verwendet, um bestimmte Konfigurationswerte zu definieren.

Feldattributverweis

Ein <field>-Tag kann die folgenden Attribute aufweisen:

Feldtyp-Referenz

Ein <field>-Tag kann die folgenden Werte für das type="" haben:

Es ist auch möglich, einen benutzerdefinierten Feldtyp zu erstellen. Dies geschieht häufig, wenn eine spezielle Schaltfläche mit einer Aktion erforderlich ist. Dazu sind zwei Hauptelemente erforderlich:

Für den Block selbst sind mindestens eine __construct und eine getElementHtml() erforderlich. Die Magento_OfflineShipping ist ein einfaches Beispiel für einen benutzerdefinierten Typ.

Beispielsweise ist im Modul OfflineShipping die Schaltfläche Exportieren in Magento\OfflineShipping\Block\Adminhtml\Form\Field\Export definiert und die Felddefinition sieht wie folgt aus:

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

Knotenreferenz des Feldes

Ein <field>-Tag kann die folgenden untergeordneten Elemente aufweisen:

Beispiel: Zwei Felder in einer bestimmten Gruppe erstellen

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

Im obigen Beispiel werden zwei Felder erstellt, die standardmäßig und in der Store-Ansicht beide sichtbar/konfigurierbar sind. Beide Felder enthalten einen Kommentar und eine QuickInfo, um dem Benutzer den Zweck zu beschreiben. Der label-Knoten ist übersetzbar.
Das Feld mit der Kennung ANOTHER_UNIQUE_FIELD_ID ist sichtbar, wenn das angegebene Modul in der if_module_enabled global aktiviert ist. Das Feld validiert seinen Wert auch anhand der Regeln required-entry und no-whitespace.
Das Feld mit dem Bezeichner A_UNIQUE_FIELD_ID definiert ein anderes Quellmodell, das die Werte Yes und No.

Allgemeine Quellmodelle

Die folgenden Quellmodelle werden vom Commerce 2 Core bereitgestellt. Im Allgemeinen gibt es viele weitere Quellmodelle. In der folgenden Liste werden die häufigsten beschrieben. Beachten Sie, dass bei diesen Quellmodellen das Feldattribut type auf select gesetzt werden muss, damit es ordnungsgemäß funktioniert.

Feldüberprüfung

Einem Feld können eine oder mehrere Validierungsklassen zugewiesen sein, um sicherzustellen, dass die Eingabe des Benutzers die Anforderungen der Erweiterung erfüllt. Validierungsregeln können mit dem <validate>-Tag angewendet werden.
Im folgenden Beispiel wird ein Feld validiert und es werden mehrere verschiedene Validierungsregeln hinzugefügt.

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

Die folgenden Validierungsregeln sind verfügbar:

Standardwerte

Standardwerte für Felder können in der etc/config.xml des Moduls festgelegt werden, indem der Standardwert im section/group/field_ID angegeben wird.

Beispiel: Standardwert für ANOTHER_UNIQUE_FIELD_ID festlegen (Standardbereich)

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

Beispiel: Standardwert für ANOTHER_UNIQUE_FIELD_ID festlegen (Website-Umfang)

Geben Sie mithilfe des websites-Tags den Standardwert für eine bestimmte Website an.

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