Row Forms

Row Forms Technical Reference

View as Markdown

Row Form Options

RowFormOptions

Options related to Dynamic Row Forms in AdapTable

autoHandle?

boolean

Whether AdapTable automatically updates AG Grid data model with created/edited/deleted rows

Default

true

disableInlineEditing?

boolean

Prevents direct editing in Grid cells even for editable columns

Default

false

includeColumnInRowForm?

(rowFormColumnContext:RowFormColumnContext) => boolean

Is given Column displayed in Row Form

Default

true

onRowFormSubmit?

(rowFormSubmittedInfo:RowFormSubmittedInfo<TData>) => void

Event fired when a Row Form is submitted via a standard button provided by AdapTable; this is not invoked when custom form buttons are provided

Default

undefined

rowFormButtons?

AdaptableButton<RowFormContext<TData>>[]

Custom form buttons; if provided, need to handle form submission explicitly

rowFormDescription?

string | ((context:RowFormTitleContext<TData>) => string)

Custom form description provider

Default

undefined

rowFormField?

(context:RowFormFieldContext<TData>) => Partial<AdaptableFormField> | undefined

Per-column override for the auto-built .

Return any subset of AdaptableFormField properties to customise the
field for a particular column. Anything you don't return falls back to
AdapTable's default - which is derived from the column's data type
(string → text, number → number, boolean → checkbox, date →
date, columns with discrete options → select).

Returning undefined keeps the default field for that column.

Use this to unlock the full power of in
Row Forms - including:
- presentation (placeholder, helpText, tooltip)
- validation (required, min, max, pattern, validate)
- data-driven hidden / disabled
- alternative field types (textarea, radio, slider, time,
datetime, color)
- multi-select via multi: true
- bespoke widgets via fieldType: 'custom' + render

Default

undefined

rowFormFieldLabel?

(context:RowFormFieldContext<TData>) => string

Custom form field label provider.

Superseded by (which can return any subset of
properties, including label); kept for
backward compatibility.

Default

undefined

rowFormTitle?

string | ((context:RowFormTitleContext<TData>) => string)

Custom form title provider

Default

'Create New Row'/'Edit Row'

setPrimaryKeyValue?

(context:SetPrimaryKeyValueContext<TData>) => any

Function called when auto-handling 'create' or 'clone' Command Button; returned value should be valid for Primary Key column

Default

undefined

includeColumnInRowForm receives a RowFormColumnContext:

rowFormButtons is a list of AdaptableButton objects. The click handler receives a RowFormContext, which is a create or edit context:

AdaptableButton

A button on a form, alert or toolbar.

label is the text. onClick runs when it is clicked and receives the button and the form or event context. buttonStyle and icon are optional. disabled and hidden are functions that return whether the button is disabled or hidden.

Extends

Identifiable

buttonStyle?

ButtonStyle| ((button:AdaptableButton<CONTEXT_TYPE>, context: CONTEXT_TYPE) =>ButtonStyle)

Style for Button - can be object or function that provides a ButtonStyle object

disabled?

(button:AdaptableButton<CONTEXT_TYPE>, context: CONTEXT_TYPE) => boolean

Function that disables / enables the button based on its evaluation result

hidden?

(button:AdaptableButton<CONTEXT_TYPE>, context: CONTEXT_TYPE) => boolean

Function which sets whether Button is hidden

icon?

AdaptableIcon| ((button:AdaptableButton<CONTEXT_TYPE>, context: CONTEXT_TYPE) =>AdaptableIcon)

Icon for Button - can be object or function that provides a AdaptableIcon object

iconPosition?

'start' | 'end'

Where the icon appears relative to the label

Default

'start'

label?

string | ((button:AdaptableButton<CONTEXT_TYPE>, context: CONTEXT_TYPE) => string)

Label for Button - can be string or function that provides string

onClick?

(button:AdaptableButton<CONTEXT_TYPE>, context: CONTEXT_TYPE) => void

Function to invoke when button is clicked

