vdlx-datagrid reference

vdlx-datagrid provides a way to bind model entities to a table element within VDL views. It offers much improved performance for larger data sets compared with vdl-table.

Download the appropriate release version of vdx-datagrid from the GitHub webiste. The first two digits of the vdlx-datagrid release version number must match the version of VDL you are using to develop. For example, if you are developing for VDL 4.6, download vdlx-datagrid version 4.6.x.

Unzip the vdlx-datagrid.zip release bundle into your Xpress Workbench client_resources folder. You can then add vdlx-datagrid in your views via the code editor-vdlx-datagrid is not available in the VDL Designer palette:

<vdl-include src="vdlx-datagrid/vdlx-datagrid.vdl"></vdl-include>

vdlx-datagrid is mostly a drop-in replacement for vdl-table and can generally be used by renaming code examples:

<vdlx-datagrid id="basic-example-1">
    <vdlx-datagrid-column set="SupportLevels">Support L.</vdlx-datagrid-column>
    <vdlx-datagrid-column entity="SupportCosts"></vdlx-datagrid-column>
    <vdlx-datagrid-column entity="ServiceLevelAgreements"></vdlx-datagrid-column>
</vdlx-datagrid>

vdlx-datagrid

Render a table of related array entities. The array entities for each column are defined as child <vdlx-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 vdlx-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 vdlx-datagrid element.

See the JavaScript API Documentation, Table section for more details on the events.

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>

<vdlx-datagrid vdl-event="'selection-changed':handleSelectionChanged, 'selection-removed':handleSelectionRemoved">
    <vdlx-datagrid-column entity="MY_ARRAY_1"></vdlx-datagrid-column>
    <vdlx-datagrid-column entity="MY_ARRAY_2"></vdlx-datagrid-column>
</vdlx-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.

always-show-selection

Whether to display selection on inactive grids. Set to true to keep selection on a grid when it becomes inactive.

Default value: "false"

class

Space-separated list of the classes of the element.

column-definition

Specify how columns are defined, allowed values: "auto", "labels", or an object defining column properties [{field:"key", title="Key"}...].

"auto" (default) will generate columns from the data.
"labels" will use the "label" property on an object as the column header, and the "value" property as the cell value. Data will be reduced to one row.

When using column properties, you should supply aa 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.
For example: column-definition="=[{field:"name", title:"Full Name", field:"tel", title:"Phone Number"}] data="=[{name="John Doe", tel:"1234"}...]".
Other recommended properties: title, width, cssClass (space separated class names), headerSortStartingDir (asc/desc),
This attribute can not be set when "data" attribute is being used.

Default value: "auto"

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.

data

Use this attribute to pass data directly to vdlx-datagrid. Supported formats are; array of primitives: [1,2,3], Array of objects: [{... prop: 1}], or an array of arrays: [...["a",1]]

accepts expression

export-filename

The name of the file exported from the table. A file extension will be assigned.

Default value: "data"

accepts expression

freeze-columns

The number of columns to freeze in the table starting from the left hand column. Works best when vdlx-datagrid is in a fixed width container

height

Grid height, When page-mode is set to scrolling you can set the height of the grid to something other than the default.

Default value: "600"

accepts expression

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.

page-mode

By default the grid will show all rows in scrolling mode. Set this attribute to paged to enable grid pagination.

page-size

The number of rows to show per-page in paged mode.

Default value: "50"

accepts expression

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.

accepts expression

Variable	Description
rowData	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. `Array.<(string\|boolean\|number)>`
indices	Data for the index columns of the row `Array.<(string\|boolean\|number)>`

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.

Default value: "true"

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.

accepts expression

show-export

Set this to true to display an export to CSV button.

Default value: "false"

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.

vdlx-datagrid-column

Required ancestor element

<vdlx-datagrid>

Attributes

bottom-calc

Specify a built-in calculation, one of avg, max, min, sum, concat or count to show that calculated value, alternatively provide a custom function, as a dynamic expression.

accepts expression

Variable	Description
values	Array of column values `(string\|boolean\|number)`
data	All table data `string`
calcParams	params passed from the column definition object `Array.<(string\|boolean\|number)>`

class

CSS classes to add to the table column cells. You can provide multiple classes separated by spaces.

accepts expression

disable-set-sorting

When applied to an index column, this will prevent set sorting from being applied to the column. Default table sorting will be used instead. It will also exclude this column from the default list of sorted columns. This option is provided to reduce the sorting overhead where performance is being affected. Set the value to "true" to disable set sorting for this datagrid column.

Default value: "false"

type: boolean

editable

Whether the cells within this column are editable. The column will automatically switch to read-only whilst the bound scenario is reserved for execution.

type: boolean

accepts expression

editor-checked-value

The value to set the cell data to if input type is checkbox and it is checked.

editor-options

An expression that results in one of the follow to be used as the select options: an array of values, an object of property to value or an array of objects containing key and value properties. This will automatically set the editor-type to be select.

accepts expression

Variable	Description
value	The value of the cell. Its data type will match that of the array elements in this column. `(string\|boolean\|number)`
rowData	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. `Array.<(string\|boolean\|number)>`
Returns
	An array of values, an object of property to value or an array of objects containing key and value properties. `Array.<>\|Object.<string, string>\|Array.<{key: string, value: }>`

editor-options-include-empty

Allow array elements to be removed using the select input. Setting this to true will add a blank item to the top of the select list.

Default value: "false"

editor-options-set

Name of a set entity to use for select options. This will display labels if a labels entity is defined against this set. This will automatically set the editor-type to be select.

editor-type

The editor type to use, in edit mode, for cells in this column. If not specified then it will be autodetected based on entity type. Possible values: checkbox, select, text.

editor-unchecked-value

