# Configuring Row Forms

Canonical page: https://www.adaptabletools.com/docs/handbook-row-form-configuring

- Row Forms are types of AdapTable Form and are highly configurable

## AdapTable Form

The Row Form displayed by AdapTable is a specialised [Adaptable Form](https://www.adaptabletools.com/docs/ui-tutorial-configuring-adaptable-forms/index.md) which renders one row for each data element in the Data Source

AdapTable will provide the appropriate edit input for the Column's Data Type (if the cell / column is editable)

### Included Columns

By default AdapTable will include every Column in the Grid in the Row Form.

This can be configured by using the `includeColumnInRowForm` property in [Row Form Options](https://www.adaptabletools.com/docs/technical-reference-row-form/index.md) which determines inclusion a case by case basis.

### `includeColumnInRowForm`

Whether a Column should be included in the Row Form

Optional callback. When omitted, every column is included. Return `false` to hide a column from the form.

It receives [`RowFormColumnContext`](https://www.adaptabletools.com/docs/reference/rowformcolumncontext.md):

| Property | Type | Description |
| --- | --- | --- |
| [adaptableColumn](https://www.adaptabletools.com/docs/reference/rowformcolumncontext.md#adaptablecolumn) | [`AdaptableColumn`](https://www.adaptabletools.com/docs/reference/adaptablecolumn.md) | Column to be displayed |
| [rowFormType](https://www.adaptabletools.com/docs/reference/rowformcolumncontext.md#rowformtype) | [`RowFormType`](https://www.adaptabletools.com/docs/reference/rowformtype.md) | Type of Row Form |
| [adaptableContext](https://www.adaptabletools.com/docs/reference/rowformcolumncontext.md#adaptablecontext) | `any` | Custom application Context provided in `AdaptableOptions.adaptableContext` |

```ts {3}
// Exclude any Actions Columns or those with an Id of 'id' from the Row Form
rowFormOptions: {
  includeColumnInRowForm: (rowFormColumnContext: RowFormColumnContext) => {
    const column: AdaptableColumn = rowFormColumnContext.adaptableColumn;
    return column.columnTypes?.includes('actionColumn') || column.columnId == 'id' ? false : true;
  },
}
```

### Form Title

### `rowFormTitle`

Title shown at the top of the Row Form

  `string | ((context: RowFormTitleContext) => string)`

A fixed string, or a function that receives a [`RowFormTitleContext`](https://www.adaptabletools.com/docs/reference/rowformtitlecontext.md) (Create vs Edit, and the Row being edited or cloned).

```ts {3-5}
rowFormOptions: {
  rowFormTitle: (context) => {
    return `Editing ${context.rowNode?.data?.name}`;
  },
},
```

### Form Description

### `rowFormDescription`

Description shown below the Row Form Title

  `string | ((context: RowFormTitleContext) => string)`

Same context as `rowFormTitle`. Omit it to show no description.

```ts {3-5}
rowFormOptions: {
  rowFormDescription: (context) => {
    return `Row is at index ${context.rowNode?.rowIndex}`;
  },
},
```

### Default Buttons

By default AdapTable will display 2 Buttons at the bottom of the Form:

- **Save** - automatically saves the Row (for `Edit` buttons) or creates a new Row (for `Create` & `Clone` buttons)

- AdapTable will only automatically perform these actions if `autoHandle` is set to _true_ in [Row Form Options](https://www.adaptabletools.com/docs/technical-reference-row-form/index.md)
  - If _false_, developers need to handle, as required, the [Row Form Submitted Event](https://www.adaptabletools.com/docs/technical-reference-row-form/index.md) which AdapTable fires

- **Cancel** - closes the Form with no changes made

### Custom Buttons

### `rowFormButtons`

Replace the default Save and Cancel Buttons

  `AdaptableButton[]`

Each Button is an [Adaptable Button](https://www.adaptabletools.com/docs/ui-tutorial-displaying-adaptable-buttons/index.md) (label, style, visibility, `onClick`). The Form closes as soon as any Button is clicked.

- If you replace the default Save Button, persist changes in the Button's `onClick`
- AdapTable will **not** call `onRowFormSubmit`, nor fire the [Row Form Submitted Event](https://www.adaptabletools.com/docs/technical-reference-row-form/index.md)

```ts {3-16}
rowFormOptions: {
  rowFormButtons: [
    {
      label: 'Cancel',
      buttonStyle: { variant: 'raised', tone: 'none' },
      onClick: (_button, context) => {
        context.adaptableApi.alertApi.showAlertInfo('Action Row', 'No changes were made');
      },
    },
    {
      label: (_button, context) => `Save ${context.rowNode?.data?.name}`,
      buttonStyle: { variant: 'raised', tone: 'info' },
      onClick: (_button, context) => {
        context.adaptableApi.gridApi.updateGridData([context.formData]);
      },
    },
  ],
},
```

**Example: Row Form Config**

Configuring a Row Form

- This demo illustrates how to configure the Edit Row Form. In `rowFormOptions` we provide many properties including:
  - `includeColumnInRowForm` - we exclude the `Actions` Column (that displays the `Add` Button) and the `Id` Column from the displayed form
  - `rowFormTitle` - we provide a custom Title based on the Row being edited
  - `rowFormDescription` - we provide a custom Description that appears below the Form Title
  - `rowFormFieldLabel` - we change the text of the Label for `Language` Column
  - `rowFormButtons` - we provide 2 Custom Buttons that display at the end of the Form and have custom Styles;
    - `Cancel` - displays an Alert when clicked
    - `Save` - has a custom Label which references the Row, and updates the Grid when clicked (button is disabled where Issue Change is negative)
  - Note: we set `autoHandle` to false since we are providing the functionality to update the Grid

Demo project (Vanilla); the files without a marker are shown below:

```text
src/
  adaptableOptions.ts
  agGridModules.ts     [template]
  columnDefs.ts
  gridOptions.ts       [template]
  index.ts             [template]
  onAdaptableReady.ts  [template]
  rowData.ts           [template]
  styles.css           [template]
index.html             [template]
package.json           [template]
tsconfig.json          [template]
```

Files marked `[template]` are the same in every demo; see the [demo template](https://www.adaptabletools.com/llms/demo-template.md#vanilla).

**`src/adaptableOptions.ts`**

```ts
import {
  AdaptableColumn,
  AdaptableOptions,
  CreateRowFormContext,
  EditRowFormContext,
  RowFormColumnContext,
} from '@adaptabletools/adaptable';
import {WebFramework} from './rowData';

export const adaptableOptions: AdaptableOptions<WebFramework> = {
  primaryKey: 'id',
  adaptableId: 'Row Forms Config',
  actionColumnOptions: {
    actionColumns: [
      {
        columnId: 'action',
        friendlyName: 'Actions',
        controls: [{type: 'command', command: 'edit'}],
      },
    ],
  },
  rowFormOptions: {
    autoHandle: false,
    includeColumnInRowForm: (rowFormColumnContext: RowFormColumnContext) => {
      const column: AdaptableColumn = rowFormColumnContext.adaptableColumn;
      return column.columnTypes?.includes('actionColumn') ||
        column.columnId == 'id'
        ? false
        : true;
    },
    rowFormTitle: context => {
      return `Editing ${context.rowNode?.data?.name}`;
    },
    rowFormDescription: context => {
      return `Row is at index ${context.rowNode?.rowIndex}`;
    },
    rowFormFieldLabel: context => {
      return context.column.friendlyName === 'Language'
        ? `${context.column.friendlyName} (please select)`
        : `${context.column.friendlyName}`;
    },
    rowFormButtons: [
      {
        label: 'Cancel',
        buttonStyle: {
          variant: 'raised',
          tone: 'none',
        },
        onClick: (
          button,
          context: CreateRowFormContext | EditRowFormContext
        ) => {
          context.adaptableApi.alertApi.showAlertInfo(
            'Action Row',
            'No changes were made'
          );
        },
      },
      {
        label: (button, context: CreateRowFormContext | EditRowFormContext) => {
          const editRowFormContext: EditRowFormContext =
            context as EditRowFormContext;
          return `Save ${editRowFormContext.rowNode?.data.name}`;
        },
        buttonStyle: {
          variant: 'raised',
          tone: 'info',
        },
        onClick: (
          button,
          context: CreateRowFormContext | EditRowFormContext
        ) => {
          context.adaptableApi.gridApi.updateGridData([context.formData]);
        },
        disabled: (button, context) => {
          return context.formData['week_issue_change'] < 0;
        },
      },
    ],
  },
  editOptions: {
    showSelectCellEditor: context => {
      return context.column.columnId === 'language';
    },
  },
  initialState: {
    Theme: {CurrentTheme: 'dark'},
    Layout: {
      CurrentLayout: 'Standard Layout',
      Layouts: [
        {
          Name: 'Standard Layout',
          TableColumns: [
            'action',
            'name',
            'github_stars',
            'update_stars',
            'week_issue_change',
            'update_issues',
            'github_watchers',
            'license',
            'language',
            'created_at',
            'has_wiki',
            'updated_at',
            'pushed_at',
            'open_issues_count',
            'closed_issues_count',
            'open_pr_count',
            'closed_pr_count',
          ],
          AutoSizeColumns: true,
        },
      ],
    },
  },
};
```

**`src/columnDefs.ts`**

```ts
import {ColDef} from 'ag-grid-enterprise';

export const columnDefs: ColDef[] = [
  {
    field: 'id',
    cellDataType: 'number',
    hide: true,
    editable: false,
  },
  {
    field: 'name',
    cellDataType: 'text',
    sortable: true,
    editable: false,
  },
  {
    field: 'language',
    cellDataType: 'text',
    enablePivot: true,
    enableRowGroup: true,
  },
  {
    field: 'github_stars',
    headerName: 'GitHub Stars',
    cellDataType: 'number',
    enableValue: true,
  },
  {
    field: 'license',
    cellDataType: 'text',
    editable: false,
  },
  {
    field: 'created_at',
    headerName: 'Created',
    cellDataType: 'date',
  },
  {
    field: 'has_wiki',
    headerName: 'Has Wiki',
    cellDataType: 'boolean',
    enablePivot: true,
    enableRowGroup: true,
  },
  {
    field: 'updated_at',
    headerName: 'Updated',
    cellDataType: 'date',
  },
  {
    field: 'pushed_at',
    headerName: 'Pushed',
    cellDataType: 'date',
  },
  {
    field: 'github_watchers',
    headerName: 'GitHub Watchers',
    cellDataType: 'number',
    enableValue: true,
  },
  {
    field: 'open_issues_count',
    headerName: 'Open Issues',
    cellDataType: 'number',
    enableValue: true,
  },
  {
    field: 'closed_issues_count',
    headerName: 'Closed Issues',
    cellDataType: 'number',
    enableValue: true,
  },
  {
    field: 'open_pr_count',
    headerName: 'Open PRs',
    cellDataType: 'number',
    enableValue: true,
  },
  {
    field: 'closed_pr_count',
    headerName: 'Closed PRs',
    cellDataType: 'number',
    enableValue: true,
  },
  {field: 'has_projects', headerName: 'Has Projects', cellDataType: 'boolean'},
  {field: 'has_pages', headerName: 'Has Pages', cellDataType: 'boolean'},
  {
    field: 'week_issue_change',
    headerName: 'Issue Change',
    cellDataType: 'number',
    enableValue: true,
  },
];
```

## Disabling In-line Editing

AdapTable can be configured so that the **only** editing allowed is through the Row Form, i.e. not directly inline in the cell itself.

This is achieved by setting the `disableInlineEditing` property in [Row Form Options](https://www.adaptabletools.com/docs/technical-reference-row-form/index.md) to _true_.

### `disableInlineEditing`

Prevents Inline Editing (so that Row Forms can be used)

A common requirement is to enable editing only through the Row Form - and not directly inline.

This is achieved by setting this property to _true_.

```ts {4}
// Prevent direct cell edits in the Grid (i.e. only via Row Form)
const adaptableOptions: AdaptableOptions = {
  rowFormOptions: {
    disableInlineEditing: true,
  },
};
```

Even Columns which have been directly set to be editable in Grid Options will be readonly (for inline editing)

## Setting Primary Key Value

Every AdapTable instance requires a [Primary Key](https://www.adaptabletools.com/docs/getting-started-primary-key/index.md) column to be provided.

This is a column which guarantees to hold unique values.

This means that when adding a new row to the Data Set via a Row Form - either `Create` or `Clone` - it is possible that the run-time user might not know what value to provide to the Primary Key Column.

For this reason, AdapTable provides the `setPrimaryKeyValue` property in Row Form Options which can return a Primary Key value for the row automatically.

### `setPrimaryKeyValue`

Returns a Primary Key value when using Create Row Form

Provides a Primary Key values for rows being added via the `Create` Row Form.

This is a useful function as often the run-time user will not know what value to provide.

The function receives [`SetPrimaryKeyValueContext`](https://www.adaptabletools.com/docs/reference/setprimarykeyvaluecontext.md) and returns the value to be used as the primary key.

The context simply contains the row being added:

| Property | Type | Description |
| --- | --- | --- |
| [rowData](https://www.adaptabletools.com/docs/reference/setprimarykeyvaluecontext.md#rowdata) | `TData` | Data in the row being created or cloned |
| [adaptableContext](https://www.adaptabletools.com/docs/reference/setprimarykeyvaluecontext.md#adaptablecontext) | `any` | Custom application Context provided in `AdaptableOptions.adaptableContext` |

```ts {3}
const adaptableOptions: AdaptableOptions = {
  rowFormOptions: {
    setPrimaryKeyValue: (context: SetPrimaryKeyValueContext) => {
      return {
        ...context.rowData,
        id: context.adaptableApi.gridApi.getRowCount() + 1,
      };
    },
  },
};
```
