vdl-datagrid

Render a table of related array entities. The array entities for each column are defined as child <vdl-datagrid-column> elements. The common index sets are automatically detected. The table will emit the following events on user interaction:

• selection-changed - Triggered whenever the selection is changed, e.g. when user creates new selection. This event is triggered on the vdl-datagrid element. Event handler also receives context of the selection, which includes selection cell list, active cell and selection type.
• selection-removed - Triggered whenever the selection is destroyed, e.g. when sorting and filtering. This event is triggered on the vdl-datagrid element.
since 5.2

Example

<vdl-var name="selectedRowData" value="=[]"></vdl-var>
<vdl-action-group name="handleSelectionChanged">
    <vdl-action-set-var var="selectedRowData" value="=value ? value.activeCell.rowData : []"></vdl-action-set-var>
</vdl-action-group>

<vdl-action-group name="handleSelectionRemoved">
    <vdl-action-set-var var="selectedRowData" value="=[]"></vdl-action-set-var>
</vdl-action-group>

<vdl-datagrid vdl-event="'selection-changed': actions.handleSelectionChanged, 'selection-removed': actions.handleSelectionRemoved">
    <vdl-datagrid-column entity="MY_ARRAY_1"></vdl-datagrid-column>
    <vdl-datagrid-column entity="MY_ARRAY_2"></vdl-datagrid-column>
</vdl-datagrid>

Attributes

