Form and Card Related tables

A Related table is a Form or Card Surface item that embeds the Table Surface of a standalone child Entity. Its independent mode gives users a child-record workflow while they edit an already saved parent. Its With the parent record mode also works while creating the parent and saves the whole draft together.

On a Form, the item saves its children in one of two modes:

• Independently (default, and always on Card): 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.
• With the parent record: child changes are staged in the Form and saved with the parent in one transaction, also while the parent is being created. See Save related records with the parent.

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 item. 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 or Card Surface.
3. In the item Add menu, choose Related table.
4. Select one server-provided inverse relationship.
5. Set its label, optional hint, visibility, order, and—on Card—optional tab. In independent Form mode, leave Show the save notice enabled to explain the save behavior, or switch it off when that explanation is already provided elsewhere.
6. Configure Table Surface selectors when different roles need different child tables.
7. Save the item and the complete leaf Surface.
8. For independent Form mode, test both create and edit: create shows a local placeholder; edit loads only children of that saved parent. For With the parent record, use the setup and checks below for a shared draft. Test Card in every host where the selected CardSurface is used.

Related Table always occupies a complete Form row or the full current Card container. It has no Column or Column span control. Its order still comes from the leaf 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.

Independent mode 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, a Form shows one independent-save notice if any visible Related table has it enabled. Card hosts do not show this notice. Hiding it does not change when child records save. 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.

Save related records with the parent

In the Form item editor set Saving related records to With the parent record. Then configure:

• Presentation — Table for any number of children, or Inline (single record), which shows the fields of the only child directly in the Form. Inline is offered only when a unique constraint on the child’s Reference to the parent proves that a parent has at most one child (all records or active records).
• Form of the related record — the child Form Surface used to add and edit children (selectors like any other surface selector; default is the child’s default Form). The child’s Reference to the parent is set by the server and never sent by the browser, so it can stay off that Form.
• Visible when / Required when — optional conditions over the parent record, written like field conditions (for example Status <> "Closed"). Users see them applied to the unsaved parent; the save decides them again on the saved parent. A comparison with an empty value is false, so Status <> "Closed" also hides the section while Status is empty; cover the empty case in the condition when the section should show then.
• When the section is hidden — Keep its records (default), Refuse saving while it has records, or Archive its records on save (the user reviews and confirms the records before the save archives them). The rule is checked on every save that leaves the section hidden while it still has active records, also when it was hidden before.

A relation may appear on the Form more than once, for example as a table on one tab and inline on another. Its items share one set of pending child changes, owned by the first of them in Form order, so a change made in one appears in the others. They must agree on Saving related records, Visible when, Required when and When the section is hidden; presentation and the Form of the related record may differ. Items that disagree are refused when you save the Form, import it or apply a package. Section conditions must compile against the parent definition; a later rename, type change or deletion of a parent field they use is refused until the condition is changed.

An older Form editor that does not know these settings cannot save the Form over them: the save is refused and nothing changes. Reload the page and edit again.

Creating a record from a related table of another record (Add in a related table, Drawer or Details) opens the target’s create Form. When that Form has sections that save with the parent, the new record and its children are saved together, and the server sets the relation to the record you started from.

Saving with the parent changes what users can rely on: the parent and every pending child change commit together or not at all; a refused child keeps the whole draft on screen with the error on that child; exact repeats after a lost answer cannot save twice. Rights are still checked per record: a user who may update children but not the parent can save child changes only when the parent itself is unchanged.

Such a user still sees Edit on a parent they can read but not update — in lists, related tables, Details and the Drawer — when the edit Form chosen for their roles has a section that saves with the parent and their child permissions allow adding, editing, archiving or deleting those records. The Form then shows the parent read-only: they can change only the related records their permissions allow, and the save checks that the parent was not changed by someone else in the meantime. Without such a section, or without those child permissions, Edit appears only for users who may update the parent.

Existing Forms keep the independent behavior until you change the setting. Packages set the same members with the SDK (SaveWithParent(), Inline(), VisibleWhen(...), RequiredWhen(...), WhenHidden(...), RelatedForm(...)) and apply them through Check → Build → Activate.

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.

When the business requirement is atomic parent-and-child creation or rollback, use a Related Table that saves with the parent record; an independent Related Table requires the parent to exist before child work starts.

Acceptance checklist

Verify the configuration with at least an editor, reader, and no-access actor (for an independent Related table; for one that saves with the parent, verify create with children, edit, children-only changes, Undo/Cancel and a refused child instead):

• 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 only the table without resetting an unsaved parent field or reloading the containing card;
• 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.