Magento 2.2: ¿Qué es el archivo definition.map.xml?

Magento 2.2 introdujo un nuevo archivo, definition.map.xml .
¿Cuál es el propósito y la intención de este archivo? Parece estar relacionado con la construcción de la propiedad schemaMap Magento\Ui\Config\Converter, pero ninguna de las notas de GitHub explica realmente la intención de estos archivos o lo que su contenido debe transmitir.

Además de la curiosidad general, mi interés principal es reparar un módulo tutorial que está roto en M2.2 .

Resumen

Mi comprensión actual de alto nivel es que el propósito de definition.map.xmles mapear datos XML de un <settings>nodo de componente de interfaz de usuario (Magento 2.2) a sus <argument>nodos.

Editar : Después de escribir esta respuesta, descubrí que la documentación de Magento tiene información adicional sobre los cambios semánticos aquí .

Explicación

Para el contexto, los componentes de la interfaz de usuario han estado utilizando <argument>nodos durante más tiempo que <settings>. Específicamente, en el view/[area]/ui_component/etc/definition.xmlarchivo o en los archivos de view/[area]/ui_component/[ui_component_name].xmlconfiguración, la práctica estándar era incluir un nodo XML como el siguiente:

<argument name="data" xsi:type="array">
    <item name="js_config" xsi:type="array">
        <item name="provider" xsi:type="string">oracle_order_form.oracle_order_form_data_source</item>
    </item>
    <item name="label" xsi:type="string" translate="true">Company Information</item>
    <item name="template" xsi:type="string">templates/form/collapsible</item>
</argument>

Esa configuración, si se le da a, digamos, un <form>componente de la interfaz de usuario, terminaría pasando al Formconstructor de la clase PHP ( Magento/Ui/Component/Form.php) en la $datamatriz. La traducción es bastante sencilla.

Sin embargo, esta estructura no proporcionó control matizado o validación del XML definitorio. Los desarrolladores podían poner lo que quisieran en sus <argument>nodos con impunidad (al menos, en el nivel de validación XSD), y esos valores se transfirieron directamente al código PHP sin muchas transformaciones.

Para agregar un nivel de abstracción y validación, Magento introdujo el <settings>nodo. Echando otro vistazo a un nodo en definition.map.xml:

<component name="form" include="uiElementSettings">
    <schema name="current">
        <argument name="data" xsi:type="array">
            <item name="layout" xsi:type="array">
                <item name="type" type="string" xsi:type="xpath">settings/layout/type</item>
                <item name="navContainerName" type="string" xsi:type="xpath">settings/layout/navContainerName</item>
            </item>
            <item name="config" xsi:type="array">
                <item name="selectorPrefix" type="string" xsi:type="xpath">settings/selectorPrefix</item>
                <item name="messagesClass" type="string" xsi:type="xpath">settings/messagesClass</item>
                <item name="errorClass" type="string" xsi:type="xpath">settings/errorClass</item>
                <item name="ajaxSaveType" type="string" xsi:type="xpath">settings/ajaxSaveType</item>
                <item name="namespace" type="string" xsi:type="xpath">settings/namespace</item>
                <item name="ajaxSave" type="boolean" xsi:type="xpath">settings/ajaxSave</item>
                <item name="reloadItem" type="string" xsi:type="xpath">settings/reloadItem</item>
            </item>
            <item name="buttons" type="buttons" xsi:type="converter">settings/buttons</item>
            <item name="spinner" type="string" xsi:type="xpath">settings/spinner</item>
        </argument>
    </schema>
</component>

... <argument>Comienza a aparecer una estructura que se parece mucho al viejo árbol. La única diferencia es, por ejemplo, cuando uno desea agregar una ruleta a un formulario, en lugar de usar el <argument>estilo:

<argument name="data" xsi:type="array">
    <item name="spinner" xsi:type="string">[My_Spinner_Name]</item>
</argument>

... se podría notar que la línea asigna el mismo valor de configuración <item name="spinner" type="string" xsi:type="xpath">settings/spinner</item>a la siguiente sintaxis alternativa:

<settings>
    <spinner>[My_Spinner_Name]</spinner>
</settings>

En la superficie, esto parece un nivel de abstracción completamente fatuo, que guarda algunos caracteres de XML en un archivo de configuración al agregar varias líneas a un nuevo archivo de mapeo.

Sin embargo, no todas las asignaciones son simples tareas de copiar y pegar. Por ejemplo, parece que la asignación para la configuración del botón:

<item name="buttons" type="buttons" xsi:type="converter">settings/buttons</item>

... es de xsi:type="converter"(en lugar de xpath, como el ejemplo de spinner anterior). Determinar las consecuencias de tal declaración está más allá de mi capacidad, pero el intrépido explorador de código fuente puede querer mirar Magento\Ui\Config\Converter, en el que muchos de estos nodos de configuración XML más complejos tienen clases PHP con nombres coincidentes.

El efecto sobre el XML es más evidente. Mientras que la sintaxis anterior para las definiciones de botones habría sido

<argument name="data" xsi:type="array">
    <item name="buttons" xsi:type="array">
        <item name="back" xsi:type="string">Company\Basic\Block\Adminhtml\Slides\BackButton</item>
        <item name="save" xsi:type="string">Company\Basic\Block\Adminhtml\Slides\SaveButton</item>
    </item>
</argument>

... la nueva configuración se vería así:

<settings>
    <buttons>
        <button name="back" class="Company\Basic\Block\Adminhtml\Slides\BackButton"/>
        <button name="save" class="Company\Basic\Block\Adminhtml\Slides\SaveButton"/>
    </buttons>
</settings>

... y aparentemente tienen los beneficios adicionales de pasar por el Ui/Configcódigo de conversión PHP de Magento .

Esta es solo una vista superficial de lo que un extraño percibe como la intención detrás de estos archivos: estoy seguro de que un desarrollador real de Magento podría proporcionar mucha más información sobre los detalles funcionales del código y la motivación detrás de este nivel adicional de abstracción

Editar : Parece que la documentación de Magento tiene, de hecho, una página que describe la motivación detrás de estos cambios. Mira aquí para más información.