add-remove-row	Setting this will show the add-remove row buttons at the bottom of the grid. Set to "true" to prompt for index selection on row add. Set to addrow-autoinc will switch the behaviour to allow new index values to be created, incrementing from the highest value in the set(s).This attribute can not be set when "data" attribute is being used.	since 5.2
always-show-selection	Whether to display selection on inactive grids. Set to true to keep selection on a grid when it becomes inactive.	since 5.2
cell-render	A custom cell render function or expression that is applied to all cells in the datagrid. This affects the rendered output of the cell only, sorting and filtering are unaffected. The cell-render function should return either the original data unchanged, some new data to display in the cell or a new HTML element to insert into the cell. In addition to returning the original or modified cell data it can also modify the HTML cellElement that is passed in. If a cell-render function is provided on vdl-datagrid and a child vdl-datagrid-column has a render function, then the vdl-datagrid-column render function will take precedence. Variable Type Description data (string|boolean|number) The value of the cell being rendered. Its data type will match that of the array elements in this column. type string The type call data requested - this will currently always be display. rowData Array.<(string|boolean|number)> The values from each cell in the current row. The order of the row data reflects the underlying order of the array indices rather than the display order. columnDefinition ColumnDefinition The ColumnDefinition object representing the configuration of the cell's column. See the ColumnDefinition object describe in the column-definition attribute. cellElement HTMLElement The cell HTML element. This can be modified or appended to, affecting the display of the cell.	since 5.3	requires expression
class	Space-separated list of the classes of the element.	since 5.2
column-definition	Specify how columns are defined. This attribute can only be used in combination with the "data" attribute. Allowed values are: column-definition="auto" - Generates columns from the data (default) column-definition="labels" - Uses the "label" and "value" properties on an object. Data will be reduced to one row. column-definition="=[{ field: "name" }, { field: "age" }]" - An array of objects defining the column properties. When using column properties, you should supply a column definition object for each column you require and each object must have a property named 'field'. The value of the field property must reference a property on the data. Below is an example showing how columns, and even individual cells can be made editable. This also shows how dropdown options can be supplied with labels: data = [ { name: "John Doe", gender: "MALE", age: 30, isStaff: false }, { name: "Jane Doe", gender: "FEMALE", age: 25, isStaff: true } ] Callback to determine if a cell is editable: /* ColumnDefinition { field: string, title: string, editable: boolean | ((details: VdlDatagridCellDetails) => boolean), parentColumn: false | ColumnDefinition, } */ /* RowDefinition { rowData: (string|number|boolean|null|undefined)[] | Record , treeParentRow: false | RowDefinition, } */ /* VdlDatagridCellDetails { cellValue: (string|number|boolean|null|undefined), columnDefinition: ColumnDefinition, rowData: (string|number|boolean|null|undefined)[] | Record , treeParentRow: false | RowDefinition, tableData: (string|number|boolean|null|undefined)[][], } */ function isNameEditable(cellDetails: VdlDatagridCellDetails) { /* Make use of the cellDetails to determine if a cell is editable... */ return true; } Callback to construct gender options: function constructGenderOptions(cellValue: (string|boolean|number), rowData: {[key: string]: (string|boolean|number)}) { return [ { key: "OTHER", value: "Prefer not to say" }, { key: "MALE", value: "Male" }, { key: "FEMALE", value: "Female" } ]; } column-definition = [ { field: "name", title: "Full Name", editable: isNameEditable }, { field: "gender", editable: true, editorOptions: constructGenderOptions }, { field: "age", headerSortStartingDir: "desc", editable: true }, { field: "isStaff" } ] Object passed to the cell-event handler: /* ColumnDefinition { field: string, title: string, editable: boolean | ((details: VdlDatagridCellDetails) => boolean), parentColumn: false | ColumnDefinition, } */ /* RowDefinition { rowData: (string|number|boolean|null|undefined)[] | Record , treeParentRow: false | RowDefinition, } */ /* VdlDatagridCellEditDetails { cellValue: (string|number|boolean|null|undefined), cellInitialValue: (string|number|boolean|null|undefined), cellOldValue: (string|number|boolean|null|undefined), columnDefinition: ColumnDefinition, rowData: (string|number|boolean|null|undefined)[] | Record , treeParentRow: false | RowDefinition, tableData: (string|number|boolean|null|undefined)[][] } */ Handling the cell-edit event: <script> function handler(cellEditDetails: VdlDatagridCellEditDetails) { /* cell-edit event handler code */ } </script> <vdl-datagrid vdl-event="cell-edit: handler" [...] > Callback to validate a cell: /* VdlDatagridCellDetails { cellValue: (string|number|boolean|null|undefined), columnDefinition: ColumnDefinition, rowData: (string|number|boolean|null|undefined)[] | Record , treeParentRow: false | RowDefinition, tableData: (string|number|boolean|null|undefined)[][], } */ function isValidBool(cellDetails: VdlDatagridCellDetails) { return true; } function isValidObject(cellDetails: VdlDatagridCellDetails) { return { isValid: true, errorMessage: "wrong value", allowSave:false }; } Column definition objects accept the following configuration properties: Variable Type Description field string The name of the objects property which holds the columns value. title string The displayed title of the column. width number | string The width of the column, either as a number in pixels, for example 200, or a percentage string such as: '50%'. headerSortStartingDir "asc" | "desc" The header sort starting direction. cssClass string Space seperated class names. editable boolean | (details: VdlDatagridCellDetails) => boolean Optional boolean, or callback which determines if an individual cell can be edited. The callback is invoked when a cell is clicked and is provided with an VdlDatagridCellDetails object to help a decision be made. dataType "string" | "number" | "boolean" Optionally specify the data type for the column. If not provided, type will automatically be inferred from the first row of data. editorOptions Array.<(string|boolean|number)> | Object.<string, string> | Array.<{key: (string|boolean|number), value: string}> Optional editor options array, the presence of which will cause a dropdown of the provided options to appear instead of the usual string, number or checkbox editor. editorValidate (details: VdlDatagridCellDetails) => boolean | InsightValidationResult Optional callback which validate the values in the column's cells. The callback is provided with a VdlDatagridCellDetails.	since 5.2	accepts expression
column-filter	Set this to true to enable the column filters. This will show a header row with filter inputs for each column.	since 5.2
data	Use this attribute to pass data directly to vdl-datagrid. Supported formats are; array of primitives: [1,2,3], Array of objects: [{... prop: 1}], or an array of arrays: [...["a",1]]	since 5.2	requires expression
export-filename	The name of the file exported from the table. A file extension will be assigned.	since 5.2	accepts expression
freeze-columns	The number of columns to freeze in the table starting from the left hand column. Works best when vdl-datagrid is in a fixed width container	since 5.2
height	Grid height, When page-mode is set to scrolling you can set the height of the grid to something other than the default.	since 5.2
id	Specify an element id for the grid. Useful if you later want to target the grid using a selector. If not given then an id will be generated.	since 5.2
page-mode	By default the grid will show all rows in scrolling mode. Set this attribute to paged to enable grid pagination.	since 5.2
page-size	The number of rows to show per-page in paged mode.	since 5.2
row-filter	Expression to be used for filtering the rows of a <vdl-datagrid>. This must be an expression and should resolve to either a function or a boolean value. If a function it will be executed when grid updates. The function will have the following signature (rowData, indices) and should return a boolean. Variable Type Description rowData Array.<(string|boolean|number)> The values from each cell in the current row. The order of the row data reflects the underlying order of the array indices rather than the display order. indices Array.<(string|boolean|number)> Data for the index columns of the row	since 5.2	requires expression
save-state	Set this to false to disable grid state saving. By default grid state is stored in the user's browser session so that user settings (e.g. page, sorting and search) are preserved if grid data is reloaded.	since 5.2
scenario	The default scenario to use for fetching data in the grid. This can be overridden per column but the default will be used when a column does not specify a particular scenario and the index sets will be fetched from the default scenario. This attribute will not affect the scenario variable in any render expression on the datagrid columns.This attribute can not be set when "data" attribute is being used.	since 5.2	accepts expression
show-export	Set this to true to display an export to CSV button.	since 5.2	accepts expression
width	Set the grid to a fixed width, in pixels. Accepts an integer value. If set to the string custom then the grid width is calculated by adding up all the widths of the columns in the grid. If a column doesn't have a width specified then it is given a default value of 100px.	since 5.2