[Colaboró David Lambauer]{class="badge informative" title="David Lambauer"}

referencia de system.xml

El system.xml le permite administrar la configuración del sistema de Commerce. Utilice este tema como referencia general para system.xml archivo. El system.xml el archivo se encuentra en etc/adminhtml/system.xml en una extensión determinada de Commerce 2.

El siguiente fragmento de código muestra el esqueleto vacío del archivo:

<?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>

Pestañas // Secciones // Grupos // Campos

En el system.xml , es posible definir cuatro tipos diferentes de entidades, que están relacionadas entre sí. En la siguiente sección se describe la relación entre pestañas, secciones, grupos y campos. La siguiente captura de pantalla muestra la Configuración del sistema de Commerce 2 en el backend de administración.
Los cuadrados rojos marcan los diferentes tipos definidos en la variable system.xml archivo:

Las pestañas se utilizan para dividir semánticamente las diferentes áreas de configuración. Cada ficha puede contener una o más secciones, a las que también se puede hacer referencia como submenús. Una sección contiene uno o más grupos.
Cada grupo enumera uno o varios campos. También puede utilizar un grupo para agregar una descripción general para los siguientes campos. Como se ha mencionado, cada grupo puede tener uno o más campos. Los campos son la entidad más pequeña en el contexto de configuración del sistema.

Fichas

A <tab>-Etiqueta hace referencia a una pestaña existente o a una nueva en la configuración del sistema.

Referencia de atributo de ficha

A <tab>La etiqueta puede tener los atributos siguientes:

Referencia del nodo de pestañas

A <tab>La etiqueta puede tener los siguientes elementos secundarios:

Ejemplo: Creación de una pestaña

El siguiente fragmento de código muestra la creación de una nueva pestaña con datos de ejemplo.

<?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>

El fragmento anterior crea una nueva pestaña con el identificador A_UNIQUE_ID. Como el translate-attribute se define y hace referencia a la etiqueta, la variable labelEl nodo es traducible. Durante el proceso de renderización, la clase CSS a-custom-css-class-to-style-this-tab se aplicarán en el elemento HTML creado para esta pestaña.
El sortOrder-attribute con el valor de 10 define la posición de la pestaña en la lista de todas las pestañas cuando se representa.

Secciones

A <section>-Etiqueta hace referencia a una sección existente o a una nueva en la configuración del sistema.

Referencia de atributo de sección

A <section>La etiqueta puede tener los atributos siguientes:

Referencia del nodo de sección

A <section>La etiqueta puede tener los siguientes elementos secundarios:

Ejemplo: Crear una sección y asignarla a una pestaña

El siguiente fragmento de código muestra el uso básico de la creación de una nueva sección.

<?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 sección descrita anteriormente define el ID A_UNIQUE_SECTION_ID, es visible en la vista de configuración predeterminada y en un contexto de tienda. El labelEl nodo es traducible. La sección está asociada a la pestaña con el ID A_UNIQUE_ID. Solo pueden acceder a la sección los usuarios que tengan los permisos definidos en la ACL VENDOR_MODULE::path_to_the_acl_resource.

Grupos

El <group>-Tag se utiliza para agrupar campos.

Referencia de atributo de grupo

A <group>La etiqueta puede tener los atributos siguientes:

Referencia del nodo de grupo

A <group>La etiqueta puede tener los siguientes elementos secundarios:

Ejemplo: Creación de un grupo para una sección determinada

El siguiente fragmento de código muestra el uso básico de la creación de un nuevo 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>

El grupo descrito anteriormente define el ID A_UNIQUE_GROUP_ID, es visible en la vista de configuración predeterminada y en un contexto de tienda. Ambos, el label y el comment se marcan como traducibles.

Campos

El <field>La etiqueta se utiliza dentro de <group>-Etiquetas para definir valores de configuración específicos.

Referencia de atributo de campo

A <field>La etiqueta puede tener los atributos siguientes:

Referencia de tipo de campo

A <field>-Tag puede tener los siguientes valores para type="" atributo:

También es posible crear un tipo de campo personalizado. Esto suele hacerse cuando se requiere un botón especial, con una acción. Para ello, se requieren dos elementos principales:

El propio bloque requiere, como mínimo, una __construct método y a getElementHtml() método. El Magento_OfflineShipping es un ejemplo sencillo de un tipo personalizado.

Por ejemplo, en el módulo OfflineShipping, el botón Exportar se define en Magento\OfflineShipping\Block\Adminhtml\Form\Field\Export y la definición del campo tiene este aspecto:

<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>

Referencia del nodo de campo

A <field>La etiqueta puede tener los siguientes elementos secundarios:

Ejemplo: Crear dos campos en un grupo determinado

<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>

El ejemplo anterior crea dos campos, visibles/configurables en la vista predeterminada y en la vista de tienda. Ambos campos tienen un comentario y una información del objeto para describir su propósito al usuario. El labelEl nodo es traducible.
El campo con el identificador ANOTHER_UNIQUE_FIELD_ID es visible cuando el módulo dado en la variable if_module_enabled está habilitado globalmente. El campo también valida su valor con las reglas required-entry y no-whitespace.
El campo con el identificador A_UNIQUE_FIELD_ID define un modelo de origen diferente que proporciona esos valores Yes y No.

Modelos de origen comunes

Commerce 2 Core proporciona los siguientes modelos de fuente. En general, hay muchos más modelos de origen; la siguiente lista describe los más comunes. Tenga en cuenta que estos modelos de origen necesitan el atributo de campo type que se establecerá en select para poder funcionar correctamente.

Validación de campos

Un campo puede tener una o más clases de validador asignadas para asegurarse de que la entrada del usuario cumple los requisitos de la extensión. Las reglas de validación se pueden aplicar con <validate>-Etiqueta.
En el siguiente ejemplo se valida un campo y se agregan distintas reglas de validación.

<field id="A_CUSTOM_IDENTIFIER" showInDefault="1" showInWebsite="0" showInStore="1">
    <validate>required-entry validate-clean-url no-whitespace</validate>
</field>

Están disponibles las siguientes reglas de validación:

Valores predeterminados

Los valores predeterminados para los campos se pueden establecer en el etc/config.xml al especificar el valor predeterminado en la variable section/group/field_ID nodo.

Ejemplo: Configuración del valor predeterminado para ANOTHER_UNIQUE_FIELD_ID (Ámbito predeterminado)

<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>

Ejemplo: Configuración del valor predeterminado para ANOTHER_UNIQUE_FIELD_ID (Ámbito del sitio web)

Uso del websites , especifique el valor predeterminado para un sitio web 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>