Row Forms

Summary

AdapTable provides dynamic Row Forms to help users to safely manage creating, cloning and editing Rows
Row Forms are highly configurable to meet all requirements
Row Form submission can be handled automatically by AdapTable or by listening to Row Form Submitted Event
Action Column Command Buttons can be used to dynamically open Row Forms

Row Forms allow users safely to manage row-related CRUD operations in AdapTable via a popup Form.

There are 3 Row Forms available (each of which is a specialised type of Adaptable Form):

Create - opens a completely empty Form with a UI control for each field in the Data Source
Clone - opens a Form with fields displaying copied values from the existing row
Edit - opens a Form showing the current values of the Row

Note

Row Forms can also be used to safely delete rows
No visible Row Form is rendered (as there is nothing to show) but the Row Form Submitted Event is still fired

Displaying Row Forms

Row Forms can be displayed via 2 methods:

via the Row Form API section of AdapTable API
using Action Column Command Buttons which automatically open the Form when clicked

Row Forms

Fork Fork

This example illustrates the 2 ways to display Row Forms in AdapTable:
- We set an Edit Action Column Command (in Action Column Options) to open the Edit Row Form for each row
- In Dashboard Options we configure an "Add New Row" Custom Button and configure the Button's onClick event to display the Create Row Form using Row Form API
In Row Form Options we set 3 properties:
- set autoHandle to true so that AdapTable will do all the actual row manipulation for us
- set disableInlineEditing to true so that editing is not possible directly in the Grid (i.e. only in the Row Form)
- provide an implementation for the setPrimaryKeyValue function so we can attach a valid primary key to newly created rows
Additionally we configure AdapTable with these Options and Initial State:
- In Edit Options we set the Language and License Columns to display a Select Cell Editor (which also appears in the Row Form)
- In Column Defs we set Github Stars to be readonly - this means that it does not display an input in the Row Form
- In Flashing Cell Initial State we set the Row to flash on any cell change
- We supply ROW_ADDED and ROW_REMOVED Observable Alerts in Alert Initial State

import {
  AdaptableButton,
  AdaptableOptions,
  DashboardButtonContext,
} from '@adaptabletools/adaptable';
import {WebFramework} from './rowData';

export const adaptableOptions: AdaptableOptions<WebFramework> = {
  primaryKey: 'id',
  adaptableId: 'Row Form Action Buttons',
  actionColumnOptions: {
    actionColumns: [
      {
        columnId: 'edit',
        friendlyName: 'Edit',
        actionColumnButton: [
          {
            command: 'edit',
          },
        ],
      },
    ],
  },
  rowFormOptions: {
    autoHandle: true,
    disableInlineEditing: true,
    setPrimaryKeyValue: context => {
      return {
        ...context.rowData,
        id: context.adaptableApi.gridApi.getRowCount() + 1,
      };
    },
  },
  editOptions: {
    showSelectCellEditor: context => {
      return (
        context.column.columnId === 'language' ||
        context.column.columnId === 'license'
      );
    },
  },
  dashboardOptions: {
    customDashboardButtons: [
      {
        label: 'Add New Row',
        onClick: (
          button: AdaptableButton<DashboardButtonContext>,
          context: DashboardButtonContext
        ) => {
          context.adaptableApi.rowFormApi.displayCreateRowForm();
        },
        buttonStyle: {
          variant: 'raised',
          tone: 'info',
        },
      },
    ],
  },
  initialState: {
    StatusBar: {
      StatusBars: [
        {
          Key: 'Center Panel',
          StatusBarPanels: ['Alert'],
        },
      ],
    },
    Alert: {
      AlertDefinitions: [
        {
          Name: 'alert-info-row-added',
          Rule: {
            ObservableExpression: 'ROW_ADDED()',
          },
          MessageType: 'Info',
          Scope: {
            All: true,
          },
          AlertProperties: {
            DisplayNotification: false,
            HighlightRow: {
              BackColor: 'Purple',
              ForeColor: 'White',
            },
          },
        },
        {
          Name: 'alert-warning-row-removed',
          Rule: {
            ObservableExpression: 'ROW_REMOVED()',
          },
          AlertProperties: {
            DisplayNotification: true,
          },
          MessageType: 'Warning',
          MessageText: 'This Row was Deleted',
          Scope: {
            All: true,
          },
        },
      ],
    },
    FlashingCell: {
      FlashingCellDefinitions: [
        {
          Name: 'Flashing_Row_Any_Change',
          Scope: {
            All: true,
          },
          Rule: {
            BooleanExpression: 'ANY_CHANGE()',
          },
          FlashTarget: 'row',
          FlashDuration: 2000,
        },
      ],
    },
    Theme: {CurrentTheme: 'dark'},
    Layout: {
      CurrentLayout: 'Standard Layout',
      Layouts: [
        {
          Name: 'Standard Layout',
          TableColumns: [
            'edit',
            'name',
            'github_stars',
            'update_stars',
            'week_issue_change',
            'update_issues',
            'github_watchers',
            'license',
            'language',
            'created_at',
            'has_wiki',
            'updated_at',
            'pushed_at',
          ],
          AutoSizeColumns: true,
        },
      ],
    },
  },
};

