Form | CYPEX Documentation

Tips & examples

A form layout for one record, with Back, Reset, and Save in the bottom bar.

When to use

Create, edit, or show a single database record with inputs bound to its fields.
Provide the data context that child inputs bind to via Element Id and Field Path.

What you need

Needs a Data Source (query name). Edit and detail also need Identifier Name and Identifier Value.

Examples

A customer profile create screen with default field values.
An edit screen that loads one record by id, validates changes, and saves.

Avoid

Nesting forms inside forms — use a Sub Form when several related records must be edited together.
Choosing edit or detail without an Identifier Value, which leaves the form empty.
Leaving On Success empty on create forms when the user should navigate away or refresh related data after save.

Properties

Editor properties

Configure these in the Application Designer property panel. Group headings mirror the editor where possible. Data Source is where the element gets its rows or field binding (a view/query, a connector operation, or a parent form field). References appear only for view-backed sources and map foreign-key ID columns to readable labels from another view.

Form Type

TyperequiredOne of: edit, create, detail

Discriminator selecting which configuration variant applies.

Choices

edit — Loads one record by identifier and lets the user change and save it.
create — Empty form for inserting a new record. Supports default data and post-save actions.
detail — Shows one record read-only.

Default: FormTypes.create

Data Source

View NamerequiredTextInside `dataSource`: Database view that supplies rows or form data.
Default: none
Identifier NameoptionalTextInside `dataSource`: Primary-key field used to load a single record (edit/detail).
Default: none
State Field NameoptionalTextInside `dataSource`: Workflow state field on the bound view.
Default: none
Identifier ValueoptionalCustom expressionInside `dataSource`: Expression resolving the record id (often from URL query).
Example null
Default: none

References

View NamerequiredTextInside `dataSource`: Database view that supplies rows or form data.
Default: none

Setup

Back button and post-save actions (mainly used on create forms).

Hide Back ButtonoptionalYes / no: Hides the Back button in the form’s bottom bar.
Default: none
On SuccessoptionalList of Element data source or type + notification or type + linkTo + notification or Connector data source: Actions run after a successful save (navigation, notifications, connectors).
Default: none

Styles

Disable SpacingoptionalYes / no: When true, removes inner padding so fields sit tighter in the layout.
Default: none

Validation

ValidationoptionalCustom expression: Custom expression or rule evaluated before save.
Example true
Default: none
JSON SchemaoptionalStructured JSON: Optional JSON Schema used for additional field validation.
Default: none

Default Data

Initial field values for create forms.

Default DataoptionalKey-value map: Initial field values when creating a new record.
Default: none

Inside `dataSource.connector_data_source`: (connector_data_source) ↕

Connector IDrequiredText

Installed connector that provides external data or actions.

Default: none

Read InputoptionalKey-value map

Configuration for read Input.

Default: none

Read Operation KeyoptionalText

Configuration for read Operation Key.

Default: none

SourcerequiredOne of: connector

Configuration for source.

Choices

connector

Default: none

Write InputoptionalKey-value map

Configuration for write Input.

Default: none

Write Operation KeyoptionalText

Configuration for write Operation Key.

Default: none

Inside `dataSource.view_data_source`: (view_data_source) ↕

Identifier NameoptionalText

Primary-key field used to load a single record (edit/detail).

Default: none

Multi ReferenceoptionalKey-value map

Map of related collections loaded alongside the main record.

Default: none

SourceoptionalOne of: view

Configuration for source.

Choices

view

Default: none

Inside `dataSource.view_data_source.multiReference.$entry`: (Each map entry) ↕

Identifier Field NamerequiredText: Field in the related view that holds the foreign key.
Default: none
Referencing Field NamerequiredText: Field on the main record that references the related view.
Default: none
View NamerequiredText: Database view that supplies rows or form data.
Default: none

Inside `onSuccess.$item.reload_table`: (reload_table) ↕

Element IDrequiredText

Another element on the page whose data backs this field.

Default: none

NotificationoptionalSettings group

Toast or banner shown after the action completes.

