Contextualizando
O que é uma configuração?
Configurações no Magento 2 são campos que pertencem a seções e grupos de configurações, onde podem conter valores pré-configurados, textos e/ou números para que os fluxos, lógicas e definições das lojas sigam esses valores, que são salvos na tabela core_config_data.
Vários módulos podem declarar arquivos de configuração que afetam o mesmo tipo de configuração, e esses vários arquivos de configuração são unificados na mesma página. Os nós nos arquivos de configuração são mesclados com base em seus XPaths, que possuem um atributo especial definido na idAttributes declarada como seu identificador. Este identificador deve ser exclusivo para todos os nós aninhados no mesmo nó pai.
Se os identificadores de nó forem iguais (ou se não houver nenhum identificador definido), todo o conteúdo subjacente no nó (atributos, nós filhos e conteúdo) será substituído. Se os identificadores de nó não forem iguais, o nó é um novo filho do nó pai.
Por que fazer uma configuração personalizada?
É recomendada a criação de configurações personalizadas para personalizar aspectos específicos do comportamento do seu módulo, podendo ser habilitar/desabilitar funcionalidades, tipos de clientes que podem acessar a determinada funcionalidade, textos que serão apresentados, valores para determinado cálculo, países atendidos por determinado serviço, entre outros inúmeros motivos.
Código para criação de uma configuração personalizada
system.xml
Para o gerenciamento de configurações no Magento é necessário criar um arquivo chamado system.xml que deve seguir a estrutura de pasta \{Vendor}\{Module}\etc\adminhtml\system.xml. Este arquivo é dividido em 4 partes: tab, section, group e field.
Com o arquivo system.xml é possível criar novas configurações como estender configurações existentes, apenas recriando a estrutura desejada.
As configurações do Magento 2 são encontradas em Painel administrativo → Store → Settings → Configuration. O nó <tab> é uma guia utilizada para dividir diferentes áreas de configuração semanticamente. Cada <tab> pode conter uma ou mais <section>, que podem ser referenciadas como submenu.
<?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="{tab_id}" translate="label" class="{css_class_name}" sortOrder="{sort_number}">
<label>{Text to translate}</label>
</tab>
<section id="{section_id}" showInDefault="{1/0}" showInWebsite="{1/0}" showInStore="{1/0}" sortOrder="{sort_number}" translate="label">
<label>{Text to translate}</label>
<tab>{tab_id}</tab>
<resource>{Vendor}_{Module}::{acl_path}</resource>
<frontend_model>{Vendor}\{Module}\{Directory}\{ClassName}</frontend_model>
<include path="{Vendor}_{Module}::{path_name}/{file_name}.xml"/>
<group id="{group_id}" translate="label comment" sortOrder="{sort_number}" showInDefault="{1/0}" showInWebsite="{1/0}" showInStore="{1/0}" canRestore="{1/0}">
<label>{Text to translate}</label>
<fieldset_css>{css_class_name}</fieldset_css>
<frontend_model>{Vendor}\{Module}\{Directory}\{ClassName}</frontend_model>
<clone_model>{Vendor}\{Module}\{Directory}\{ClassName}</clone_model>
<clone_fields>{1/0}</clone_fields>
<comment>{Comment to translate}</comment>
<hide_in_single_store_mode>{1/0}</hide_in_single_store_mode>
<group id="{child_group_id}" sortOrder="{sort_number}">
</group>
<depends>
<field id="{section_id}/{group_id}/{field_id}">{1/0}</field>
</depends>
<include path="{Vendor}_{Module}::{path_name}/{file_name}.xml"/>
<field id="{field_tag_chilren_id}" translate="label" type="text">
<label>{Field label}</label>
<comment>{Field comment}</comment>
<tooltip>{Field tooltip}</tooltip>
<hint>{Field hint}</hint>
<frontend_class>{Vendor}\{Module}\{Directory}\{ClassName}</frontend_class>
<frontend_model>{Vendor}\{Module}\{Directory}\{ClassName}</frontend_model>
<backend_model>{Vendor}\{Module}\{Directory}\{ClassName}</backend_model>
<source_model>{Vendor}\{Module}\{Directory}\{ClassName}</source_model>
<config_path>{new_section_id}/{new_group_id}/{new_field_id}</config_path>
<validate>{validation-rules}</validate>
<can_be_empty>{1/0}</can_be_empty>
<if_module_enabled>{1/0}</if_module_enabled>
<base_url type="media" scope_info="1">{frontend_name}/{controller_directory}/{controller_name}</base_url>
<upload_dir config="{section_id}/{group_id}/{field_id}" scope_info="1">{frontend_name}/{controller_directory}/{controller_name}</upload_dir>
<button_label>{Button label}</button_label>
</field>
<field id="{field_text_id}" translate="label" type="text">
<label>{Text to translate}</label>
</field>
<field id="{field_textarea_id}" translate="label" type="textarea">
<label>{Text to translate}</label>
</field>
<field id="{field_select_id}" translate="label" type="select">
<label>{Text to translate}</label>
<source_model>Magento\Config\Model\Config\Source\Yesno</source_model>
</field>
<field id="{field_multiselect_id}" translate="label" type="multiselect">
<label>{Text to translate}</label>
<source_model>{Vendor}\{Module}\Model\{Directory}\{ClassName}</source_model>
</field>
<field id="{field_obscure_id}" translate="label" type="obscure">
<label>{Text to translate}</label>
<backend_model>Magento\Config\Model\Config\Backend\Encrypted</backend_model>
</field>
<field id="{field_password_id}" translate="label" type="password">
<label>{Text to translate}</label>
</field>
<field id="{field_label_id}" translate="label" type="label">
<label>{Text to translate}</label>
<frontend_model>{Vendor}\{Module}\{Directory}\{ClassName}</frontend_model>
</field>
<field id="{field_time_id}" translate="label" type="time">
<label>{Text to translate}</label>
</field>
<field id="{field_allowspecific_id}" translate="label" type="allowspecific">
<label>{Text to translate}</label>
<source_model>{Vendor}\{Module}\Model\{Directory}\{ClassName}</source_model>
</field>
<field id="{field_image_id}" translate="label" type="image">
<backend_model>Magento\Config\Model\Config\Backend\Image</backend_model>
<upload_dir config="{section_id}/{group_id}/{field_id}" scope_info="1">{frontend_name}/{controller_directory}/{controller_name}</upload_dir>
<base_url type="media" scope_info="1">{frontend_name}/{controller_directory}/{controller_name}</base_url>
</field>
</group>
</section>
</system>
</config>
config.xml
Cada campo no arquivo system.xml não terá nenhum valor salvo na tabela core_config_data a princípio, o retorno do valor do campo será null. Então, para definir um valor inicial para o campo, é necessário criar um arquivo chamado config.xml que deve seguir a estrutura de pasta \{Vendor}\{Module}\etc\config.xml.
<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Store:etc/config.xsd">
<default>
<{section_id}>
<{group_id}>
<{field_id}>{value}</{field_id}>
</{group_id}>
</{section_id}>
</default>
</config>
Acessando as os valores
Para acessar o valor de uma configuração salva no banco, basta injetar a classe \Magento\Framework\App\Config\ScopeConfigInterface e acessar o método getValue(string $path, \Magento\Store\Model\ScopeInterface::SCOPE_STORE, $scopeCode = null) ou o método isSetFlag(string $path, \Magento\Store\Model\ScopeInterface::SCOPE_STORE, $scopeCode = null), passando o caminho do campo desejado e o ID do escopo da loja desejada.
<?php
namespace {Vendor}\{Module}\Model\Config\Source;
use Magento\Framework\App\Config\ScopeConfigInterface;
use Magento\Store\Model\ScopeInterface;
class {ClassName}
{
private const CUSTOM_MODULE_PATH_CONFIG = '{section_id}/{group_id}/{field_id}';
public function __construct(
private ScopeConfigInterface $scopeConfig
) {
}
public function getConfigValue(?int $storeId = null): string|int|bool
{
return $this->scopeConfig->getValue(
self::CUSTOM_MODULE_PATH_CONFIG,
ScopeInterface::SCOPE_STORE,
$storeId
);
}
public function isConfigEnable(?int $storeId = null): bool
{
return $this->scopeConfig->isSetFlag(
self::CUSTOM_MODULE_PATH_CONFIG,
ScopeInterface::SCOPE_STORE,
$storeId
);
}
}
Finalizando
Valores entre chaves (
{test}) devem ser alterados na implementação do código.
Diretórios e Arquivos
Segue a a lista de diretórios e arquivos a serem criados.
- app/
- code/
- {Vendor}/
- {Module}/
- etc/
- adminhtml/
- system.xml
- config.xml
- module.xml
- Model/
- Config/
- Source/
- {ClassName}.php
- registration.php
- composer.json
Atributos e nós
Para formar as configurações com exatidão segue as tabelas dos atributos e nós do arquivo system.xml:
Atributos de Tab
| Atributos | Descrição | Tipo | Obrigatório |
|---|---|---|---|
| id | Define o identificador que é utilizado na guia. | typeId | sim |
| translate | Define o campo que deve ser traduzido. o nó filho <label> que será traduzido. O valor deve ser o nome da tag que será traduzido, então deve ser label. |
string | opcional |
| type | Define o tipo de entrada do elemento HTML renderizado. O valor padrão é text. | string | opcional |
| sortOrder | Define a ordem de classificação da guia. A ordem é determinada por números crescente, então números menores aparecerão primeiro. | float | opcional |
| class | Adicionar uma classe CSS definida para renderizar junto com o elemento HTM da <tab>
|
string | opcional |
Nós filhos de Tab
| Nó | Descrição | Tipo |
|---|---|---|
| label | Define a legenda do nó que será exibido. | string |
Atributos de Section
| Atributos | Descrição | Tipo | Obrigatório |
|---|---|---|---|
| id | Define o identificador que é utilizado na seção. | typeId | sim |
| translate | Define o campo que deve ser traduzido. o nó filho <label> que será traduzido. O valor deve ser o nome da tag que será traduzido, então deve ser label. |
string | opcional |
| type | Define o tipo de entrada do elemento HTML renderizado. O valor padrão é text. |
string | opcional |
| sortOrder | Define a ordem de classificação da seção. A ordem é determinada por números crescente, então números menores aparecerão primeiro. | float | opcional |
| showInDefault | Define se a seção será exibida nas configurações de escopo. O valor 1 exibirá a configuração e o valor 0 não exibirá. |
integer | opcional |
| showInStore | Define se a seção será exibida nos níveis da loja. O valor 1 exibirá a configuração e o valor 0 não exibirá. |
integer | opcional |
| showInWebsite | Define se a seção será exibida nos níveis dos sites da loja. O valor 1 exibirá a configuração e o valor 0 não exibirá. |
integer | opcional |
| canRestore | Define se a seção pode ser restaurada ao valor padrão. | integer | opcional |
| advanced | Atributo depreciado. | boolean | opcional |
| extends | Ao fornecer um identificador de outra seção, o conteúdo deste nó estenderá a seção referenciada. | string | opcional |
Nós filhos de Section
| Nó | Descrição | Tipo |
|---|---|---|
| label | Define a legenda do nó que será exibido. | string |
| class | Adicionar uma classe CSS definida para renderizar junto com o elemento HTM da <section>. |
string |
| tab | Referenciar seção a uma <tab>. O valor deve ser o atributo id do nó <tab>. |
typeTabId |
| resource | Referenciar seção a um recurso ACL para fornecer permissões das configurações. | typeAclResourceId |
| group | Define um ou mais grupos ou subgrupos. | typeGroup |
| frontend_model | Especifica um Model para alterar a renderização da saída. | typeModel |
| include | Utilizado para incluir arquivos adicionais compatíveis com system_include.xsd. Normalmente, utilizado para estruturar grandes arquivos system.xml
|
includeType |
Atributos de Group
| Atributos | Descrição | Tipo | Obrigatório |
|---|---|---|---|
| id | Define o identificador que é utilizado na seção. | typeId | sim |
| translate | Define o campo que deve ser traduzido. o nó filho <label> que será traduzido. O valor deve ser o nome da tag que será traduzido, então deve ser label. |
string | opcional |
| type | Define o tipo de entrada do elemento HTML renderizado. O valor padrão é text. |
string | opcional |
| sortOrder | Define a ordem de classificação da seção. A ordem é determinada por números crescente, então números menores aparecerão primeiro. | float | opcional |
| showInDefault | Define se a seção será exibida nas configurações de escopo. O valor 1 exibirá a configuração e o valor 0 não exibirá. |
integer | opcional |
| showInStore | Define se a seção será exibida nos níveis da loja. O valor 1 exibirá a configuração e o valor 0 não exibirá. |
integer | opcional |
| showInWebsite | Define se a seção será exibida nos níveis dos sites da loja. O valor 1 exibirá a configuração e o valor 0 não exibirá. |
integer | opcional |
| canRestore | Define se a seção pode ser restaurada ao valor padrão. | integer | opcional |
| extends | Ao fornecer um identificador de outra seção, o conteúdo deste nó estenderá a seção referenciada. | string | opcional |
Nós filhos de Group
| Nó | Descrição | Tipo |
|---|---|---|
| label | Define a legenda do nó que será exibido. | string |
| fieldset_css | Adiciona um ou mais classes CSS a um grupo de campos. | string |
| frontend_model | Especifica um Model para alterar a renderização da saída. | typeModel |
| clone_model | Especifica um determinado Model para clonar os campos. | typeModel |
| clone_fields | Habilita ou Desabilita campos clonados. | integer |
| comment | Adiciona um comentário abaixo do grupo. Pode ser utilizado conteúdo HTML através do nó <![CDATA[//]]>. |
string |
| hide_in_single_store_mode | Se o grupo deve estar visível no modo de uma única visão da loja. O valor 1 exibirá a configuração e o valor 0 não exibirá. |
integer |
| field | Define um ou mais campos que devem estar disponíveis dentro do grupo. | field |
| group | Define um ou mais grupos ou subgrupos. | group |
| depends | Pode ser utilizado para declarar dependências de outros campos. É utilizado para exibir campos/grupos específicos quando um determinado campo tem o valor 1. Espera um nó <field id="{section_id}/{group_id}/{field_id}>{1/0}</field>. |
field |
| attribute | Atributo personalizado que pode ser utilizado na classe Model para alteração do frontend. Normalmente é utilizada para deixar a classe mais dinâmica. | attribute |
| include | Utilizado para incluir arquivos adicionais compatíveis com system_include.xsd. Normalmente, utilizado para estruturar grandes arquivos system.xml. |
includeType |
Atributos de field
| Atributos | Descrição | Tipo | Obrigatório |
|---|---|---|---|
| advanced | Atributo depreciado. | boolean | opcional |
| id | Define o identificador que é utilizado no grupo. | typeId | sim |
| translate | Define o campo que deve ser traduzido. o nó filho <label> que será traduzido. O valor deve ser o nome da tag que será traduzido, então deve ser label. |
string | opcional |
| type | Define o tipo de entrada do elemento HTML renderizado. O valor padrão é text. |
string | opcional |
| sortOrder | Define a ordem de classificação dos campos. A ordem é determinada por números crescente, então números menores aparecerão primeiro. | float | opcional |
| showInDefault | Define se o campo será exibido nas configurações de escopo. O valor 1 exibirá a configuração e o valor 0 não exibirá. |
integer | opcional |
| showInStore | Define se o campo será exibido nos níveis da loja. O valor 1 exibirá a configuração e o valor 0 não exibirá. |
integer | opcional |
| showInWebsite | Define se o campo será exibido nos níveis dos sites da loja. O valor 1 exibirá a configuração e o valor 0 não exibirá. |
integer | opcional |
| canRestore | Define se o grupo pode ser restaurado ao valor padrão. | integer | opcional |
| extends | Ao fornecer um identificador de outro campo, o conteúdo deste nó estenderá ao campo referenciado. | string | opcional |
Tipos de Field
| Nó | Descrição |
|---|---|
| text | Valor padrão, única linha de texto para o campo. |
| textarea | Bloco de texto. |
| select | Dropdown, podendo ter um source_model. Também utilizado para seleções Yes/No, utilizando a classe \Magento\Search\Model\Adminhtml\System\Config\Source\Engine. |
| multiselect | Similar ao tipo select, mas podendo ter múltiplas seleções. |
| button | Um botão que dispara um evento imediato. Requer um Model personalizado para definir a ação do botão. |
| obscure | Um campo de texto com o valor encriptado e exibe *****. Caso o campo seja alterado por inspeção de elementos no navegador não exibirá o valor real. |
| password | Similar ao tipo obscure exceto o valor neste campo não é encriptado. Caso o campo seja alterado por inspeção de elementos no navegador exibirá o valor real. |
| file | Permite o upload de um arquivo no processo. |
| label | Define uma legenda ao invés de um campo editável. Usando este tipo quando um campo for editável apenas em escopos específicos. |
| time | Controle para definir o tempo usando três menus (hora, minuto e segundo). |
| allowspecific | Uma lista para múltiplas seleções de países. Requer um source_model. |
| image | Permite o upload de imagens. |
| note | Permite que uma note informativa seja adicionada a página. Este tipo requer um frontend_model para renderizar. |
Nós filhos de Field
| Nó | Descrição | Tipo |
|---|---|---|
| label | Define a legenda do nó que será exibido. | string |
| comment | Adiciona um comentário abaixo do campo. Pode ser utilizado conteúdo HTML através do nó <![CDATA[//]]>. |
string |
| tooltip | Outro elemento possível do frontend que também podem ser utilizado para descrever o significado deste campo. Será exibido como um pequeno ícone ao lado do campo. | string |
| hint | Exibe informações adicionais. Disponíveis somente com o atributo frontend_model. |
string |
| frontend_class | Adicionar uma classe CSS definida para renderizar junto com o elemento HTM da <field>. |
string |
| frontend_model | Especifica um Model para alterar a renderização e modificar a saída no frontend. | typeModel |
| backend_model | Especifica um Model para modificar os valores configurados no backend. | typeModel |
| source_model | Especifica um Model que fornece uma específica configuração de valores na fonte. | typeModel |
| config_path | Pode ser utilizado para substituir o caminho de configuração genérica de um campo. | typeConfigPath |
| validate | Define diferentes regras de validações (separadas por vírgulas). | string |
| can_be_empty | Utilizado quando o type é do tipo multiselect para especificar que o campo pode ser vazio. |
integer |
| if_module_enabled | Utilizado para exibir um campo somente quando o módulo estiver habilitado. | typeModel |
| base_url | Utilizado na combinação com o nó upload_dir para o upload de arquivos. |
typeUrl |
| upload_dir | Especifica o diretório para upload. Esse nó contem atributos e nós adicionais. | typeUploadDir |
| button_url | Exibe um botão se o nó button_label for especificado. Normalmente são utilizados na combinação com um Model para o frontend. |
typeUrl |
| button_label | Exibe um botão se o nó button_url for especificado. Normalmente são utilizados na combinação com um Model para o frontend. |
string |
| hide_in_single_store_mode | Se o campo deve estar visível no modo de uma única visão da loja. O valor 1 exibirá a configuração e o valor 0 não exibirá. |
integer |
| source_service | Serviço utilizado para popular opções do tipo select. |
complexType |
| depends | Pode ser utilizado para declarar dependências de outros campos. É utilizado para exibir campos/grupos específicos quando um determinado campo tem o valor 1. Espera um nó <field id="{section_id}/{group_id}/{field_id}>{1/0}</field>. |
complexType |
| attribute | Atributo personalizado que pode ser utilizado na classe Model para alteração do frontend. Normalmente é utilizada para deixar a classe mais dinâmica. | complexType |
Validação dos campos
| Nó | Descrição |
|---|---|
| alphanumeric | Permite letras, números, espaços ou sublinhados. |
| integer | Permite números inteiros positivos e negativos. |
| ipv4 | Permite um endereço de IP v4 válido. |
| ipv6 | Permite um endereço de IP v6 válido. |
| letters-only | Permite apenas letras (maiúsculas e minúsculas). |
| letters-with-basic-punc | Permite letras ou pontuações. Deve passar na expressão regular /^[a-z\-.,()\u0027\u0022\s]+$/i. |
| mobileUK | Permite tipos de telefone celulares no formato britânico (UK). |
| no-marginal-whitespace | Não permite espaços em branco no início ou fim do valor. |
| no-whitespace | Não permite espaços em branco. |
| phoneUK | Permite tipos de telefone no formato britânico (UK). |
| phoneUS | Permite tipos de telefone no formato estado-unidense (US). |
| required-entry | Não permite um valor vazio (equivalente ao validate_no_empty). |
| time | Permite um tempo válido no formato de 24 horas, entre 00:00:00 e 23:59:59. |
| time12h | Permite um tempo válido no formato de 12 horas, entre 00:00:00 am e 12:59:59 pm. |
| validate-admin-password | Permite 7 caracteres ou mais, usando numéricos e alfabéticos. |
| validate-alphanum-with-spaces | Permite o uso de letras, números ou espaços. |
| validate-clean-url | Permite um endereço de URL válido. |
| validate-currency-dollar | Permite o valor válido de uma quantia em dólar. |
| validate-data | Permite o uso de letras, número e underlines. A primeira letra deve conter uma letra como caractere (deve passar na expressão regular /^[A-Za-z]+[A-Za-z0-9_]+$/). |
| validate-date-au | Permite o formato de data dd/mm/yyyy. |
| validate-email | Permite um endereço de e-mail válido. |
| validate-emailSender | Permite um endereço de e-mail válido. |
| validate-fax | Permite um número de fax válido. |
| validate-no-empty | Não permite um valor vazio (equivalente ao required-entry). |
| validate-no-html-tags | Não permite o uso de HTML no valor. |
| validate-password | Permite 6 caracteres ou mais, usando numéricos e alfabéticos. Espaços no início e ao fim serão ignorados. |
| validate-phoneLax | Permite um número de telefone válido no formato (000) 000-0000 ou 000-000-0000. |
| validate-phoneStrict | Permite um número de telefone válido no formato (000) 000-0000 ou 000-000-0000. |
| validate-select | Força que a opção da seleção tenha um valor escolhido, não podendo ser null, 0 ou ''. |
| validate-ssn | Permite um número de seguro social válido estado-unidense (US). |
| validate-street | Permite o uso de letras, números, espaços e o caractere #. |
| validate-url | Permite um endereço de URL válido. Requer o protocolo (http://, https:// ou ftp://). |
| validate-xml-identifier | Permite um identificador CML válido. |
| validate-zip-us | Permite um código postal válido no formato estado-unidense (US). |
| binUS | Permite o valor do número de identificação do veículo no formato estado-unidense (US). |
Top comments (0)