Ligantic
Knowledge Base
Tutorials
Updates
Search Articles
Login
Free Sign Up
Home
Get Started
Tutorials
How-to guides
Reference
Explanation
Spaces
Schemas
Flows
Experiences
Endpoints
SDK and CLI
Browse documentation
Home
Get Started
Spaces
Schemas
Flows
Experiences
Endpoints
SDK and CLI
Docs
/

Entity Context

An entity context wraps a region of an Experience so that descendant blocks (Input, Button, and Text blocks) can read from and write to the same underlying Record. Configure it from the Entity Context section of the block settings panel on any block that supports the entityContext prop (such as Box, Button, or Link blocks).

Settings Panel

Open the Entity Context section of the block settings panel. With the toggle enabled you can configure:

  • Name — display name for the datum (defaults to the Schema name).
  • Literal — author the Schema inline rather than referencing a Schema in the Space.
  • Schema — pick the Schema this entity context represents.
  • Lookup — how the Record is loaded.
  • Field overrides — per-field defaults and enforced values applied at render and save time.

Lookup Mode

The Lookup selector chooses how the Record is loaded:

Mode

Meaning

None

The entity context is in-memory only.

By Id

Reads a Record ID from a datum reference (for example, a URL parameter or parent query result) and fetches that Record.

By Query

Runs a filter against the Schema and uses the first match. If no Record matches, the entity context enters the new state — defaults are applied and a CRUD save will create the Record.

Switching modes preserves the configuration for the side you switch back to whenever possible (an existing query filter is kept while you visit By Id mode, for example).

The By Query mode reuses the same filter builder used by query blocks, so any combination of property and relationship filters is available.

Field Overrides

Field overrides are an ordered list of { mode, schemaPath, value } entries.

  • Default seeds an initial value when the entity context is in the new state. The user can still edit the field.
  • Enforce locks the field — bound Input blocks render read-only and the value is always sent on save.

For each row you can:

  • Toggle between Default and Enforce.
  • Pick the target Schema path (data fields and relationship fields are both selectable).
  • Edit the value as a literal or a datum reference. The override editor does not support contextValue.
  • Reorder the row up or down, or remove it.

Set Field Overrides from Query

When the lookup is in By Query mode, a From Query button appears next to Add. It inspects the current filter and proposes enforce overrides derived from it:

Filter shape

Generated override

relationship with fromId

enforce on the queried Schema's toSchemaPath (the property holding the FROM ID).

relationship with toId

enforce on the queried Schema's fromSchemaPath (the property holding the TO ID).

property with eq

enforce on the property path with the same value.

The button opens a preview popover showing:

  • Overrides that will be appended to the existing list.
  • Overrides that are skipped because the same schemaPath is already configured. Existing hand edits are never silently overwritten — you can remove the conflicting row first if you want the derived value to win.

Click Append N to apply, or Cancel to discard.

Unsaved Changes

Every entity context tracks whether it holds unsaved changes. Blocks read this through meta.* paths on the entity context's datum: bind a Text block to one, or use one in a data state condition.

Path

Meaning

meta.state

pending while loading, loaded for a Record that was loaded, new for one that doesn't exist yet, or error.

meta.isDirty

true while there are unsaved changes.

meta.dirtyFields

The top-level fields with unsaved changes.

meta.error

The last error from a CRUD action, if any.

What counts as a change depends on the entity context:

  • A Record (a Schema from the Space): changes are measured from the Record as it was loaded. A new Record in a by-id context always counts as changed, so a save creates it. A by-query context with no match measures changes from its initial value instead; it stays clean until that value changes, and saving then creates the Record.
  • A draft (a Literal Schema): changes are measured from its initial value: its defaults, values passed in the URL, and its field overrides. A draft nobody has typed into has no unsaved changes, and changing a value back to where it started clears the change. A field that was empty and is emptied again, for example by clearing an input, counts as unchanged.

Batch

A Batch entity context (choose Batch instead of Datum) collects every entity context inside it, including one per row or cell of a For Each. Its datum adds:

Path

Meaning

meta.isDirty / meta.isBatchDirty

true while any entity context inside has unsaved changes.

meta.dirtyCount

How many entity contexts inside have unsaved changes.

meta.newCount

How many entity contexts inside are new.

meta.hasErrors

true when any entity context inside has an error.

meta.dirtyValues

The values of the entity contexts inside that have unsaved changes, as a list. Pass it to a Flow to save them (see below).

A CRUD Save targeting the batch saves each Record inside that has unsaved changes. A CRUD action's On Success: Reset on the batch discards the unsaved changes of every entity context inside it.

Show Unsaved Changes and Enable Save

To make a Save button light up only when there is something to save:

  1. Wrap the editable blocks and the Save button in a Box with a Batch entity context.
  2. Add a Text block bound to the batch's meta.dirtyCount, for a status such as "3 unsaved changes". Use a data state on meta.isBatchDirty to switch to "No unsaved changes".
  3. Give the Save button a Disabled state that is active while the batch has no unsaved changes. While it is active, the button can't be clicked and shows the Disabled state's styling.
  4. To highlight a changed field or cell, add a data state on its own entity context's meta.isDirty.

The Disabled state's condition reads the batch's meta.isBatchDirty and checks the value itself (an empty condition path):

{
  "id": "disabled",
  "name": "Disabled",
  "activation": {
    "when": {
      "type": "datumCondition",
      "datum": {
        "type": "datumReference",
        "referenceId": "counts",
        "path": ["meta", "isBatchDirty"]
      },
      "condition": {
        "type": "property",
        "path": [],
        "operator": "eq",
        "value": { "type": "literal", "value": false }
      }
    }
  },
  "overrides": { "background": [{ "color": "#c7ccd4" }] }
}

counts is the batch entity context's id.

Send Unsaved Changes to a Flow

A Flow button can pass a batch's unsaved changes to its Flow: map a trigger input of type array to the batch's meta.dirtyValues. The Flow receives one item per changed entity context inside the batch, each with its full value (including its defaults and field overrides), and can create or update Records from them, for example with List - Map. This saves drafts that are not Records themselves, such as one draft per cell of a grid.

Before the Flow runs, each changed entity context is validated against its Schema, as a CRUD Save on a batch does. If any is invalid, the Flow doesn't run and the errors show under the fields.

To clear the drafts once the Flow has saved them, set the button's On Success to Reset with the batch as the target. To show the saved Records straight away, end the Flow with a UX - Action that refetches data: lists and queries over that Schema reload, including grouped totals.

Any meta.* path can be mapped to a trigger input the same way, for example an entity context's meta.isDirty.

The Studio's datum pickers, condition editor and Flow input mapping don't list meta.* paths, so set these bindings, conditions and inputs in the Experience's JSON, for example with the CLI or API.

Migrating Legacy Configurations

Earlier versions stored the lookup as lookupEntityById / lookupEntityByIdSource. These are converted automatically to the lookup: { mode: "id", idSource } shape, and the editor saves the new shape on the next write. No manual migration is required — opening and saving any affected Experience is sufficient.

Related pages

Button
Interactive block that renders Text and Image children and triggers configured actions.
Page not found. It may have moved or may not be published.
Browse documentation