Magento 2.2 introduced a new file, definition.map.xml.
What is the purpose and intent of this file? It seems to be related to building the schemaMap property in Magento\Ui\Config\Converter, but none of the GitHub notes really explain the intent of this files or what it's contents are meant to convey.

Other than general curiosity, my main interest is in patching up a tutorial module that's broken in M2.2.



My current high-level understanding is that the purpose of definition.map.xml is to map XML data from a (Magento 2.2) UI Component's <settings> node to its <argument> nodes.

Edit: After writing this answer, I found that the Magento documentation has additional information on the semantic changes here.


For context, UI components have been using <argument> nodes for a longer time than <settings>. Specifically, in the view/[area]/ui_component/etc/definition.xml file or view/[area]/ui_component/[ui_component_name].xml configuration files, the standard practice was to include an XML node such as the following:

<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 name="label" xsi:type="string" translate="true">Company Information</item>
    <item name="template" xsi:type="string">templates/form/collapsible</item>

That configuration, if given to, say, a <form> UI Component, would wind up passed into the Form PHP class's constructor (Magento/Ui/Component/Form.php) in the $data array. The translation is fairly straightforward.

However, this structure did not provide nuanced control or validation of the defining XML. Developers could put whatever they wanted in their <argument> nodes with impunity (at least, at the XSD validation level), and those values were passed right back to the PHP code without a lot of transformations.

To add a level of abstraction and validation, Magento introduced the <settings> node. Taking another look at a node in 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 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 name="buttons" type="buttons" xsi:type="converter">settings/buttons</item>
            <item name="spinner" type="string" xsi:type="xpath">settings/spinner</item>

...A structure that looks very similar to the old <argument> tree begins to appear. The only difference is, for example, when one desires to add a spinner to a form, rather than using the <argument> style:

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

...one could notice that the same configuration value is mapped by the line <item name="spinner" type="string" xsi:type="xpath">settings/spinner</item> to the following alternative syntax:


On the surface, this seems like a completely fatuous level of abstraction, saving a few characters of XML in one configuration file by adding multiple lines to a new mapping file.

However, not every mapping is a simple matter of copy-and-paste. For example, it seems that the mapping for button configuration:

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

...is of xsi:type="converter" (rather than xpath, like the spinner example above). Determining the consequences of such a declaration is beyond my ability, but the intrepid source code explorer may want to look in Magento\Ui\Config\Converter, in which many of these more complex XML configuration nodes have PHP classes with matching names.

The effect on the XML is more apparent. Whereas the old syntax for button definitions would have been

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

...the new configuration would look like:

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

...and ostensibly have the additional benefits of passing through Magento's Ui/Config PHP conversion code.

This is only a cursory view of what an outsider perceives to be the intent behind these files: I am sure that an actual Magento developer would be able to provide much more insight into both the functional details of the code and the motivation behind this additional level of abstraction.

Edit: It looks like the Magento documentation does, in fact, have a page describing the motivation behind these changes. Look here for more information.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.