Default: none

TyperequiredOne of: reload_table

Discriminator selecting which configuration variant applies.

Choices

reload_table

Default: none

Inside `onSuccess.$item.reload_table.notification`: (notification) ↕

MessagerequiredText or Custom expression (text): User-visible notification text.
Default: none
PersistoptionalYes / no: Configuration for persist.
Default: none
VariantoptionalText: Configuration for variant.
Default: none

Inside `onSuccess.$item.save_form`: (save_form) ↕

Element IDrequiredText

Another element on the page whose data backs this field.

Default: none

NotificationoptionalSettings group

Toast or banner shown after the action completes.

Default: none

TyperequiredOne of: save_form

Discriminator selecting which configuration variant applies.

Choices

save_form

Default: none

Inside `onSuccess.$item.save_form.notification`: (notification) ↕

MessagerequiredText or Custom expression (text): User-visible notification text.
Default: none
PersistoptionalYes / no: Configuration for persist.
Default: none
VariantoptionalText: Configuration for variant.
Default: none

Inside `onSuccess.$item.reload_form`: (reload_form) ↕

Element IDrequiredText

Another element on the page whose data backs this field.

Default: none

NotificationoptionalSettings group

Toast or banner shown after the action completes.

Default: none

TyperequiredOne of: reload_form

Discriminator selecting which configuration variant applies.

Choices

reload_form

Default: none

Inside `onSuccess.$item.reload_form.notification`: (notification) ↕

MessagerequiredText or Custom expression (text): User-visible notification text.
Default: none
PersistoptionalYes / no: Configuration for persist.
Default: none
VariantoptionalText: Configuration for variant.
Default: none

Inside `onSuccess.$item.refresh_chart`: (refresh_chart) ↕

Element IDrequiredText

Another element on the page whose data backs this field.

Default: none

NotificationoptionalSettings group

Toast or banner shown after the action completes.

Default: none

TyperequiredOne of: refresh_chart

Discriminator selecting which configuration variant applies.

Choices

refresh_chart

Default: none

Inside `onSuccess.$item.refresh_chart.notification`: (notification) ↕

MessagerequiredText or Custom expression (text): User-visible notification text.
Default: none
PersistoptionalYes / no: Configuration for persist.
Default: none
VariantoptionalText: Configuration for variant.
Default: none

Inside `onSuccess.$item.refresh_display_data`: (refresh_display_data) ↕

Element IDrequiredText

Another element on the page whose data backs this field.

Default: none

NotificationoptionalSettings group

Toast or banner shown after the action completes.

Default: none

TyperequiredOne of: refresh_display_data

Discriminator selecting which configuration variant applies.

Choices

refresh_display_data

Default: none

Inside `onSuccess.$item.refresh_display_data.notification`: (notification) ↕

MessagerequiredText or Custom expression (text): User-visible notification text.
Default: none
PersistoptionalYes / no: Configuration for persist.
Default: none
VariantoptionalText: Configuration for variant.
Default: none

Inside `onSuccess.$item.refresh_geojson_field`: (refresh_geojson_field) ↕

Element IDrequiredText

Another element on the page whose data backs this field.

Default: none

NotificationoptionalSettings group

Toast or banner shown after the action completes.

Default: none

TyperequiredOne of: refresh_geojson_field

Discriminator selecting which configuration variant applies.

Choices

refresh_geojson_field

Default: none

Inside `onSuccess.$item.refresh_geojson_field.notification`: (notification) ↕

MessagerequiredText or Custom expression (text): User-visible notification text.
Default: none
PersistoptionalYes / no: Configuration for persist.
Default: none
VariantoptionalText: Configuration for variant.
Default: none

Inside `onSuccess.$item.toggle_modal`: (toggle_modal) ↕

Element IDrequiredText

Another element on the page whose data backs this field.

Default: none

NotificationoptionalSettings group

Toast or banner shown after the action completes.

Default: none

TyperequiredOne of: toggle_modal

Discriminator selecting which configuration variant applies.

Choices

toggle_modal

