Magento 2.2: Qual é o arquivo definition.map.xml?

Magento 2.2 introduziu um novo arquivo, definition.map.xml .
Qual é o objetivo e a intenção deste arquivo? Parece estar relacionado à criação da propriedade schemaMap Magento\Ui\Config\Converter, mas nenhuma das notas do GitHub realmente explica a intenção desses arquivos ou o que seu conteúdo deve transmitir.

Além da curiosidade geral, meu principal interesse é corrigir um módulo tutorial quebrado no M2.2 .

Sumário

Meu entendimento atual de alto nível é que o objetivo definition.map.xmlé mapear dados XML de um <settings>nó do componente de interface do usuário (Magento 2.2) para seus <argument>nós.

Edit : Depois de escrever esta resposta, descobri que a documentação do Magento tem informações adicionais sobre as mudanças semânticas aqui .

Explicação

Por contexto, os componentes da interface do usuário usam <argument>nós há mais tempo que <settings>. Especificamente, no view/[area]/ui_component/etc/definition.xmlarquivo ou nos view/[area]/ui_component/[ui_component_name].xmlarquivos de configuração, a prática padrão era incluir um nó XML, como o seguinte:

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

Essa configuração, se fornecida a, digamos, um <form>componente de interface do usuário, acabaria sendo passada para o Formconstrutor da classe PHP ( Magento/Ui/Component/Form.php) na $datamatriz. A tradução é bastante direta.

No entanto, essa estrutura não forneceu controle ou validação diferenciada do XML de definição. Os desenvolvedores poderiam colocar o que quisessem em seus <argument>nós com impunidade (pelo menos no nível de validação XSD), e esses valores foram transmitidos de volta ao código PHP sem muitas transformações.

Para adicionar um nível de abstração e validação, o Magento introduziu o <settings>nó. Examinando novamente um nó em 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>

... Uma estrutura que se parece muito com a <argument>árvore antiga começa a aparecer. A única diferença é, por exemplo, quando se deseja adicionar um botão giratório a um formulário, em vez de usar o <argument>estilo:

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

... pode-se notar que o mesmo valor de configuração é mapeado pela linha <item name="spinner" type="string" xsi:type="xpath">settings/spinner</item>para a seguinte sintaxe alternativa:

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

Na superfície, isso parece um nível de abstração completamente absurdo, salvando alguns caracteres de XML em um arquivo de configuração, adicionando várias linhas a um novo arquivo de mapeamento.

No entanto, nem todo mapeamento é uma simples questão de copiar e colar. Por exemplo, parece que o mapeamento para configuração de botão:

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

... é de xsi:type="converter"(em vez de xpath, como no exemplo giratório acima). Determinar as consequências de tal declaração está além da minha capacidade, mas o intrépido explorador de código-fonte pode procurar Magento\Ui\Config\Converter, em que muitos desses nós de configuração XML mais complexos têm classes PHP com nomes correspondentes.

O efeito no XML é mais aparente. Enquanto a antiga sintaxe para definições de botões teria 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>

... a nova configuração seria semelhante a:

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

... e ostensivamente têm os benefícios adicionais de passar pelo Ui/Configcódigo de conversão PHP do Magento .

Esta é apenas uma visão superficial do que um estranho percebe ser a intenção por trás desses arquivos: Tenho certeza de que um desenvolvedor Magento real poderia fornecer muito mais informações sobre os detalhes funcionais do código e a motivação por trás desse nível adicional de abstração.

Edit : Parece que a documentação do Magento, de fato, tem uma página descrevendo a motivação por trás dessas mudanças. Veja aqui mais informações.