InsertListing UI Component should have a clear example of passing data from parent UI Component

[ioweb-gr]

Is there an existing issue for this?

• [X] I have searched the existing issues

Which topic?

https://developer.adobe.com/commerce/frontend-core/ui-components/components/insert-listing/#integration-form

What's wrong with the content?

I think that the documentation is severely lacking in the insertListing component.

The most important use I see for this component would be to show a list of entity objects that are tied to another entity so in the parent form you'd need to render the child entity listing.

However there's no clear example of how to pass the parent form's entity id to the data provider of the innerListing component to filter further.

It probably has to do something with the imports directive but there's no example of how to achieve this.

Moreover there's no clear reference in the system either.

Assuming I need to add an InsertListing component in my products I have to assume that my InsertListing component should use <imports>true</imports>

However there's no example of how to pass the entity_id to it's data provider.

<!-- product_form.xml -->
<form xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Ui:etc/ui_configuration.xsd">
    <!-- ... existing form configuration ... -->

    <fieldset name="receipt_product_edit_listing_fieldset">
        <argument name="data" xsi:type="array">
            <item name="config" xsi:type="array">
                <item name="label" xsi:type="string" translate="true">Receipt Product Edit Listing</item>
                <item name="sortOrder" xsi:type="number">100</item>
                <item name="collapsible" xsi:type="boolean">true</item>
            </item>
        </argument>
        <insertListing name="receipt_product_edit_listing">
            <settings>
                <dataLinks>
                    <exports>false</exports>
                    <imports>true</imports>
                </dataLinks>
                <autoRender>true</autoRender>
                <dataScope>receipt_product_edit_listing</dataScope>
                <realTimeLink>true</realTimeLink>
                <ns>receipt_product_edit_listing</ns>
                <!-- what do I need to add here to pass the parent entity id to the child component? -->
            </settings>
        </insertListing>
    </fieldset>
</form>

Do you think you can improve this with a clear example?

What changes do you propose?

Add a very common use case example for how the import function works to pass the entity_id from the parent form to the innerListing

Add a very common use case example to pass something from the child InsertListing component to the parent ui component for example the selected items.

Anything else that can help to cover this?

Also it's easier to pass form elements than the entity_id itself

[m2-assistant[bot]]

Hi @ioweb-gr. Thank you for your report. To speed up processing of this issue, make sure that you provided sufficient information. Add a comment to assign the issue: @magento I am working on this

---

Join Magento Community Engineering Slack and ask your questions in #github channel.

[JesperHerrloff]

I think you could use something like this to get the selected items. . You need to set the provider you want de listing to communicate with. `

`

If you check the code and read what it does, you will find out what works. https://github.com/magento/magento2/blob/2.4/app/code/Magento/Ui/view/base/web/js/form/components/insert-listing.js#L51

But I agree that the documentation needs some refactoring to bee more clear.

[ioweb-gr]

I think that people who are reading the documentation should be able to understand what to do without having to go through the files line by line to understand what is happening and how things are intertwined. Moreover the XML configuration files are supposedly used so that they're easy to understand. However in reality, not so much. People mostly get confused and use plain PHP to do things rather than reuse the ui components due to complexity and unclear documentation.

That's just my humble opinion here but some areas in the documentation are not addressed to a new developer joining Magento, but to people who have rather good experience with it. While in reality they should be focused to someone assuming he has no prior knowledge to the system's code, except for the other related documentation he has read so far. My point being again that he shouldn't have to go through other people's code just to guess how to use things. He should have clear use case examples, the more the better, right in the documentation

[JesperHerrloff]

You can use and i Think you should define your listing as externalProvider. Then set externalFilterMode true,

Then imports and exports to import relevant id from where you use it. But I agree that the documentation is terrible. It is often faster do read the code in the code base.

<imports>
       <link name="product_id">${ $.provider }:data.product.current_product_id</link>
</imports>

<exports>
        <link name="product_id">${ $.externalProvider }:params.product_id</link>
</exports>

Where product_id is the name I filter my grid on. the imports uses the data source of the productForm. Then in your receipt_product_edit_listing.xml you could add to the dataSource Settings.

<filterUrlParams>
        <param name="product_id">*</param>
</filterUrlParams>