|
| 1 | +# Use the block chooser UI component |
| 2 | + |
| 3 | +## Navigation |
| 4 | + |
| 5 | +1. [Introduction] |
| 6 | +2. [Installation guide] |
| 7 | +3. [Contribution guide] |
| 8 | +4. [Developer documentation] |
| 9 | + 1. [Architecture overview] |
| 10 | + 1. [BlueFoot to PageBuilder data migration] |
| 11 | + 1. [Third-party content type migration] |
| 12 | + 1. [Iconography] |
| 13 | + 2. [Add image uploader to content type] |
| 14 | + 1. [Module integration] |
| 15 | + 1. [Additional data configuration] |
| 16 | + 1. [Content type configuration] |
| 17 | + 1. [How to add a new content type] |
| 18 | + 1. [Bindings] |
| 19 | + 1. [Events] |
| 20 | + 1. [Master format] |
| 21 | + 1. [Visual select] |
| 22 | + 1. [Reuse product conditions in content types] |
| 23 | + 1. [Store component master format as widget directive] |
| 24 | + 1. [Render a content type preview] |
| 25 | + 1. **Use the block chooser UI component** |
| 26 | + 1. [Custom Toolbar] |
| 27 | +5. [Roadmap and known issues] |
| 28 | + |
| 29 | +[Introduction]: README.md |
| 30 | +[Contribution guide]: CONTRIBUTING.md |
| 31 | +[Installation guide]: install.md |
| 32 | +[Developer documentation]: developer-documentation.md |
| 33 | +[Architecture overview]: architecture-overview.md |
| 34 | +[BlueFoot to PageBuilder data migration]: bluefoot-data-migration.md |
| 35 | +[Third-party content type migration]: new-content-type-example.md |
| 36 | +[Iconography]: iconography.md |
| 37 | +[Add image uploader to content type]: image-uploader.md |
| 38 | +[Module integration]: module-integration.md |
| 39 | +[Additional data configuration]: custom-configuration.md |
| 40 | +[Content type configuration]: content-type-configuration.md |
| 41 | +[How to add a new content type]: how-to-add-new-content-type.md |
| 42 | +[Bindings]: bindings.md |
| 43 | +[Events]: events.md |
| 44 | +[Master format]: master-format.md |
| 45 | +[Visual select]: visual-select.md |
| 46 | +[Reuse product conditions in content types]: product-conditions.md |
| 47 | +[Store component master format as widget directive]: widget-directive.md |
| 48 | +[Render a content type preview]: content-type-preview.md |
| 49 | +[Use the block chooser UI component]: block-chooser-component.md |
| 50 | +[Custom Toolbar]: toolbar.md |
| 51 | +[Roadmap and known issues]: roadmap.md |
| 52 | + |
| 53 | +## What's in this topic |
| 54 | + |
| 55 | +This topic describes how to use the block chooser UI component for a custom content type. |
| 56 | + |
| 57 | +## Overview |
| 58 | +To use the block chooser component for your custom content type: |
| 59 | + |
| 60 | +1. [Add the block select grid listing modal to content type XML](#add-the-block-select-grid-listing-modal-to-content-type-XML) |
| 61 | +2. [Add component to content type XML](#add-component-to-content-type-xml) |
| 62 | + |
| 63 | + |
| 64 | +## Configuration options |
| 65 | +Extends all `abstract` configuration. |
| 66 | + |
| 67 | +`Magento_PageBuilder/js/form/element/block-chooser` configuration options: |
| 68 | + |
| 69 | +<table> |
| 70 | + <tr> |
| 71 | + <th>Option </th> |
| 72 | + <th>Type</th> |
| 73 | + <th>Description</th> |
| 74 | + </tr> |
| 75 | + <tr> |
| 76 | + <td><code>dataUrlConfigPath</code></td> |
| 77 | + <td>String</td> |
| 78 | + <td>The path inside the PageBuilder configuration object that points to the controller URL used to request data for display in the grid. </br>For example, if you utilize the <code>additional_data</code> configuration feature and you add the URL you could specify <code>content_types.mycontenttype.additional_data.my_cusom_property.my_data_url</code>.</td> |
| 79 | + </tr> |
| 80 | + <tr> |
| 81 | + <td><code>requestParameter</code></td> |
| 82 | + <td>String</td> |
| 83 | + <td>The parameter name under which the selected entity ID will be sent when the component retrieves the metadata from the controller (which is specified by <code>dataUrlConfigPath</code>). </br>The default template is expecting the associated controller to return (at minimum) <code>title</code> and <code>is_active</code>. You can override the component template with the <code>template</code> attribute for the <code>component</code> element, and display desired data using a custom controller.</td> |
| 84 | + </tr> |
| 85 | + <tr> |
| 86 | + <td><code>modalName</code></td> |
| 87 | + <td>String</td> |
| 88 | + <td>The UI registry key to the UI component that is representing the modal containing the <code>pagebuild_block_select_grid</code> listing. </br>For example, if you include the modal element with the name <code>modal</code> in the root of your content type form, you could set it to <code>ns = ${ $.ns }, index = modal</code>.</td> |
| 89 | + </tr> |
| 90 | + <tr> |
| 91 | + <td><code>buttonTitle</code></td> |
| 92 | + <td>String</td> |
| 93 | + <td>The text displayed on the button used to open the block selection modal.</td> |
| 94 | + </tr> |
| 95 | + <tr> |
| 96 | + <td><code>displayMetadata</code></td> |
| 97 | + <td>Boolean</td> |
| 98 | + <td>Denotes whether to display the information grid describing the block in more detail; <code>true</code> by default.</td> |
| 99 | + </tr> |
| 100 | +</table> |
| 101 | + |
| 102 | +## Add the block select grid listing modal to content type XML |
| 103 | + |
| 104 | +To add the block select grid listing modal, `pagebuilder_block_select_grid`, to the XML file for a content type, `Magento_PageBuilder/view/base/pagebuilder/content_type/<your-content-type>.xml`: |
| 105 | + |
| 106 | +``` xml |
| 107 | +<modal name="modal" sortOrder="30"> |
| 108 | + <settings> |
| 109 | + <options> |
| 110 | + <option name="title" xsi:type="string" translate="true">Select Block...</option> |
| 111 | + <option name="buttons" xsi:type="array"> |
| 112 | + <item name="0" xsi:type="array"> |
| 113 | + <item name="text" xsi:type="string" translate="true">Cancel</item> |
| 114 | + <item name="actions" xsi:type="array"> |
| 115 | + <item name="0" xsi:type="string">closeModal</item> |
| 116 | + </item> |
| 117 | + </item> |
| 118 | + <item name="1" xsi:type="array"> |
| 119 | + <item name="text" xsi:type="string">Add Selected</item> |
| 120 | + <item name="class" xsi:type="string">action-primary</item> |
| 121 | + <item name="actions" xsi:type="array"> |
| 122 | + <item name="0" xsi:type="array"> |
| 123 | + <item name="targetName" xsi:type="string">${ $.name }.pagebuilder_block_select_grid</item> |
| 124 | + <item name="actionName" xsi:type="string">save</item> |
| 125 | + </item> |
| 126 | + <item name="1" xsi:type="string">closeModal</item> |
| 127 | + </item> |
| 128 | + </item> |
| 129 | + </option> |
| 130 | + </options> |
| 131 | + </settings> |
| 132 | + <insertListing name="pagebuilder_block_select_grid" sortOrder="10"> |
| 133 | + <settings> |
| 134 | + <externalData>block_id</externalData> |
| 135 | + <externalProvider>${ $.ns }.pagebuilder_block_select_grid_data_source</externalProvider> |
| 136 | + <loading>false</loading> |
| 137 | + <selectionsProvider>${ $.ns }.${ $.ns }.columns.ids</selectionsProvider> |
| 138 | + <autoRender>true</autoRender> |
| 139 | + <dataScope>select_id</dataScope> |
| 140 | + <ns>pagebuilder_block_select_grid</ns> |
| 141 | + <dataLinks> |
| 142 | + <imports>false</imports> |
| 143 | + <exports>true</exports> |
| 144 | + </dataLinks> |
| 145 | + </settings> |
| 146 | + </insertListing> |
| 147 | +</modal> |
| 148 | +``` |
| 149 | + |
| 150 | +If desired, modify the `title` option to fit your situation. |
| 151 | + |
| 152 | +## Add component to content type XML |
| 153 | + |
| 154 | +To insert the block chooser UI component, `Magento_PageBuilder/js/form/element/block-chooser`, into the XML file for a content type, `Magento_PageBuilder/view/base/pagebuilder/content_type/<your-content-type>.xml`: |
| 155 | + |
| 156 | +``` xml |
| 157 | +<component component="Magento_PageBuilder/js/form/element/block-chooser" name="block_chooser" sortOrder="10"> |
| 158 | + <argument name="data" xsi:type="array"> |
| 159 | + <item name="config" xsi:type="array"> |
| 160 | + <item name="requestParameter" xsi:type="string">block_id</item> |
| 161 | + <item name="dataUrlConfigPath" xsi:type="string">content_types.block.additional_data.chooserConfig.dataUrl</item> |
| 162 | + <item name="modalName" xsi:type="string">ns = ${ $.ns }, index = modal</item> |
| 163 | + <item name="buttonTitle" xsi:type="string" translate="true">Select Block...</item> |
| 164 | + </item> |
| 165 | + </argument> |
| 166 | + <settings> |
| 167 | + <imports> |
| 168 | + <!-- This references the value of the block_id field below --> |
| 169 | + <link name="id">${ $.ns }.${ $.ns }.general.block_id:value</link> |
| 170 | + </imports> |
| 171 | + </settings> |
| 172 | +</component> |
| 173 | +<field name="block_id" formElement="hidden" sortOrder="20"> |
| 174 | + <settings> |
| 175 | + <dataType>text</dataType> |
| 176 | + <imports> |
| 177 | + <link name="value">${ $.ns }.${ $.ns }.modal.pagebuilder_block_select_grid:externalValue</link> |
| 178 | + </imports> |
| 179 | + </settings> |
| 180 | +</field> |
| 181 | +``` |
| 182 | +The `block_id` field pulls in the selected value from the modal. |
| 183 | + |
| 184 | +Then the `block_chooser` component pulls in the value from the `block_id` field to ascertain when it should commence updating. |
0 commit comments