Data Table Field

Form Widget

datatable - renders an editable table of records, formatted as a grid. Cell content can be editable directly in the grid, allowing for the management of several rows and columns of information.

data:
    type: datatable
    adding: true
    deleting: true
    columns: []
    searching: false

In order to use this with a model, the field should be defined in the jsonable property or anything that can handle storing as an array.

The following field properties are supported and commonly used.

Property	Description
label	a name when displaying the form field to the user.
default	specifies a default string value, optional.
comment	places a descriptive comment below the field.
adding	allow records to be added to the data table. Default: `true`.
deleting	allow records to be deleted from the data table. Default: `true`.
toolbar	show the toolbar above the data table. Default: `true`.
searching	allow records to be searched via a search box. Default: `false`.
sorting	allow columns to be sorted by clicking the column header. Default: `false`.
reorderRows	allow rows to be manually reordered by dragging the row handle. Default: `false`.
reorderColumns	allow columns to be manually reordered by dragging the column header. Default: `false`.
height	the data table's height, in pixels. If set to `false`, the data table will stretch to fit the content. Default: `false`.
placeholder	a title to display as a placeholder overlay when the table has no rows. When set, the table starts empty (no automatic blank row). Default: `false`.
columns	an array representing the column configuration of the data table. See the Column Configuration section below.

# Column Configuration

The data table widget allows for the specification of columns as an array via the columns configuration variable. Each column should use the field name as a key, and the following configuration variables to set up the field.

Example:

columns:
    name:
        type: string
        title: Name
    price:
        type: numeric
        title: Price
        width: 100px
    country:
        type: dropdown
        title: Country
    state:
        type: dropdown
        title: State
        dependsOn: country
    is_active:
        type: checkbox
        title: Active

Option	Description
type	the input type for this column's cells. See the Column Types section below.
title	defines the column's title.
width	defines the width of the column, in pixels. Example: `100px`.
readOnly	whether this column is read-only. Default: `false`.
ellipsis	truncate overflowing cell content with `...` instead of clipping silently. Requires a fixed `width` to take visible effect. Default: `false`.
validation	an array specifying the validation for the content of the column's cells. See the Column Validation section below.
options	for `dropdown` columns only - specifies the available options as a `{key: label}` map. The grid stores the key in the data and shows the label in the cell. If omitted, options will be loaded via AJAX using the model's `getDataTableOptions` method.
dependsOn	specifies the name of another column that this column depends on. When the parent column value changes, this column's value is cleared and its options are refreshed.
dateFormat	for `date` columns only - the date format. Default: `YYYY-MM-DD`.
timeFormat	for `time` columns only - the time format. Default: `HH:mm`.

# Column Types

The following column types are available.

Type	Description
string	a standard text input (default).
checkbox	a checkbox for boolean values.
numeric	a numeric input that only accepts numbers, including decimals.
dropdown	a strict dropdown select list. The full list is always shown when opened; the user must pick one of the configured options. Options can be provided inline via the `options` property, or loaded dynamically via AJAX.
autocomplete	a text input with autocomplete suggestions. The list filters as the user types and free-text entry is allowed. Options can be provided inline via the `options` property, or loaded dynamically via AJAX.
date	a date picker input.
time	a time picker input.

Dropdown and autocomplete column options can be provided in two ways.

Inline options are defined directly in the column configuration.

columns:
    status:
        type: dropdown
        title: Status
        options:
            draft: Draft
            published: Published
            archived: Archived

AJAX options are loaded dynamically from the model when no inline options are specified. The widget will call one of the following methods on the model.

Method	Description
getFieldNameDataTableOptions	called first, where FieldName is the studly-cased field name (e.g., `getRatesDataTableOptions`). Receives `$column` and `$rowData` parameters.
getDataTableOptions	a generic fallback method. Receives `$fieldName`, `$column` and `$rowData` parameters.

public function getRatesDataTableOptions($column, $rowData)
{
    if ($column === 'country') {
        return ['au' => 'Australia', 'us' => 'United States'];
    }

    if ($column === 'state') {
        // Use $rowData['country'] to return dependent options
        return State::getNamesByCountry($rowData['country']);
    }
}

# Column Dependencies

A column can depend on another column using the dependsOn property. When the parent column value changes, the dependent column value is automatically cleared and its dropdown options are refreshed.

columns:
    country:
        type: dropdown
        title: Country
    state:
        type: dropdown
        title: State
        dependsOn: country

# Column Validation

Column cells can be validated against the below types of validation. Validation should be specified as an array within the column configuration.

columns:
    id:
        type: string
        title: ID
        validation:
            integer:
                message: Please enter a number
            required:
                message: This field is required

Validation	Description
required	validates that data must be entered before saving.
integer	validates that the data is an integer.
float	validates that the data is a floating-point number.
regex	validates the data against a regular expression. A string `pattern` attribute must be provided.

← Color Picker FieldDate Picker Field →

Data Table Field

Data Table Field

# Column Configuration

# Column Types

# Dropdown and Autocomplete Options

# Column Dependencies

# Column Validation

On This Page