tooltip?

string | ((button:AdaptableButton<CONTEXT_TYPE>, context: CONTEXT_TYPE) => string)

Tooltip for Button - can be string or function that provides string

buttonStyle is a ButtonStyle:

ButtonStyle

Appearance of an AdapTable button.

variant is 'text', 'outlined' (the default) or 'raised'. tone is the colour: 'neutral' (the default), 'success', 'error', 'warning', 'info', 'accent' or 'none'. className adds a CSS class.

className?

string

CSS Classname to use for the Button

tone?

'success' | 'error' | 'neutral' | 'none' | 'warning' | 'info' | 'accent'

Button's Tone - values: 'success', 'error', 'neutral', 'none', 'warning', 'info', 'accent'

Default

'neutral'

variant?

'text' | 'outlined' | 'raised'

How Button appears - values: 'text', 'outlined', 'raised'

Default

'outlined'

rowFormField receives a RowFormFieldContext and returns an AdaptableFormField:

AdaptableForm

Expand

Defines the form. fields is a list of fields, rows of fields, or field groups. buttons are the form buttons. layout is rows (the default) or inline.

AdaptableForm

Defines a form which appears dynamically; used by Alerts, Export Custom Destinations and Dashboard Custom Toolbars.

buttons?

AdaptableButton<T>[]

Buttons to include in the Form

description?

string

Additional information to appear in the Form

fields?

(AdaptableFormField|AdaptableFormField[] |AdaptableFormFieldGroup)[]

Collection of Dynamic Fields and Field Groups to display.

Items can be:
- a single (rendered on its own row in the
default rows layout, or as one cell in the inline layout),
- an array of (rendered side-by-side on the
same row in the rows layout), or
- an (a labelled section that
visually groups related fields).

layout?

AdaptableFormLayout

How the form's fields are arranged on screen.

- rows (default): each field on its own row, label on the left and
input on the right. Suitable for popups / wizards.
- inline: fields are placed side-by-side on a single horizontal line,
with the label rendered immediately before its input. Designed for
compact contexts such as Dashboard Custom Toolbars where vertical
real-estate is scarce.

Default

'rows'

onSubmit?

(formData: TData, context: T) => void

Optional form-level submit hook.

Fired when the user presses Enter while focus is inside any field
input AND the form is currently valid. The full formData is passed
through, typed as TData if you've supplied a custom shape.

Use this as an ergonomic shortcut to avoid wiring an explicit "Submit"
button - or in addition to one, so power users can press Enter to
commit. If the form is invalid the hook is not invoked.

title?

string

Title to appear in the Form

Each field is an AdaptableFormField:

AdaptableFormField

Defines a Field that appears in an Adaptable Form

clearToDefault?

boolean

For single select fields only. When the user clears the combobox,
whether to restore instead of leaving the field empty.

Defaults to true when defaultValue is set, otherwise false.
Set to false when an empty selection is a distinct state from the default.

defaultValue?

string | boolean | number | Array<string | number | boolean>

Field Default Value - can be of type string, boolean, number, or for
select fields with multi: true an array of those.

For single select fields, this is also the value restored when the user
clears the combobox (unless is false).

disabled?

boolean | ((formData:AdaptableFormData, context:BaseContext) => boolean)

Disable the field's input. Either a boolean or a function evaluated
against the current form data. Disabled fields render but the user
cannot edit them.

fieldType

AdaptableFormFieldType

Field Type - dictates which UI control is rendered

helpText?

string

Inline help text rendered immediately below the field's input. Useful
for short explanations such as "format: YYYY-MM-DD" or "min 3 chars".

hidden?

boolean | ((formData:AdaptableFormData, context:BaseContext) => boolean)

Hide the field. Either a boolean or a function evaluated against the
current form data. Hidden fields are not rendered and are excluded from
validation.

label

string

Label to display in the Field

max?

number | string

Maximum allowed value. For number and slider: the highest accepted
number. For date, time and datetime: the latest allowed value in
ISO format.