Default: none

Inside `onSuccess.$item.toggle_modal.notification`: (notification) ↕

MessagerequiredText or Custom expression (text): User-visible notification text.
Default: none
PersistoptionalYes / no: Configuration for persist.
Default: none
VariantoptionalText: Configuration for variant.
Default: none

Inside `onSuccess.$item.reset_input`: (reset_input) ↕

Element IDrequiredText

Another element on the page whose data backs this field.

Default: none

NotificationoptionalSettings group

Toast or banner shown after the action completes.

Default: none

TyperequiredOne of: reset_input

Discriminator selecting which configuration variant applies.

Choices

reset_input

Default: none

Inside `onSuccess.$item.reset_input.notification`: (notification) ↕

MessagerequiredText or Custom expression (text): User-visible notification text.
Default: none
PersistoptionalYes / no: Configuration for persist.
Default: none
VariantoptionalText: Configuration for variant.
Default: none

Inside `onSuccess.$item.show_notification`: (show_notification) ↕

NotificationrequiredSettings group

Toast or banner shown after the action completes.

Default: none

TyperequiredOne of: show_notification

Discriminator selecting which configuration variant applies.

Choices

show_notification

Default: none

Inside `onSuccess.$item.show_notification.notification`: (notification) ↕

MessagerequiredText or Custom expression (text): User-visible notification text.
Default: none
PersistoptionalYes / no: Configuration for persist.
Default: none
VariantoptionalText: Configuration for variant.
Default: none

Inside `onSuccess.$item.navigate`: (navigate) ↕

Link TorequiredSettings group

In-app navigation target (page and parameters).

Default: none

NotificationoptionalSettings group

Toast or banner shown after the action completes.

Default: none

TyperequiredOne of: navigate

Discriminator selecting which configuration variant applies.

Choices

navigate

Default: none

Inside `onSuccess.$item.navigate.linkTo`: (linkTo) ↕

Page IDrequiredText: Target page id in the application menu.
Default: none
ParamsrequiredKey-value map: Query parameters passed to the target page.
Default: none

Inside `onSuccess.$item.navigate.notification`: (notification) ↕

MessagerequiredText or Custom expression (text): User-visible notification text.
Default: none
PersistoptionalYes / no: Configuration for persist.
Default: none
VariantoptionalText: Configuration for variant.
Default: none

Inside `onSuccess.$item.go_back`: (go_back) ↕

NotificationoptionalSettings group

Toast or banner shown after the action completes.

Default: none

TyperequiredOne of: go_back

Discriminator selecting which configuration variant applies.

Choices

go_back

Default: none

Inside `onSuccess.$item.go_back.notification`: (notification) ↕

MessagerequiredText or Custom expression (text): User-visible notification text.
Default: none
PersistoptionalYes / no: Configuration for persist.
Default: none
VariantoptionalText: Configuration for variant.
Default: none

Inside `onSuccess.$item.reset_table_selection`: (reset_table_selection) ↕

Element IDrequiredText

Another element on the page whose data backs this field.

Default: none

NotificationoptionalSettings group

Toast or banner shown after the action completes.

Default: none

TyperequiredOne of: reset_table_selection

Discriminator selecting which configuration variant applies.

Choices

reset_table_selection

Default: none

Inside `onSuccess.$item.reset_table_selection.notification`: (notification) ↕

MessagerequiredText or Custom expression (text): User-visible notification text.
Default: none
PersistoptionalYes / no: Configuration for persist.
Default: none
VariantoptionalText: Configuration for variant.
Default: none

Inside `onSuccess.$item.execute_connector_operation`: (execute_connector_operation) ↕

Connector IDrequiredText

Installed connector that provides external data or actions.

Default: none

Input MappingoptionalKey-value map

Maps connector input fields to expressions or literals.

Default: none

NotificationoptionalSettings group

Toast or banner shown after the action completes.

Default: none

Operation KeyrequiredText

Connector operation invoked by this element or action.

Default: none

TyperequiredOne of: execute_connector_operation

Discriminator selecting which configuration variant applies.