Row Form Contents

Row Forms are vertical and render a Label and relevant UI control for each Column in the AG Grid Row.

The Label displays the Column's Header and the field is an input type associcated with the Column's Data Type:

Column Data Type	Input Type
`text`	Standard input
`number`	Numeric Cell Editor
`date`	Date Picker
`boolean`	Checkbox

Hint

Read-only Columns display the field's value but no input is provided
If a Column has been given a Select Cell Editor, the Form displays it, populated with the Column's distinct values

Configuring Row Forms

Developers can configure Row Forms so they meet precise requirements and use cases. Options include:

configuring the Form's title and description
changing the buttons that appear (by default they are Cancel and Save)
adding custom buttons
providing a Primary Key value (useful when accessing the Add Row Form)
disabling inline editing - so that all editing has to use the Form

Find Out More

See Configuring Row Forms for more details

Handling Row Form Submission

In the demo above, AdapTable performed all the row management automatically.

It has added, edited or cloned the Row when the Form is submitted (and removed it when Delete is clicked).

This is perfectly suitable for most scenarios, and no additional developer / support input is required.

However, some use cases require that rows are only updated or deleted after the form has been submitted.

Note

This allows developers first to get details of the new / updated row and call any relevant backend services
They can only then update the Grid's row data collection - typically via a round trip, rather than directly

For this reason, Adaptable provides the Row Form Submitted Event which is fired:

whenever a Row Form is submitted
when a Delete Action Column Command Button is clicked

Caution

If using this option then set autoHandle to false in Row Form Options
This tells AdapTable not to do any row management itself but to leave it to the developer listening to the Event

autoHandle

Default: true

boolean

AdapTable will automatically hande all Grid changes

If this property is set to false, AdapTable will not directly update AG Grid when a Row Form is submitted.

Instead it will fire the Row Form Submitted Event and the developer will react and do whatever is necessary.

// Don't let AdapTable handle the form submission - do it ourself
const adaptableOptions: AdaptableOptions = {
  rowFormOptions = {
    autoHandle: falee,
  },
};

Row Form Events

Fork Fork

This demo provides a more advanced use case for leveraging Row Forms in Adaptable
In Row Form Options we set 4 properties:
- in actionRowButtons we configure 'clone', 'edit' and 'delete' buttons
- pin 'clone' and 'edit' to left of Grid, and 'delete' to the right
- provide an implementation for the setPrimaryKeyValue function so we can attach a valid primary key to newly created rows
- autoHandle has been left unset, so it defaults to false - meaning we need to handle the Row Form submission
In Dashboard Options we configure a Custom Button which when clicked opens the Create Row form
Most importantly we listen to the Row Form Submitted Event and based on the type of the action we perform the Row manipulation directly
Note: in a more real world case you will likely call a server to do this but the key point is the separation of form submission and row-related action

import {
  AdaptableButton,
  AdaptableOptions,
  AlertMessageContext,
  CustomToolbarButtonContext,
  DashboardButtonContext,
} from '@adaptabletools/adaptable';
import {WebFramework} from './rowData';

