[Colaboró David Lambauer]{class="badge informative" title="David Lambauer"} [Solo PaaS]{class="badge informative" title="Se aplica solo a proyectos de Adobe Commerce en la nube (infraestructura PaaS administrada por Adobe) y a proyectos locales."}

referencia de system.xml

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

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 archivo 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 el archivo system.xml:

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

Una etiqueta <tab> hace referencia a una ficha existente o a una nueva en la configuración del sistema.

Referencia de atributo de ficha

Una etiqueta <tab> puede tener los atributos siguientes:

Referencia del nodo de pestañas

Una etiqueta <tab> 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 ficha con el identificador A_UNIQUE_ID. A medida que se define el atributo translate y hace referencia a la etiqueta, el nodo label se puede traducir. Durante el proceso de representación, la clase CSS a-custom-css-class-to-style-this-tab se aplicará en el elemento HTML que se creó para esta pestaña.
El atributo sortOrder con el valor 10 define la posición de la ficha en la lista de todas las fichas cuando se representa.

Secciones

Una etiqueta <section> hace referencia a una sección existente o a una nueva en la configuración del sistema.

Referencia de atributo de sección

Una etiqueta <section> puede tener los atributos siguientes:

Referencia del nodo de sección

Una etiqueta <section> 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, que es visible en la vista de configuración predeterminada y en un contexto de tienda. El nodo label es traducible. La sección está asociada a la pestaña con el ID A_UNIQUE_ID. Solo pueden obtener acceso a la sección los usuarios que tengan los permisos definidos en la ACL VENDOR_MODULE::path_to_the_acl_resource.

Grupos

La etiqueta <group> se usa para agrupar campos.

Referencia de atributo de grupo

Una etiqueta <group> puede tener los atributos siguientes:

Referencia del nodo de grupo

Una etiqueta <group> 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, que es visible en la vista de configuración predeterminada y en un contexto de tienda. Tanto label como comment se marcan como traducibles.

Campos

La etiqueta <field> se usa dentro de etiquetas <group> para definir valores de configuración específicos.

Referencia de atributo de campo

Una etiqueta <field> puede tener los atributos siguientes:

Referencia de tipo de campo

Una etiqueta <field> puede tener los siguientes valores para el atributo type="":

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, un método __construct y un método getElementHtml(). 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 el siguiente 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

Una etiqueta <field> 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 nodo label es traducible.
El campo con el identificador ANOTHER_UNIQUE_FIELD_ID es visible cuando el módulo dado en 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 origen. 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 que el atributo de campo type se establezca en select para que funcione 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 la etiqueta <validate>.
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 archivo etc/config.xml del módulo especificando el valor predeterminado en el nodo section/group/field_ID.

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)

Con la etiqueta 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>