[Contribuição de David Lambauer]{class="badge informative" title="David Lambauer"}
referência system.xml
O arquivo system.xml
permite gerenciar a configuração do sistema Commerce. Use este tópico como uma referência geral para o arquivo system.xml
. O arquivo system.xml
está localizado em etc/adminhtml/system.xml
em uma determinada extensão do Commerce 2.
O trecho de código a seguir mostra o esqueleto nu do arquivo:
<?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>
.Guias // Seções // Grupos // Campos
No arquivo system.xml
, é possível definir quatro tipos diferentes de entidades, que estão relacionadas umas às outras. A seção a seguir descreve a relação entre guias, seções, grupos e campos. A captura de tela a seguir exibe a Configuração do sistema Commerce 2 no back-end do administrador.
Os quadrados vermelhos marcam os diferentes tipos definidos no arquivo system.xml
:
As guias são usadas para dividir semanticamente diferentes áreas de configuração. Cada guia pode conter uma ou mais seções, que também podem ser referenciadas como submenus. Uma seção contém um ou mais grupos.
Cada grupo lista um ou mais campos. Você também pode usar um grupo para adicionar uma descrição geral para os campos a seguir. Como mencionado, cada grupo pode ter um ou mais campos. Os campos são a menor entidade
no contexto de configuração do sistema.
Guias
Uma tag <tab>
faz referência a uma guia existente ou nova na configuração do sistema.
Referência de atributo de guia
Uma tag <tab>
pode ter os seguintes atributos:
id
typeId
translate
label
para tornar o rótulo traduzível.string
sortOrder
float
class
string
Referência do nó de guia
Uma tag <tab>
pode ter o seguinte filho:
label
string
Exemplo: criar uma guia
O trecho de código a seguir demonstra a criação de uma nova guia com dados de exemplo.
<?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>
O trecho acima cria uma nova guia com o identificador A_UNIQUE_ID
. Como o atributo translate
é definido e faz referência ao rótulo, o nó label
é traduzível. Durante o processo de renderização, a classe CSS a-custom-css-class-to-style-this-tab
será aplicada ao elemento HTML criado para esta guia.
O atributo sortOrder
com o valor de 10
define a posição da guia na lista de todas as guias quando renderizada.
Seções
Uma tag <section>
faz referência a uma seção nova ou existente na configuração do sistema.
Referência de atributo de seção
Uma tag <section>
pode ter os seguintes atributos:
id
typeId
translate
label
para tornar o rótulo traduzível.string
type
text
.string
sortOrder
float
showInDefault
1
para mostrar a seção e 0
para ocultá-la.int
showInStore
1
para mostrar a seção e 0
para ocultá-la.int
showInWebsite
1
para mostrar a seção e 0
para ocultá-la.int
canRestore
int
advanced
bool
extends
string
Referência do nó da seção
Uma tag <section>
pode ter os seguintes filhos:
label
string
class
string
tab
typeTabId
header_css
string
resource
typeAclResourceId
group
typeGroup
frontend_model
typeModel
include
system_include.xsd
arquivos adicionais compatíveis. Normalmente usado para estruturar arquivos system.xml
grandes.includeType
Exemplo: criar uma seção e atribuí-la a uma guia
O trecho de código a seguir demonstra o uso básico da criação de uma nova seção.
<?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>
A seção descrita acima define a ID A_UNIQUE_SECTION_ID
, que é visível na exibição de configuração padrão e em um contexto de armazenamento. O nó label
pode ser traduzido. A seção está associada à guia com a ID A_UNIQUE_ID
. A seção só pode ser acessada por usuários que tenham as permissões definidas na ACL VENDOR_MODULE::path_to_the_acl_resource
.
Grupos
A <group>
-Tag é usada para agrupar campos.
Referência de atributo de grupo
Uma tag <group>
pode ter os seguintes atributos:
id
typeId
translate
label
para tornar o rótulo traduzível. Vários campos devem ser separados por um espaço.string
type
text
.string
sortOrder
float
showInDefault
1
para mostrar o grupo e 0
para ocultar o grupo.int
showInStore
1
para mostrar o grupo e 0
para ocultar o grupo.int
showInWebsite
1
para mostrar o grupo e 0
para ocultar o grupo.int
canRestore
int
advanced
bool
extends
string
Referência do nó do grupo
Uma tag <group>
pode ter os seguintes filhos:
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[//]]>
.string
hide_in_single_store_mode
1
oculta o grupo; 0
mostra o grupo.int
field
field
group
unbounded
depends
1
. Este nó espera uma cadeia de caracteres section/group/field
.depends
attribute
attribute
include
system_include.xsd
arquivos adicionais compatíveis. Normalmente usado para estruturar arquivos system.xml
grandes.includeType
more_url
, demo_url
e help_url
são definidos por um modelo de front-end do PayPal que é usado apenas uma vez. Esses nós não são reutilizáveis.Exemplo: criar um grupo para uma determinada seção
O trecho de código a seguir demonstra o uso básico da criação de um novo grupo.
<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>
O grupo descrito acima define a ID A_UNIQUE_GROUP_ID
, que é visível na exibição de configuração padrão e em um contexto de armazenamento. Ambos, o label
e o comment
são marcados como traduzíveis.
Campos
A <field>
-Tag é usada dentro de <group>
-Tags para definir valores de configuração específicos.
Referência do atributo de campo
Uma tag <field>
pode ter os seguintes atributos:
id
typeId
translate
label
para tornar o rótulo traduzível. Vários campos devem ser separados por um espaço.string
type
text
.string
sortOrder
float
showInDefault
1
para mostrar o campo e 0
para ocultar o campo.int
showInStore
1
para mostrar o campo e 0
para ocultar o campo.int
showInWebsite
1
para mostrar o campo e 0
para ocultar o campo.int
canRestore
int
advanced
bool
extends
string
Referência do tipo de campo
Uma tag <field>
pode ter os seguintes valores para o atributo type=""
:
text
textarea
select
source_model
personalizado. Também usado para Yes/No
seleções. Veja um exemplo em Magento\Search\Model\Adminhtml\System\Config\Source\Engine
.multiselect
select
, mas várias opções são válidas.button
Magento\ScheduledImportExport\Block\Adminhtml\System\Config\Clean
.obscure
**​**
. A alteração do tipo usando "Elemento Inspect" no navegador não revela o valor.password
obscure
, exceto que o valor oculto não é criptografado, e a alteração forçada do tipo usando "Elemento Inspect" no navegador revela o valor.file
label
time
allowspecific
source_model
como Magento\Shipping\Model\Config\Source\Allspecificcountries
image
note
frontend_model
para renderizar a anotação.Também é possível criar um tipo de campo personalizado. Isso geralmente é feito quando um botão especial, com uma ação, é necessário. Para fazer isso, são necessários dois elementos principais:
- Criando um bloco na área
adminhtml
- Definindo o
type=""
para o caminho para este bloco
O próprio bloco requer, no mínimo, um método __construct
e um método getElementHtml()
. O Magento_OfflineShipping é um exemplo simples de um tipo personalizado.
Por exemplo, no módulo OfflineShipping, o botão Exportar é definido em Magento\OfflineShipping\Block\Adminhtml\Form\Field\Export
e a definição do campo é semelhante a:
<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>
Referência do nó de campo
Uma tag <field>
pode ter os seguintes filhos:
label
string
comment
<![CDATA[//]]>
.string
tooltip
string
hint
frontend_model
específico.string
frontend_class
string
frontend_model
typeModel
backend_model
typeModel
source_model
typeModel
config_path
typeConfigPath
validate
string
can_be_empty
type
é multiselect
para especificar que um campo pode estar vazio.int
if_module_enabled
typeModule
base_url
upload_dir
para carregamentos de arquivo.typeUrl
upload_dir
typeUploadDir
button_url
button_url
e button_label
forem especificados. Normalmente usado em combinação com um modelo de front-end personalizado.typeUrl
button_label
button_label
e button_url
forem especificados. Normalmente usado em combinação com um modelo de front-end personalizado.string
more_url
typeUrl
demo_url
typeUrl
hide_in_single_store_mode
1
oculta o grupo; 0
mostra o grupo.int
options
complexType
depends
1
. Este nó espera uma cadeia de caracteres section/group/field
.complexType
attribute
complexType
requires
complexType
more_url
, demo_url
, requires
e options
são definidos por um modelo de pagamento principal diferente e são usados apenas uma vez. Esses nós não são reutilizáveis.Exemplo: criar dois campos em um determinado grupo
<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>
O exemplo acima cria dois campos, ambos visíveis/configuráveis no padrão e na exibição de loja. Ambos os campos têm um comentário e uma dica de ferramenta para descrever sua finalidade para o usuário. O nó label
pode ser traduzido.
O campo com o identificador ANOTHER_UNIQUE_FIELD_ID
fica visível quando o módulo fornecido em if_module_enabled
é habilitado globalmente. O campo também valida seu valor em relação às regras required-entry
e no-whitespace
.
O campo com o identificador A_UNIQUE_FIELD_ID
define um modelo de origem diferente que fornece os valores Yes
e No
.
Modelos de origem comuns
Os seguintes modelos de origem são fornecidos pelo Commerce 2 Core. Em geral, há muito mais modelos de origem; a lista a seguir descreve os mais comuns. Saiba que esses modelos de origem precisam do atributo de campo type
para funcionarem corretamente.select
Magento\Config\Model\Config\Source\Yesnocustom
Yes
, No
e Specified
.Magento\Config\Model\Config\Source\Enabledisable
Enable
, Disable
. Salva os valores como 0
e 1
no banco de dados.Magento\AdminNotification\Model\Config\Source\Frequency
1 Hour
,2 Hours
,6 Hours
,12 Hours
e 24 Hours
. Os valores são salvos como números inteiros.Magento\Catalog\Model\Config\Source\TimeFormat
Magento\Cron\Model\Config\Source\Frequency
Daily
, Weekly
e Monthly
. Os valores são salvos no banco de dados como D
, W
e M
.Magento\GoogleAdwords\Model\Config\Source\Language
Magento\Config\Model\Config\Source\Locale
Validação de campo
Um campo pode ter uma ou mais classes de validador atribuídas para garantir que a entrada do usuário atenda aos requisitos da extensão. Regras de validação podem ser aplicadas com a <validate>
-Tag.
O exemplo a seguir valida um campo e adiciona várias regras de validação diferentes.
<field id="A_CUSTOM_IDENTIFIER" showInDefault="1" showInWebsite="0" showInStore="1">
<validate>required-entry validate-clean-url no-whitespace</validate>
</field>
As seguintes regras de validação estão disponíveis:
alphanumeric
integer
ipv4
ipv6
letters-only
abcABC
.letters-with-basic-punc
Deve passar a seguinte expressão:
/^[a-z\-.,()\u0027\u0022\s]+$/i
.mobileUK
no-marginal-whitespace
no-whitespace
phoneUK
phoneUS
required-entry
validate-no-empty
).Mensagem de falha na validação: "Este campo é obrigatório".
time
15
, 15:05
ou 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
ou www.example.com
.validate-currency-dollar
validate-data
O primeiro caractere deve ser uma letra.
(Deve corresponder à expressão:
/^[A-Za-z]+[A-Za-z0-9_]+$/
)Mensagem de falha de validação: "Use somente letras (a-z ou A-Z), números (0-9) ou sublinhado (_) neste campo e o primeiro caractere deve ser uma letra."
validate-date-au
validate-email
validate-emailSender
validate-fax
validate-no-empty
requried-entry
).Mensagem de falha de validação: "Valor vazio".
validate-no-html-tags
validate-password
validate-phoneLax
validate-phoneStrict
validate-select
null
, um valor de cadeia de caracteres none
ou um comprimento de cadeia de caracteres igual a 0.validate-ssn
validate-street
validate-url
validate-xml-identifier
validate-zip-us
vinUS
Valores padrão
Os valores padrão para campos podem ser definidos no arquivo etc/config.xml
do módulo especificando-se o valor padrão no nó section/group/field_ID
.
Exemplo: Definindo o valor padrão para ANOTHER_UNIQUE_FIELD_ID
(Escopo padrão)
<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>
Exemplo: Definindo o valor padrão para ANOTHER_UNIQUE_FIELD_ID
(Escopo do site)
Usando a marca websites
, especifique o valor padrão para um site específico.
<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>