Form Related tables

A Related table is a Form Surface item that embeds the Table Surface of a standalone child Entity. It gives users a familiar child-record workflow while they edit an already saved parent: page and sort rows, use Tree View when the selected child table supports it, add or edit a child, open Details in a new tab, and run permitted Archive or Delete actions.

The child operations are independent mutations. They are not included in the parent form payload and are not rolled back if the user cancels the parent form.

Eligibility checklist

The Designer offers only targets returned by the server in RelatedTableTargets. A relationship is eligible when all of the following are true:

• the parent and child are standalone Data entities;
• the parent has one direct InverseReference field;
• that field is paired with one direct scalar Reference field on the child;
• the pair is explicit and points back to this parent entity;
• the relation was not generated as an Association endpoint link;
• the child has at least one Table Surface that can be selected, or a default Table Surface can be resolved at runtime.

Part and Association definitions cannot own this Form item. Card Surfaces cannot contain it. Generated association inverse paths are not eligible. The item binds exactly one relation; multi-hop paths and client-authored filters are not supported.

Prepare the child experience

Configure the child before adding the item:

1. Create the child Table Surface and its readable columns. The parent Reference column is automatically hidden inside the Related table.
2. Configure Table actions for the workflows users need. Related Table honors actor-shaped Add, Edit, Open details, Archive, and Delete behavior from that surface. Preview is not shown here.
3. Configure child create and edit Form Surfaces and the Table Surface’s form selectors.
4. Configure a Details page if Open details should be available.
5. Grant parent View and the required child permissions through Entity Security. Parent access never implies child access.
6. If the child table uses Tree View, finish its parent field, index, sorting, and security setup first.

Add the item in Designer

1. Open Constructor > Entity Explorer and choose the parent Entity Definition.
2. Open Surface library and select a Form Surface.
3. In the item Add menu, choose Related table.
4. Select one server-provided inverse relationship.
5. Set its label, optional hint, visibility, and order.
6. Configure Table Surface selectors when different roles need different child tables.
7. Save the item and the complete Form Surface.
8. Test both create and edit forms. Create must show a local placeholder; edit must load only children of that saved parent.

Related Table always occupies a complete Form row. It has no Column or Column span control. Its order still comes from the Form item’s SortOrder.

Choose the child Table Surface

Selectors use the same role-aware model as other Entity UI surface selectors:

1. Keep selectors whose role list is empty or intersects the current user’s roles.
2. Evaluate higher Priority first.
3. At the same priority, evaluate a role-specific selector before a global selector.
4. Use the stable selector id as the final tie-breaker.

Default selects the child’s current default Table Surface. An empty selector list has the same result. CustomKey must name an existing Table Surface on that exact child entity; a table from another entity is rejected. A missing custom surface is reported explicitly at runtime instead of silently choosing a different table.

A useful pattern is a global Default selector at priority 0, with one or more higher-priority CustomKey selectors for roles that need a specialized column or action set.

Runtime behavior to communicate to users

In create mode Moltaro performs no child-data request. The item shows a compact message that related records become available after the parent is saved.

In edit mode the form shows a permanent independent-save notice. The table:

• uses ten rows per page;
• provides an Active / Archived scope when Entity Security grants child View plus ReadArchive; this is independent of configured Archive/Delete actions, and Add remains available only in Active scope;
• honors the selected Table Surface’s sorting and Tree View;
• persists personal sorting with optimistic concurrency;
• hides the child Reference that binds the parent;
• excludes filter builder, saved views, bulk actions, fullscreen, Manual Order, Preview, and Unlink;
• opens child Details in a new browser tab;
• refreshes only itself after a child mutation, preserving the parent draft.

Add receives a server-owned locked parent Reference. The browser cannot supply or replace the binding/filter used to query the table. Edit and Archive are available only when both the selected Table Surface and the current actor permit the action. Delete additionally requires an archived child. After Archive, the embedded table automatically switches to Archived so the user can confirm permanent deletion with the current archived row version.

Related Table or owned Table field?

Choose a Related Table when the child is a standalone business record with its own lifecycle, permissions, detail page, audit history, and independent save. Choose an owned Table field when rows are value-like content inside the parent and must be created, validated, saved, or cancelled with the parent form.

Do not use Related Table when the business requirement is atomic parent-and- child creation or rollback. V1 requires the parent to exist before child work starts.

Acceptance checklist

Verify the configuration with at least an editor, reader, and no-access actor:

• create mode performs no related-data request;
• edit shows only children whose Reference equals the current parent;
• the parent Reference column is hidden and locked on Add;
• role-specific and default Table Surface selection resolve as intended;
• child fields and actions are shaped by the actor’s permissions;
• Add/Edit refresh the table without resetting an unsaved parent field;
• cancelling the parent does not undo a completed child mutation;
• Active/Archived scope returns the correct lifecycle state, Delete is hidden for active rows, and Archive/Delete require confirmation and persist after reload;
• Details opens in a new tab; browser back/forward retains the parent form;
• desktop and 375 px layouts remain usable, with no console or network error.

For daily use, see Related tables in forms. For exact API and YAML contracts, see the Related Table developer and agent guide.