The value to set the cell data to if input type is checkbox and it is not checked.

entity

Name of the array entity to show in this column. Throws an error if the entity doesn't exist or is not an array or set type.

filter-by-formatted

Use formatted values for filtering. This defaults to false unless the entity has a label in which case the default is true.

type: boolean

format

Specify a number formatting string. Only applicable to array elements of type integer, real, decision variable and constraint. The formatting syntax is explained in the Xpress Insight Developer Guide.

heading

A custom header for this column, will default to be the entity alias. Alternatively, you can set the title as the text contents of the <vdlx-datagrid-column> element.

accepts expression

render

Reference to a custom cell renderer. Overrides any default entity rendering. This will be used to generate the cell value for rendering, filtering and sorting. It must be an expression and resolves as a function, this function should return a string. Render callback may only reference entities through VDL expression that are not present on the table. If it is necessary to use entities data from other columns, then rowData array must be used in the render callback.

accepts expression

Variable	Description
data	The value of the cell being rendered. Its data type will match that of the array elements in this column.The cell value will be HTML escaped to avoid XSS security issues. `(string\|boolean\|number)`
type	The type call data requested - this will be <em>filter</em>, <em>display</em> or <em>sort</em>. `string`
rowData	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. `Array.<(string\|boolean\|number)>`

scenario

The scenario id/index for this column. Not allowed on index column (when specifying a set entity). This attribute will not affect the scenario variable in the render expression.

accepts expression

set

Name of the set entity to show in this column. Throws an error if the entity doesn't exist or is not a set type.

set-position

Index (zero-based) of occurrence of that index set in the index tuple for the array. Defaults to next available position.

sort-by-formatted

Use formatted values for sorting. This is always set to enabled for calculated columns.

Default value: "false"

type: boolean

sort-direction

The direction the column data should be sorted in.

Default value: "asc"

sort-order

Sets the column to be sorted by default, provide a number from 0. With multiple sorted columns the number provides the order in which sorting should be applied to the columns, so the highest number will result in the column having sorting applied last.

type: number

width

The width, in pixels, to set the column.

accepts expression

vdlx-datagrid-index-filter

This tag can be used at either the vdlx-datagrid level or the vdlx-datagrid-column level.

When used at the vdlx-datagrid-column level, it can only accept a single value and will filter the specified index set for the array entity associated with that column. Note that it will not reduce the amount of data fetched from the server when used at the column level.

When used at the vdlx-datagrid level, it can accept one or more values and will filter the specified index set for all arrays in the table. This will request the filtered data from the server, so reduce the amount of data that is fetched from the server and processed by the table, resulting in improved performance. The filtered index set will still be shown as a column in the table, so you will need to use vdl-visible="=false" to hide this if necessary.

Example

<!-- Example of an index filter on a column -->
<vdlx-datagrid>
    <vdlx-datagrid-column entity="FactoryDemand" heading="='Factory Demand (' + vars.filterValue + ')'">
        <vdlx-datagrid-index-filter set="Factories" value="=vars.filterValue"></vdlx-datagrid-index-filter>
    </vdlx-datagrid-column>
</vdlx-datagrid>

<!-- Example of a server-side index filter on an entire table -->
<vdlx-datagrid vdl-if="=vars.multiFilter.length > 0">
    <vdlx-datagrid-index-filter set="MonthsOfYear" value="=vars.multiFilter"></vdlx-datagrid-index-filter>
    <vdlx-datagrid-column entity="FactorySupply"></vdlx-datagrid-column>
</vdlx-datagrid>

Attributes

set	Name of the set entity to filter out of the indices for the column. required
value	Single value to fix the indices to. If used at the `vdlx-datagrid` level, the value will accept multiple values in the form of an array or a vdl-var required accepts expression
set-position	Index (zero-based) of occurrence of that index set in the index tuple for the array. Default value: "0"

vdlx-datagrid-validate

Add a validation rule to a <vdlx-datagrid-column> element. You can declare multiple <vdlx-datagrid-validate> rules within a <vdlx-datagrid-column> and they will all be applied. Each rule can specify whether the field is allowed to save data if that rule fails (this is soft validation). The pass attribute defines the expression that is called every time the field or autocolumn changes. The expression is automatically given the variables: entityName, value, indices and rowData (if used with vdlx-datagrid). entityName is the name of the entity bound to the field, value is the current value being input, indices is an array of indices if the field is bound to an array element and rowData is an array containing indices and values of the current row.

Required parent element

<vdlx-datagrid-column>

Example

<vdlx-datagrid>
  <vdlx-datagrid-column entity="FactoryDemand">
    <vdlx-datagrid-validate pass="=value >= scenario.entities.SupportLevel.value"
                  allow-save="=scenario.entities.CanSave.value">
      FactoryDemand should be greater than or equal to SupportLevel
    </vdlx-datagrid-validate>
  </vdlx-datagrid-column>
</vdlx-datagrid>

Attributes

pass

Expression to used for validating the value of a <vdl-field> or <vdl-table-column>. This must be an expression and should resolve to either a function or a boolean value. If a function it will be executed on each change to the vdl-field or vdl-table-column and also when a save is attempted. The function will have the following signature (entityName, value, key) and should return a boolean.

required accepts expression

Variable	Description
entityName	Name of the entity being validated `string`
value	Value to be validated. The data type depends on the user input binding `(string\|boolean\|number)`
indices	Optional array indices provided when binding to an array element `?Array.<(string\|boolean\|number)>`
rowData	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. `?Array.<(string\|boolean\|number)>`

allow-save

If set to true this will allow a field to be saved even though it is marked as invalid.

Default value: "false"

accepts expression

Element contents

Text content only

Text content of the element is used as the message to display when attempting to save and validation fails