maxLength?

number

Maximum length for text and textarea fields.

min?

number | string

Minimum allowed value. For number and slider: the lowest accepted
number. For date, time and datetime: the earliest allowed value
in ISO format (YYYY-MM-DD / HH:mm / YYYY-MM-DDTHH:mm).

minLength?

number

Minimum length for text and textarea fields.

multi?

boolean

For select fields only. When true the field renders as a
multi-select combobox; the field's value is an array of selected
option.values rather than a single value.

Default

false

name

string

Name of the Field

onValueChange?

(value: any, context:BaseContext) => void

Optional callback invoked whenever value of this field changes

options?

AdaptableFormFieldOption[] | ((formData:AdaptableFormData, context:BaseContext) =>AdaptableFormFieldOption[] | Promise<AdaptableFormFieldOption[]>)

Items to populate the select and radio fieldTypes.

Either a static array, or a function that derives the options from the
current form data and Adaptable context. The function form may return
a Promise for asynchronously-loaded options - the form will render the
field with no items until the promise resolves.

pattern?

string

Regular expression that the value of a text field must match.

placeholder?

string

Placeholder text shown inside text, textarea, number, date,
time and datetime inputs when empty. For select fields it is
rendered as the empty-state label when no value is selected.

When omitted on a select field with a , the label of
the matching options entry is used as the empty-state label.

render?

(params:AdaptableFormFieldRenderParams) => React.ReactNode

For custom fields only. Renders an arbitrary React node as the
field's input. Receives the current value, a setValue setter
(controlled), the current form data, the Adaptable context and the
resolved disabled state.

Use this as an escape hatch when none of the built-in fieldTypes
fit - e.g. to render a star-rating widget, a tag editor or any
bespoke control.

required?

boolean

If true the field is treated as required. An empty value ('',
null, undefined, or unchecked checkbox) will produce a validation
error.

rows?

number

For textarea fields: the visible number of text rows.

Default

3

step?

number

Stepping interval for number, slider, time and datetime
fields.

tooltip?

string

Tooltip shown when hovering the field's label.

validate?

(value: any, formData:AdaptableFormData, context:BaseContext) => string | null | undefined

Custom field-level validation. Return an error message string to mark
the field invalid, or null/undefined if the value is valid.

Custom validation runs after built-in checks (required, min,
max, pattern, etc.) - the first failing check wins.

fieldType is an AdaptableFormFieldType:

Value
'text'
'textarea'
'select'
'radio'
'date'
'time'
'datetime'
'number'
'slider'
'color'
'checkbox'
'textOutput'
'custom'

Select and radio options are AdaptableFormFieldOption objects:

AdaptableFormFieldOption

One choice in a select or radio form field.

label

string

Text shown for this choice.

value

any

Value written into the form data when this choice is selected.

layout is an AdaptableFormLayout:

Value
'rows'
'inline'

buttons are AdaptableButton objects:

AdaptableButton

A button on a form, alert or toolbar.

label is the text. onClick runs when it is clicked and receives the button and the form or event context. buttonStyle and icon are optional. disabled and hidden are functions that return whether the button is disabled or hidden.

Extends

Identifiable

buttonStyle?

ButtonStyle| ((button:AdaptableButton<CONTEXT_TYPE>, context: CONTEXT_TYPE) =>ButtonStyle)

Style for Button - can be object or function that provides a ButtonStyle object

disabled?

(button:AdaptableButton<CONTEXT_TYPE>, context: CONTEXT_TYPE) => boolean

Function that disables / enables the button based on its evaluation result

hidden?

(button:AdaptableButton<CONTEXT_TYPE>, context: CONTEXT_TYPE) => boolean

Function which sets whether Button is hidden

icon?

AdaptableIcon| ((button:AdaptableButton<CONTEXT_TYPE>, context: CONTEXT_TYPE) =>AdaptableIcon)

Icon for Button - can be object or function that provides a AdaptableIcon object

iconPosition?

'start' | 'end'