Choices

execute_connector_operation

Default: none

Inside `onSuccess.$item.execute_connector_operation.notification`: (notification) ↕

MessagerequiredText or Custom expression (text): User-visible notification text.
Default: none
PersistoptionalYes / no: Configuration for persist.
Default: none
VariantoptionalText: Configuration for variant.
Default: none

Sizing

Minimum size: 4 × 3 grid cells (width × height).
Default size when dropped on a page: 12 × 5.

Accessibility

Renders as a semantic form. Focus moves through fields in order; validation messages are associated with their inputs for screen readers.

Expressions

Values you can read in expressions

Other parts of your app can read live values from this element in custom expressions:

elements.myForm.<property>

loadState object Async state of the initial load (idle, loading, success, error). elements.myForm.loadState

saveState object Async state of the last save attempt. elements.myForm.saveState

data null The current form values, keyed by field name. elements.myForm.data.quantity

When Read a field the user is currently editing, before it is saved — for example to show a live total or drive a conditional container.

errors any Field-level validation errors after submit or blur. elements.myForm.errors

originalData null Snapshot of data as loaded (before user edits). elements.myForm.originalData

touched Record<string | number, boolean> Map of fields the user has interacted with. elements.myForm.touched

hasChanges boolean True when any field differs from the loaded record. elements.myForm.hasChanges

When Warn before navigating away, or only enable a Save button once something has actually been edited. True as soon as any field differs from the loaded record.

isValid boolean True when all validation rules pass. elements.myForm.isValid

When Disable a Save or Submit button until every field passes validation, instead of letting the user click and receive an error.

identifier string | number Resolved primary-key value for the loaded record. elements.myForm.identifier

When The primary-key value of the loaded record. Use it to filter a related table or pass a parameter to another page. Empty on a create form, since the record does not exist yet.

To use one of these, open the property you want to drive on the other element, switch it to expression mode in the Expression Editor, and enter:

1
elements.myForm.data

Replace myForm with this element’s unique id. Select the element in Application Designer and copy the id chip at the top of the right-hand property panel.

Composition

Child slots

This container accepts nested elements in these slots:

slot	accepts
`content`	any element

Nesting overview

graph TD
  root["default_form"]
  root --> content["content slot"]

Where you can place it

Drag this element into one of these containers:

Sample configuration

Minimal example — required fields only ↕

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
{
  "config": {
    "dataSource": {
      "source": "connector",
      "connectorId": "my_connector",
      "identifierName": "identifierName",
      "readOperationKey": "readOperationKey",
      "readInput": {
        "exampleKey": "@@expression:'value'"
      },
      "writeOperationKey": "writeOperationKey",
      "writeInput": {
        "exampleKey": "@@expression:'value'"
      }
    },
    "type": "edit"
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
{
  "config": {
    "dataSource": {
      "source": "connector",
      "connectorId": "my_connector",
      "identifierName": "identifierName",
      "readOperationKey": "readOperationKey",
      "readInput": {
        "exampleKey": "@@expression:'value'"
      },
      "writeOperationKey": "writeOperationKey",
      "writeInput": {
        "exampleKey": "@@expression:'value'"
      }
    },
    "type": "edit",
    "jsonSchema": {},
    "validation": "@@expression:'value'",
    "defaultData": {
      "exampleKey": "@@expression:'value'"
    },
    "hideBackButton": false,
    "disableSpacing": false,
    "onSuccess": [
      {
        "type": "reload_table",
        "elementId": "myElement",
        "notification": {
          "message": "message",
          "variant": "variant",
          "persist": false
        }
      },
      {
        "type": "save_form",
        "elementId": "myElement",
        "notification": {
          "message": "message",
          "variant": "variant",
          "persist": false
        }
      }
    ]
  },
  "children": {
    "content": [
      {
        "type": "default_text_input",
        "config": {
          "label": "Name"
        }
      },
      {
        "type": "default_form_button",
        "config": {
          "label": "Save",
          "action": "save"
        }
      }
    ]
  }
}