[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>
bin/magento dev:urn-catalog:generate [--ide IDE] [--] <path>
ausführen.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:
id
typeId
translate
label
an, damit die Beschriftung übersetzt werden kann.string
sortOrder
float
class
string
Registerknotenreferenz
Ein <tab>
-Tag kann das folgende untergeordnete Element aufweisen:
label
string
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:
id
typeId
translate
label
an, damit die Beschriftung übersetzt werden kann.string
type
text
.string
sortOrder
float
showInDefault
1
an, um den Abschnitt anzuzeigen, und 0
, um den Abschnitt auszublenden.int
showInStore
1
an, um den Abschnitt anzuzeigen, und 0
, um den Abschnitt auszublenden.int
showInWebsite
1
an, um den Abschnitt anzuzeigen, und 0
, um den Abschnitt auszublenden.int
canRestore
int
advanced
bool
extends
string
Knotenreferenz für Abschnitte
Ein <section>
-Tag kann die folgenden untergeordneten Elemente aufweisen:
label
string
class
string
tab
typeTabId
header_css
string
resource
typeAclResourceId
group
typeGroup
frontend_model
typeModel
include
system_include.xsd
kompatible Dateien einzuschließen. Wird normalerweise verwendet, um große system.xml
-Dateien zu strukturieren.includeType
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:
id
typeId
translate
label
an, damit die Beschriftung übersetzt werden kann. Mehrere Felder sollten durch ein Leerzeichen getrennt werden.string
type
text
.string
sortOrder
float
showInDefault
1
an, um die Gruppe anzuzeigen, und 0
, um die Gruppe auszublenden.int
showInStore
1
an, um die Gruppe anzuzeigen, und 0
, um die Gruppe auszublenden.int
showInWebsite
1
an, um die Gruppe anzuzeigen, und 0
, um die Gruppe auszublenden.int
canRestore
int
advanced
bool
extends
string
Knoten-Referenz für Gruppen
Ein <group>
-Tag kann die folgenden untergeordneten Elemente aufweisen:
label
string
fieldset_css
string
frontend_model
typeModel
clone_model
typeModel
clone_fields
int
help_url
typeUrl
more_url
typeUrl
demo_link
typeUrl
comment
<![CDATA[//]]>
kann HTML angewendet werden.string
hide_in_single_store_mode
1
blendet die Gruppe aus; 0
zeigt die Gruppe an.int
field
field
group
unbounded
depends
1
aufweist. Dieser Knoten erwartet eine section/group/field
-Zeichenfolge.depends
attribute
attribute
include
system_include.xsd
kompatible Dateien einzuschließen. Wird normalerweise verwendet, um große system.xml
-Dateien zu strukturieren.includeType
more_url
, demo_url
und help_url
werden durch ein PayPal-Frontend-Modell definiert, das nur einmal verwendet wird. Diese Knoten können nicht wiederverwendet werden.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:
id
typeId
translate
label
an, damit die Beschriftung übersetzt werden kann. Mehrere Felder sollten durch ein Leerzeichen getrennt werden.string
type
text
.string
sortOrder
float
showInDefault
1
an, um das Feld anzuzeigen, und 0
, um das Feld auszublenden.int
showInStore
1
an, um das Feld anzuzeigen, und 0
, um das Feld auszublenden.int
showInWebsite
1
an, um das Feld anzuzeigen, und 0
, um das Feld auszublenden.int
canRestore
int
advanced
bool
extends
string
Feldtyp-Referenz
Ein <field>
-Tag kann die folgenden Werte für das Attribut type=""
aufweisen:
text
textarea
select
source_model
. Wird auch für Yes/No
-Auswahlen verwendet. Ein Beispiel finden Sie unter Magento\Search\Model\Adminhtml\System\Config\Source\Engine
.multiselect
select
, aber mehrere Optionen sind gültig.button
Magento\ScheduledImportExport\Block\Adminhtml\System\Config\Clean
.obscure
**​**
angezeigten Wert. Wenn Sie den Typ mit "Inspect Element"im Browser ändern, wird der Wert nicht angezeigt.password
obscure
, außer dass der ausgeblendete Wert nicht verschlüsselt ist und eine erzwungene Änderung des Typs mit "Inspect-Element"im Browser den Wert anzeigt.file
label
time
allowspecific
source_model
wie Magento\Shipping\Model\Config\Source\Allspecificcountries
image
note
frontend_model
erforderlich, um die Notiz wiederzugeben.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:
- Baustein im Bereich
adminhtml
erstellen - Setzen von
type=""
auf den Pfad zu diesem Block
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:
label
string
comment
<![CDATA[//]]>
kann HTML angewendet werden.string
tooltip
string
hint
frontend_model
verfügbar.string
frontend_class
string
frontend_model
typeModel
backend_model
typeModel
source_model
typeModel
config_path
typeConfigPath
validate
string
can_be_empty
type
multiselect
ist, um anzugeben, dass ein Feld leer sein kann.int
if_module_enabled
typeModule
base_url
upload_dir
für Datei-Uploads verwendet.typeUrl
upload_dir
typeUploadDir
button_url
button_url
und button_label
angegeben sind. Wird normalerweise in Kombination mit einem benutzerdefinierten Frontend-Modell verwendet.typeUrl
button_label
button_label
und button_url
angegeben sind. Wird normalerweise in Kombination mit einem benutzerdefinierten Frontend-Modell verwendet.string
more_url
typeUrl
demo_url
typeUrl
hide_in_single_store_mode
1
blendet die Gruppe aus; 0
zeigt die Gruppe an.int
options
complexType
depends
1
aufweist. Dieser Knoten erwartet eine section/group/field
-Zeichenfolge.complexType
attribute
complexType
requires
complexType
more_url
, demo_url
, requires
und options
werden durch ein anderes Kernzahlungsmodell definiert und nur einmal verwendet. Diese Knoten können nicht wiederverwendet werden.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.
Magento\Config\Model\Config\Source\Yesnocustom
Yes
, No
und Specified
bereit.Magento\Config\Model\Config\Source\Enabledisable
Enable
, Disable
bereit. Speichert die Werte als 0
und 1
in der Datenbank.Magento\AdminNotification\Model\Config\Source\Frequency
1 Hour
, 2 Hours
, 6 Hours
, 12 Hours
und 24 Hours
bereit. Werte werden als Ganzzahlen gespeichert.Magento\Catalog\Model\Config\Source\TimeFormat
Magento\Cron\Model\Config\Source\Frequency
Daily
, Weekly
und Monthly
bereit. Werte werden in der Datenbank als D
, W
und M
gespeichert.Magento\GoogleAdwords\Model\Config\Source\Language
Magento\Config\Model\Config\Source\Locale
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:
alphanumeric
integer
ipv4
ipv6
letters-only
abcABC
.letters-with-basic-punc
Muss den folgenden Ausdruck übergeben:
/^[a-z\-.,()\u0027\u0022\s]+$/i
.mobileUK
no-marginal-whitespace
no-whitespace
phoneUK
phoneUS
required-entry
validate-no-empty
Validierung).Validierungsfehlermeldung: "Dies ist ein erforderliches Feld."
time
15
, 15:05
oder 15:05:48
.time12h
3 am
, 11:30 pm
, 02:15:00 pm
.validate-admin-password
validate-alphanum-with-spaces
validate-clean-url
https://www.example.com
oder www.example.com
.validate-currency-dollar
validate-data
Das erste Zeichen muss ein Brief sein.
(Muss mit Ausdruck übereinstimmen:
/^[A-Za-z]+[A-Za-z0-9_]+$/
)Überprüfungsfehler-Meldung: "Bitte verwenden Sie in diesem Feld nur Buchstaben (a-z oder A-Z), Zahlen (0-9) oder Unterstriche (_), und das erste Zeichen sollte ein Brief sein."
validate-date-au
validate-email
validate-emailSender
validate-fax
validate-no-empty
requried-entry
Validierung).Validierungsfehlermeldung: "Leerer Wert".
validate-no-html-tags
validate-password
validate-phoneLax
validate-phoneStrict
validate-select
null
-Wert, keinen Zeichenfolgenwert von none
oder eine Zeichenfolgenlänge von 0 aufweist.validate-ssn
validate-street
validate-url
validate-xml-identifier
validate-zip-us
vinUS
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>