>>> [!note] Migrated issue <!-- Drupal.org comment --> <!-- Migrated from issue #3477428. --> Reported by: [effulgentsia](https://www.drupal.org/user/78040) >>> <h3 id="overview">Overview</h3> <p>Currently, the XB field type is a <a href="https://git.drupalcode.org/project/experience_builder/-/blob/0.1.0-alpha1/src/Plugin/Field/FieldType/ComponentTreeItem.php?ref_type=tags#L55">single-item</a> field with two columns: <a href="https://git.drupalcode.org/project/experience_builder/-/blob/0.1.0-alpha1/src/Plugin/Field/FieldType/ComponentTreeItem.php?ref_type=tags#L90">tree and props</a>, each defined as a JSON structure.</p> <p><span class="drupalorg-gitlab-issue-link drupalorg-gitlab-link-wrapper"><a href="https://git.drupalcode.org/project/experience_builder/-/work_items/3468272" class="drupalorg-gitlab-link">https://git.drupalcode.org/project/experience_builder/-/work_items/3468272</a></span> proposes to store the tree relationally, not as a JSON value.</p> <p>Option #3 in the proposed resolution of <span class="drupalorg-gitlab-issue-link project-issue-status-info project-issue-status-4"><a href="https://www.drupal.org/project/drupal/issues/3440578" title="Status: Postponed">#3440578: [PP-2] JSON-based data storage proposal for component-based page building</a></span> proposes to associate a field_union type with each component instance's static prop values in order to facilitate code outside of XB being able to use the information in the corresponding field_union config entities to implement Views integrations, migration tooling, configuring search indexes or other special view modes, etc.</p> <p>This issue proposes to combine the de-jsonifying of the tree and the addition of the field_union type reference into a single refactor.</p> <h3 id="proposed-resolution">Proposed resolution</h3> <ul> <li>Change the field type from single-item to multi-valued. Each item would be for a single component instance.</li> <li>Order (the <code>delta</code> column of) the items the same as how they appear in the left sidebar's Layers panel. This corresponds to how the component instances are ordered in the HTML when the page is rendered except where components render their slots in a different order than the order in which those slots are defined in the SDC's YAML.</li> <li>Define the following columns (properties) in the field type: <ul> <li><code>instance_id</code> (string)</li> <li><code>component</code> (string): Reference to the <code>component</code> config entity that defines the component that this is an instance of.</li> <li><code>parent</code> (string): The instance ID of the parent component in the tree. NULL for component instances that are at the top-level in the tree.</li> <li><code>slot</code> (string): The parent's slot that this component is in. NULL for component instances that are at the top-level in the tree or are in the default/unnamed slot of their parent (if in the future we decide to add support for default/unnamed slots).</li> <li><code>data_sources</code> (json): The <code>sourceTypes</code> and <code>expression</code> portion of what's currently in the <code>props</code> column (prior to this proposed refactoring) for this component instance. For example:<br> <pre>{<br>&nbsp; "prop1": {<br>&nbsp;&nbsp;&nbsp; "sourceType": "dynamic",<br>&nbsp;&nbsp;&nbsp; "expression": "&#8505;&#65038;&#9244;entity:node:article&#9245;title&#9246;&#9247;value"<br>&nbsp; },<br>&nbsp; "prop2": {<br>&nbsp;&nbsp;&nbsp; "sourceType": "static:field_item:string",<br>&nbsp;&nbsp;&nbsp; "expression": "&#8505;&#65038;string&#9247;value"<br>&nbsp; }<br>}</pre></li> <li><code>static_values</code> (json): The <code>value</code> portion of what's currently in the <code>props</code> column (prior to this proposed refactoring) for this component instance. For example, given the above example of <code>data_sources</code>, this could be:<br> <pre>{<br>&nbsp; "prop2": "Hello, world!"<br>}</pre><p> The above example uses XB's current optimization of omitting the column/property name within the sourceType's field type if it's the sole property being used and it corresponds to the field type's <code>mainPropertyName()</code>. Given this issue's proposal to add a <code>field_union</code> reference (see below), we should evaluate if it would be better for people using that reference if we always explicitly included the column/property name, in which case the above would be:</p> <pre>{<br>&nbsp; "prop2": {<br>&nbsp;&nbsp;&nbsp; "value": "Hello, world!"<br>&nbsp; }<br>}</pre></li> <li><code>field_union</code> (string):<br> Reference to the <code>field_union</code> config entity that defines the union of field types for this component. Alternatively, we could omit this from here and instead add the field_union reference to the <code>component</code> config entity. Since the component instance references the component config entity, this would just then be one more hop to get to the field_union config entity, but denormalizing the field_union reference into here might help with querying since Drupal doesn't have great support for JOINing on config entities (though that support could be improved if Drupal core refactored the <code>config</code> table to store as JSON instead of serialized PHP).<br><br>Whether the <code>field_union</code> reference is in this field type directly, or only indirectly via <code>component</code>, it can be NULL in cases where <code>static_values</code> can't be, or wouldn't benefit from being, conformed to a field_union definition. Note that a field_union can be a union of fields that are of any type, including a JSON field, so the "wouldn't benefit from being" is more likely to be the case than "can't be". An example of this might be the values for block settings that we either can't or choose not to define field_union types for. </li> </ul> </li> </ul> <h3 id="ui-changes">User interface changes</h3> <p>None</p> <h3 id="caveats">Caveats</h3> <ul> <li>It would be nice to have the field_union module be an optional dependency rather than required for XB to function. See comment #5.</li> <li>@lauriii, @catch, @alexpott, @longwave, @Wim Leers, @tedbow, and I (@effulgentsia) met during DrupalCon Barcelona and there was disagreement on whether the <code>field_union</code> reference would be useful. @catch thinks it's needed to support <span class="drupalorg-gitlab-issue-link drupalorg-gitlab-link-wrapper"><a href="https://git.drupalcode.org/project/canvas/-/work_items/3462219" class="drupalorg-gitlab-link">https://git.drupalcode.org/project/canvas/-/work_items/3462219</a></span>, but @lauriii thinks those use cases could be solved in better ways by XB directly. The next step to try to resolve that disagreement would be to formulate some specific use cases and think through what a good UX would be for a site builder to implement them. However, regardless of whether the <code>field_union</code> reference ends up being useful in practice, I don't think it hurts anything to have it, especially if the reference is only in the <code>component</code> config entity and not denormalized into the field type.</li> <li>If some fields or field properties are marked as <code>required</code> within the field_union config entity, that will not be enforced when saving the <code>static_values</code> JSON. The reason is that XB will allow some of a component's props to be defined statically and some to come from the entity's fields or other dynamic or even remote sources. In other words, it's perfectly valid for <code>static_values</code> to only contain a subset of what's required by the field_union.</li> </ul> <h3 id="risks">Risks</h3> <p>I ran this proposal by @Wim Leers before writing it up, and he pointed out that there could be nodes with hundreds of component instances on them, so this proposal creates the possibility of a multi-valued field item with more items in it than we're typically used to in Drupal, and we don't know what performance or memory issues <code>FieldItemList</code> and its related PHP objects will encounter at that scale. This is something we'll need to keep our eyes on, but I think there's two things that mitigate the risk:</p> <ul> <li>I hope people don't actually put hundreds of component instances on a node. That wouldn't lead to a good authoring experience. A good design system, even if it includes some small components (atoms), should also include larger components (molecules, organisms) that content authors work with, so that content authors aren't in practice putting every atom one-by-one on a page.</li> <li>If we need to, we can implement a <code>list_class</code> for the XB field type that's more suitable to very large lists than <code>FieldItemList</code> is.</li> </ul> > Related issue: [Issue #3440578](https://www.drupal.org/node/3440578) > Related issue: [Issue #3170831](https://www.drupal.org/node/3170831) > Related issue: [Issue #3455629](https://www.drupal.org/node/3455629) > Related issue: [Issue #3462219](https://www.drupal.org/node/3462219) > Related issue: [Issue #2232427](https://www.drupal.org/node/2232427) > Related issue: [Issue #3523842](https://www.drupal.org/node/3523842) > Related issue: [Issue #3523844](https://www.drupal.org/node/3523844)