Where the icon appears relative to the label

Default

'start'

label?

string | ((button:AdaptableButton<CONTEXT_TYPE>, context: CONTEXT_TYPE) => string)

Label for Button - can be string or function that provides string

onClick?

(button:AdaptableButton<CONTEXT_TYPE>, context: CONTEXT_TYPE) => void

Function to invoke when button is clicked

tooltip?

string | ((button:AdaptableButton<CONTEXT_TYPE>, context: CONTEXT_TYPE) => string)

Tooltip for Button - can be string or function that provides string

buttonStyle is a ButtonStyle:

ButtonStyle

Appearance of an AdapTable button.

variant is 'text', 'outlined' (the default) or 'raised'. tone is the colour: 'neutral' (the default), 'success', 'error', 'warning', 'info', 'accent' or 'none'. className adds a CSS class.

className?

string

CSS Classname to use for the Button

tone?

'success' | 'error' | 'neutral' | 'none' | 'warning' | 'info' | 'accent'

Button's Tone - values: 'success', 'error', 'neutral', 'none', 'warning', 'info', 'accent'

Default

'neutral'

variant?

'text' | 'outlined' | 'raised'

How Button appears - values: 'text', 'outlined', 'raised'

Default

'outlined'

setPrimaryKeyValue receives a SetPrimaryKeyValueContext:

Row Form Submitted Event

AdapTable fires the Row Form Submitted Event when an edit or create Row Form is submitted (or a delete ActionRowButton is clicked).

This allows developers to handle the form submission themselves, and provide any additional actions, validation or messages to backend services as required.

Hint

AdapTable handles all row manipulation directly, bypassing this event, if autoHandle is set to true in Row Form Options

RowFormSubmittedInfo

The RowFormSubmittedInfo object can be one of 3 types:

CreatedRowInfo

Create (or clone) form was submitted.

The new row is added after this event, from formData. rowNode is not set.

Extends , so adaptableApi is included.

Extends

BaseContext

formData

AdaptableFormData

Values entered in the form. Empty strings are omitted.

rowNode?

IRowNode<TData>

Not set for a created row. The row does not exist yet; it is added from formData after this event.

type

'rowCreated'

Always rowCreated.

adaptableContext

any

Custom application Context provided in AdaptableOptions.adaptableContext

EditedRowInfo

Edit form was submitted.

The row is updated from formData after this event.

Extends , so adaptableApi is included.

Extends

BaseContext

formData

AdaptableFormData

Values entered in the form.

rowNode

IRowNode<TData>

Row being edited. It is still the row in the grid when this event fires.

type

'rowEdited'

Always rowEdited.

adaptableContext

any

Custom application Context provided in AdaptableOptions.adaptableContext

DeletedRowInfo

Delete was confirmed.

The row is deleted after this event. There is no form data.

Extends , so adaptableApi is included.

Extends

BaseContext

rowNode

IRowNode<TData>

Row about to be deleted. It is still in the grid when this event fires.

type

'rowDeleted'

Always rowDeleted.

adaptableContext

any

Custom application Context provided in AdaptableOptions.adaptableContext

Event Subscription

Subscribing to the Event is done the same way as with all Adaptable Events:

api.eventApi.on('RowFormSubmitted', (eventInfo: RowFormSubmittedInfo) => {
    // do something with the info
});

Row Form API

RowFormApi

Row Forms. Opens the form used to create, clone or edit a row, and deletes a row by primary key. Deleting does not open a form.

displayCloneRowForm(primaryKey)
returns

Promise<void>

Opens the Row Form to create a row, prefilled from an existing row.

displayCreateRowForm()
returns

Promise<void>

Open create dialog for a new row

displayDeleteRowForm(primaryKey)
returns

void

Deletes a row and fires the Row Form submitted event. No form is shown.

displayEditRowForm(primaryKey)
returns

Promise<void>

Opens the Row Form to edit the row with this primary key.

PreviousConfiguring Row FormsNextFDC3