[Beitrag von David Lambauer]{class="badge informative" title="David Lambauer"}

system.xml-Referenz

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

Das folgende Code-Snippet zeigt das leere 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 Datei system.xml können vier verschiedene Entitätstypen definiert werden, die miteinander verbunden 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 markieren die verschiedenen Typen, die in der Datei system.xml definiert sind:

Registerkarten werden verwendet, um verschiedene Konfigurationsbereiche semantisch zu teilen. 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 über ein oder mehrere Felder verfügen. Felder sind die kleinsten Entitäten
im Systemkonfigurationskontext.

Registerkarten

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

Registerattributreferenz

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

Registerknotenreferenz

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

Beispiel: Erstellen einer Registerkarte

Das folgende Codefragment zeigt 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 Kennung "A_UNIQUE_ID". Da das Attribut translate-definiert ist und auf den Titel verweist, ist der Knoten label übersetzbar. Während des Rendervorgangs 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 Attribut sortOrder mit dem Wert 10 definiert die Position der Registerkarte in der Liste aller Registerkarten, wenn sie gerendert wird.

Abschnitte

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

Abschnittsattributreferenz

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

Knotenreferenz für Abschnitte

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

Beispiel: Erstellen Sie einen Abschnitt und weisen Sie ihn einer Registerkarte zu

Das folgende Codefragment zeigt die grundlegende Verwendung der Erstellung 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>

Im oben beschriebenen Abschnitt wird die ID A_UNIQUE_SECTION_ID definiert, die in der standardmäßigen Konfigurationsansicht und in einem Store-Kontext angezeigt wird. Der Knoten label kann übersetzt werden. Der Abschnitt ist der Registerkarte mit der ID A_UNIQUE_ID zugeordnet. Auf den Abschnitt können nur Benutzer zugreifen, für die die in ACL VENDOR_MODULE::path_to_the_acl_resource definierten Berechtigungen definiert sind.

Gruppen

Das Tag <group>-Tag dient der Gruppierung von Feldern.

Gruppenattributreferenz

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

Knoten-Referenz für Gruppen

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

Beispiel: Erstellen einer Gruppe für einen bestimmten Abschnitt

Das folgende Codefragment zeigt die grundlegende Verwendung der Erstellung 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, ist in der standardmäßigen Konfigurationsansicht und in einem Store-Kontext sichtbar. Sowohl die label als auch die comment sind als übersetzbar markiert.

Felder

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

Feldattributreferenz

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

Feldtyp-Referenz

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

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

Der Block selbst erfordert mindestens eine __construct -Methode und eine getElementHtml() -Methode. Magento_OfflineShipping ist ein einfaches Beispiel für einen benutzerdefinierten Typ.

Beispielsweise wird im OfflineShipping-Modul 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>

Feldknotenreferenz

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

Beispiel: Erstellen Sie zwei Felder in einer bestimmten 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" 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 sowohl standardmäßig als auch in der Store-Ansicht sichtbar/konfigurierbar sind. Beide Felder verfügen über einen Kommentar und eine QuickInfo, um den Zweck für den Benutzer zu beschreiben. Der Knoten label kann übersetzt werden.
Das Feld mit der Kennung ANOTHER_UNIQUE_FIELD_ID ist sichtbar, wenn das angegebene Modul im if_module_enabled global aktiviert ist. Das Feld validiert seinen Wert auch anhand der Regeln required-entry und no-whitespace.
Das Feld mit der Kennung A_UNIQUE_FIELD_ID definiert ein anderes Quellmodell, das die Werte Yes und No bereitstellt.

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 für diese Quellmodelle das Feldattribut type auf select gesetzt werden muss, damit es ordnungsgemäß funktioniert.

Feldvalidierung

In einem Feld können eine oder mehrere Validator-Klassen zugewiesen werden, 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 mehrere unterschiedliche 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 Datei "etc/config.xml" des Moduls festgelegt werden, indem der Standardwert im Knoten "section/group/field_ID"angegeben wird.

Beispiel: Einstellen des Standardwerts für ANOTHER_UNIQUE_FIELD_ID (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: Einstellen des Standardwerts für ANOTHER_UNIQUE_FIELD_ID (Website-Umfang)

Geben Sie mithilfe des Tags websites 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>