[Contributo di David Lambauer]{class="badge informative" title="David Lambauer"}
riferimento system.xml
Il file system.xml
consente di gestire la configurazione del sistema Commerce. Utilizzare questo argomento come riferimento generale per il file system.xml
. Il file system.xml
si trova in etc/adminhtml/system.xml
in una determinata estensione di Commerce 2.
Il seguente frammento di codice mostra l'ossatura del file:
<?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>
.Schede // Sezioni // Gruppi // Campi
Nel file system.xml
è possibile definire quattro diversi tipi di entità, che sono correlati tra loro. Nella sezione seguente viene descritta la relazione tra schede, sezioni, gruppi e campi. La schermata seguente mostra la configurazione del sistema di Commerce 2 nel backend di amministrazione.
I quadrati rossi contrassegnano i diversi tipi definiti nel file system.xml
:
Le schede vengono utilizzate per dividere semanticamente diverse aree di configurazione. Ogni scheda può contenere una o più sezioni, a cui è possibile fare riferimento come sottomenu. Una sezione contiene uno o più gruppi.
Ogni gruppo elenca uno o più campi. È inoltre possibile utilizzare un gruppo per aggiungere una descrizione generale per i campi seguenti. Come accennato, ogni gruppo può avere uno o più campi. I campi sono l’entità più piccola
nel contesto di configurazione del sistema.
Schede
Un tag <tab>
fa riferimento a una scheda esistente o nuova nella configurazione di sistema.
Riferimento attributo scheda
Un tag <tab>
può avere i seguenti attributi:
id
typeId
translate
label
per rendere traducibile l'etichetta.string
sortOrder
float
class
string
Riferimento nodo scheda
Un tag <tab>
può avere il seguente elemento figlio:
label
string
Esempio: creare una scheda
Il seguente frammento di codice illustra la creazione di una nuova scheda con dati di esempio.
<?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>
Il frammento precedente crea una nuova scheda con l'identificatore A_UNIQUE_ID
. Poiché l'attributo translate
è definito e fa riferimento all'etichetta, il nodo label
è traducibile. Durante il rendering, la classe CSS a-custom-css-class-to-style-this-tab
verrà applicata all'elemento HTML creato per questa scheda.
L'attributo sortOrder
con il valore di 10
definisce la posizione della scheda nell'elenco di tutte le schede sottoposte a rendering.
Sezioni
Un tag <section>
fa riferimento a una sezione esistente o nuova nella configurazione di sistema.
Riferimento attributo sezione
Un tag <section>
può avere i seguenti attributi:
id
typeId
translate
label
per rendere traducibile l'etichetta.string
type
text
.string
sortOrder
float
showInDefault
1
per visualizzare la sezione e 0
per nasconderla.int
showInStore
1
per visualizzare la sezione e 0
per nasconderla.int
showInWebsite
1
per visualizzare la sezione e 0
per nasconderla.int
canRestore
int
advanced
bool
extends
string
Riferimento nodo sezione
Un tag <section>
può avere i seguenti figli:
label
string
class
string
tab
typeTabId
header_css
string
resource
typeAclResourceId
group
typeGroup
frontend_model
typeModel
include
system_include.xsd
. Utilizzato in genere per strutturare file system.xml
di grandi dimensioni.includeType
Esempio: creare una sezione e assegnarla a una scheda
Il seguente frammento di codice illustra l'utilizzo di base della creazione di una nuova sezione.
<?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 sezione descritta sopra definisce l'ID A_UNIQUE_SECTION_ID
, che è visibile nella vista di configurazione predefinita e in un contesto di archivio. Il nodo label
è traducibile. La sezione è associata alla scheda con ID A_UNIQUE_ID
. È possibile accedere alla sezione solo da utenti che dispongono delle autorizzazioni definite nell'ACL VENDOR_MODULE::path_to_the_acl_resource
.
Gruppi
Il tag <group>
viene utilizzato per raggruppare i campi.
Riferimento attributo gruppo
Un tag <group>
può avere i seguenti attributi:
id
typeId
translate
label
per rendere traducibile l'etichetta. Più campi devono essere separati da uno spazio.string
type
text
.string
sortOrder
float
showInDefault
1
per mostrare il gruppo e 0
per nasconderlo.int
showInStore
1
per mostrare il gruppo e 0
per nasconderlo.int
showInWebsite
1
per mostrare il gruppo e 0
per nasconderlo.int
canRestore
int
advanced
bool
extends
string
Riferimento nodo di gruppo
Un tag <group>
può avere i seguenti figli:
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[//]]>
HTML è possibile applicare.string
hide_in_single_store_mode
1
nasconde il gruppo; 0
mostra il gruppo.int
field
field
group
unbounded
depends
1
. Questo nodo richiede una stringa section/group/field
.depends
attribute
attribute
include
system_include.xsd
. Utilizzato in genere per strutturare file system.xml
di grandi dimensioni.includeType
more_url
, demo_url
e help_url
sono definiti da un modello front-end PayPal utilizzato una sola volta. Questi nodi non sono riutilizzabili.Esempio: creare un gruppo per una determinata sezione
Il seguente frammento di codice illustra l'utilizzo di base della creazione di un nuovo gruppo.
<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>
Il gruppo descritto sopra definisce l'ID A_UNIQUE_GROUP_ID
, è visibile nella vista di configurazione predefinita e in un contesto di archivio. Sia label
che comment
sono contrassegnati come traducibili.
Campi
Il tag <field>
viene utilizzato all'interno dei tag <group>
per definire valori di configurazione specifici.
Riferimento attributo campo
Un tag <field>
può avere i seguenti attributi:
id
typeId
translate
label
per rendere traducibile l'etichetta. Più campi devono essere separati da uno spazio.string
type
text
.string
sortOrder
float
showInDefault
1
per visualizzare il campo e 0
per nascondere il campo.int
showInStore
1
per visualizzare il campo e 0
per nascondere il campo.int
showInWebsite
1
per visualizzare il campo e 0
per nascondere il campo.int
canRestore
int
advanced
bool
extends
string
Riferimento tipo di campo
Un tag <field>
può avere i seguenti valori per l'attributo type=""
:
text
textarea
select
source_model
personalizzato. Utilizzato anche per Yes/No
selezioni. Vedi Magento\Search\Model\Adminhtml\System\Config\Source\Engine
per un esempio.multiselect
select
, ma sono valide più opzioni.button
Magento\ScheduledImportExport\Block\Adminhtml\System\Config\Clean
per un esempio.obscure
**​**
. Se si modifica il tipo utilizzando l’elemento "Inspect" nel browser, il valore non viene visualizzato.password
obscure
, tranne per il fatto che il valore nascosto non è crittografato e la modifica forzata del tipo tramite "Inspect Element" nel browser non rivela il valore.file
label
time
allowspecific
source_model
come Magento\Shipping\Model\Config\Source\Allspecificcountries
image
note
frontend_model
per eseguire il rendering della nota.È inoltre possibile creare un tipo di campo personalizzato. Questa operazione viene spesso eseguita quando è necessario un pulsante speciale, con un’azione. A tal fine sono necessari due elementi principali:
- Creazione di un blocco in
adminhtml
- Impostazione di
type=""
nel percorso di questo blocco
Il blocco stesso richiede almeno un metodo __construct
e un metodo getElementHtml()
. Magento_OfflineShipping è un semplice esempio di tipo personalizzato.
Nel modulo OfflineShipping, ad esempio, il pulsante Esporta è definito in Magento\OfflineShipping\Block\Adminhtml\Form\Field\Export
e la definizione del campo è simile alla seguente:
<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>
Riferimento nodo di campo
Un tag <field>
può avere i seguenti figli:
label
string
comment
<![CDATA[//]]>
HTML è possibile applicare.string
tooltip
string
hint
frontend_model
specifico.string
frontend_class
string
frontend_model
typeModel
backend_model
typeModel
source_model
typeModel
config_path
typeConfigPath
validate
string
can_be_empty
type
è multiselect
per specificare che un campo può essere vuoto.int
if_module_enabled
typeModule
base_url
upload_dir
per i caricamenti di file.typeUrl
upload_dir
typeUploadDir
button_url
button_url
e button_label
. Di solito utilizzato in combinazione con un modello front-end personalizzato.typeUrl
button_label
button_label
e button_url
. Di solito utilizzato in combinazione con un modello front-end personalizzato.string
more_url
typeUrl
demo_url
typeUrl
hide_in_single_store_mode
1
nasconde il gruppo; 0
mostra il gruppo.int
options
complexType
depends
1
. Questo nodo richiede una stringa section/group/field
.complexType
attribute
complexType
requires
complexType
more_url
, demo_url
, requires
e options
sono definiti da un diverso modello di pagamento di base e vengono utilizzati una sola volta. Questi nodi non sono riutilizzabili.Esempio: creare due campi in un determinato gruppo
<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'esempio precedente crea due campi, entrambi visibili/configurabili nella visualizzazione predefinita e nella visualizzazione punto vendita. Entrambi i campi hanno un commento e una descrizione per descriverne lo scopo per l’utente. Il nodo label
è traducibile.
Il campo con l'identificatore ANOTHER_UNIQUE_FIELD_ID
è visibile quando il modulo specificato in if_module_enabled
è abilitato a livello globale. Il valore del campo viene convalidato anche in base alle regole required-entry
e no-whitespace
.
Il campo con identificatore A_UNIQUE_FIELD_ID
definisce un modello di origine diverso che fornisce i valori Yes
e No
.
Modelli di origine comuni
I seguenti modelli di origine sono forniti da Commerce 2 Core. In generale, ci sono molti più modelli di origine; l'elenco seguente descrive quelli più comuni. Tenere presente che questi modelli di origine richiedono che l'attributo del campo type
sia impostato su select
per funzionare correttamente.
Magento\Config\Model\Config\Source\Yesnocustom
Yes
, No
e Specified
.Magento\Config\Model\Config\Source\Enabledisable
Enable
, Disable
. Salva i valori come 0
e 1
nel database.Magento\AdminNotification\Model\Config\Source\Frequency
1 Hour
,2 Hours
,6 Hours
,12 Hours
e 24 Hours
. I valori vengono salvati come numeri interi.Magento\Catalog\Model\Config\Source\TimeFormat
Magento\Cron\Model\Config\Source\Frequency
Daily
, Weekly
e Monthly
. I valori vengono salvati nel database come D
, W
e M
.Magento\GoogleAdwords\Model\Config\Source\Language
Magento\Config\Model\Config\Source\Locale
Convalida campo
A un campo possono essere assegnate una o più classi di convalida per garantire che l’input dell’utente soddisfi i requisiti dell’estensione. Le regole di convalida possono essere applicate con il tag <validate>
.
Nell'esempio seguente viene convalidato un campo e vengono aggiunte diverse regole di convalida.
<field id="A_CUSTOM_IDENTIFIER" showInDefault="1" showInWebsite="0" showInStore="1">
<validate>required-entry validate-clean-url no-whitespace</validate>
</field>
Sono disponibili le seguenti regole di convalida:
alphanumeric
integer
ipv4
ipv6
letters-only
abcABC
.letters-with-basic-punc
Deve passare la seguente espressione:
/^[a-z\-.,()\u0027\u0022\s]+$/i
.mobileUK
no-marginal-whitespace
no-whitespace
phoneUK
phoneUS
required-entry
validate-no-empty
).Messaggio di errore di convalida: "Questo campo è obbligatorio".
time
15
, 15:05
o 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
o www.example.com
.validate-currency-dollar
validate-data
Il primo carattere deve essere una lettera.
(Deve corrispondere all'espressione:
/^[A-Za-z]+[A-Za-z0-9_]+$/
)Messaggio di errore di convalida: "Utilizzare solo lettere (a-z o A-Z), numeri (0-9) o il carattere di sottolineatura (_) in questo campo e il primo carattere deve essere una lettera."
validate-date-au
validate-email
validate-emailSender
validate-fax
validate-no-empty
requried-entry
).Messaggio di errore di convalida: "Valore vuoto".
validate-no-html-tags
validate-password
validate-phoneLax
validate-phoneStrict
validate-select
null
, un valore stringa di none
o una lunghezza stringa di 0.validate-ssn
validate-street
validate-url
validate-xml-identifier
validate-zip-us
vinUS
Valori predefiniti
I valori predefiniti per i campi possono essere impostati nel file etc/config.xml
del modulo specificando il valore predefinito nel nodo section/group/field_ID
.
Esempio: impostazione del valore predefinito per ANOTHER_UNIQUE_FIELD_ID
(ambito predefinito)
<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>
Esempio: impostazione del valore predefinito per ANOTHER_UNIQUE_FIELD_ID
(ambito sito Web)
Utilizzando il tag websites
, specifica il valore predefinito per un sito Web specifico.
<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>