export const adaptableOptions: AdaptableOptions<WebFramework> = {
  primaryKey: 'id',
  adaptableId: 'Row Form Event',
  actionColumnOptions: {
    actionColumns: [
      {
        columnId: 'actions',
        friendlyName: 'Actions',
        actionColumnButton: [
          {
            command: 'edit',
          },
          {
            command: 'clone',
          },
        ],
      },
      {
        columnId: 'delete',
        friendlyName: 'Delete',
        actionColumnButton: [
          {
            command: 'delete',
          },
        ],
      },
    ],
  },
  rowFormOptions: {
    autoHandle: false,
    setPrimaryKeyValue: context => {
      return {
        ...context.rowData,
        id: context.adaptableApi.gridApi.getRowCount() + 1,
      };
    },
  },
  dashboardOptions: {
    customDashboardButtons: [
      {
        label: 'Add New Row',
        onClick: (
          button: AdaptableButton<DashboardButtonContext>,
          context: DashboardButtonContext
        ) => {
          context.adaptableApi.rowFormApi.displayCreateRowForm();
        },
        buttonStyle: {
          variant: 'raised',
          tone: 'info',
        },
      },
    ],
    customToolbars: [
      {
        name: 'ButtonToolbar',
        title: 'Buttons',
        toolbarButtons: [
          {
            label: 'Add New Row',
            onClick: (
              button: AdaptableButton<CustomToolbarButtonContext>,
              context: CustomToolbarButtonContext
            ) => {
              context.adaptableApi.rowFormApi.displayCreateRowForm();
            },
            buttonStyle: {
              variant: 'raised',
              tone: 'info',
            },
          },
        ],
      },
    ],
  },
  initialState: {
    Dashboard: {
      Tabs: [
        {
          Name: 'Demo',
          Toolbars: ['ButtonToolbar', 'SystemStatus'],
        },
      ],
    },
    StatusBar: {
      StatusBars: [
        {
          Key: 'Center Panel',
          StatusBarPanels: ['Alert', 'SystemStatus'],
        },
      ],
    },
    Theme: {CurrentTheme: 'dark'},
    Alert: {
      AlertDefinitions: [
        {
          Name: 'alert-info-row-added',
          Rule: {
            ObservableExpression: 'ROW_ADDED()',
          },
          MessageType: 'Info',
          Scope: {
            All: true,
          },
          AlertProperties: {
            DisplayNotification: false,
            HighlightRow: {
              BackColor: 'Purple',
              ForeColor: 'White',
            },
          },
        },
        {
          Name: 'alert-error-row-removed',
          Rule: {
            ObservableExpression: 'ROW_REMOVED()',
          },
          AlertProperties: {
            DisplayNotification: true,
          },
          MessageType: 'Error',
          //  MessageText: 'A Row was Deleted',
          Scope: {
            All: true,
          },
        },
      ],
    },
    FlashingCell: {
      FlashingCellDefinitions: [
        {
          Name: 'Flashing_RowAny_Change',
          Scope: {
            All: true,
          },
          Rule: {
            BooleanExpression: 'ANY_CHANGE()',
          },
          FlashTarget: 'row',
          FlashDuration: 2000,
        },
      ],
    },
    Layout: {
      CurrentLayout: 'Standard Layout',
      Layouts: [
        {
          Name: 'Standard Layout',
          TableColumns: [
            'actions',
            'name',
            'github_stars',
            'update_stars',
            'week_issue_change',
            'update_issues',
            'github_watchers',
            'license',
            'language',
            'created_at',
            'has_wiki',
            'updated_at',
            'pushed_at',
            'delete',
          ],
          ColumnPinning: {
            actions: 'left',
            delete: 'right',
          },
          AutoSizeColumns: true,
        },
      ],
    },
  },
};

FAQ

How can I check data provided in the form before it enters the AG Grid? First, ensure that autoHandle is set to false to prevent automatic entry; then listen to the Row Form Submitted Event to perform any updates yourself

AdapTable Resources

PreviousTechnical Reference NextConfiguring Row Forms

Framework: