Configuring the Columns

Description

The DataGrid presents the data in rows and aligned in columns. A column is not a visual element by itself, it is rather an abstraction that aligns cells in a vertical manner. Very often, the cells of a given column share various characteristics. In the DataGrid, these characteristics are regrouped in what is call a ColumnDefinition.

In the DataGrid, many functions accept PartialColumnDefinition instead of ColumnDefinition. A PartialColumnDefinition is mostly the same thing as a ColumnDefinition except that its properties are optional. The only required property on PartialColumnDefinition is id. Any optional property that is missing on a PartialColumnDefinition may be interpreted differently depending on the function being called. For example, a function that adds a column definition to the DataGrid may fulfill any missing property with a default value, while a function that updates a column’s definition may decide that any missing property means that there is no update to do on these properties.

A ColumnDefinition has a type property that specifies the type of data the column’s target field has. The type of a column can be string, boolean, integer, number, date, time or dateTime.

Initialization

A ColumnDefinition can be assigned to the DataGrid through its options (PartialDataGridStartupOptions) as soon as it is initialized. On a PartialDataGridStartupOptions, it is possible to assign one or more PartialColumnDefinition to the columnDefinitions property.

Example

const options = { columnDefinitions: [{id: "value", field: "value", title: "Value", type:”string”}] };

const dataGrid = new Xceed.DataGrid("container", options);

Update

Once the DataGrid is initialized, it is possible to add, remove, move or modify one or more columns dynamically at runtime with one of the functions on the DataGrid. The setOptions and the setColumnDefinitions functions can do most of the actions in batch with a single call. The setOptions function takes a DataGridOptions while the setColumnDefinitions function takes an array of PartialColumnDefinition. The getColumnDefinitions function returns the current list of ColumnDefinition.

The setOptions and the setColumnDefinitions functions do not need to obtain the original ColumnDefinition to do updates. It is the value of the PartialColumnDefinitionid property that allows the DataGrid to re-trace the corresponding ColumnDefinition. To sum it up, from a list of PartialColumnDefinition, the DataGrid can determine the desired changes. If an id is not already present, then it is an insert; if an id is missing from the new list of PartialColumnDefinition, then it is a deletion; otherwise it is an update to an existing column. The order of the PartialColumnDefinition received will indicate the new display order.

Examples

Adding

const colDefs = dataGrid.getColumnDefinitions();

colDefs.push({id: "colId", field: "prop", title: "Prop"});

dataGrid.setColumnDefinitions(colDefs);

Removing

const colDefs = dataGrid.getColumnDefinitions();

colDefs.splice(0, 1);

dataGrid.setColumnDefinitions(colDefs);

Updating

const colDefs = dataGrid.getColumnDefinitions();

colDefs[0].title = "new title";

dataGrid.setColumnDefinitions(colDefs);

Reordering

This example assumes that there are 2 columns, first and last.

const colDefs = [{id: "last"}, {id: "first"}];

dataGrid.setColumnDefinitions(colDefs);

The DataGrid exposes more functions to manage ColumnDefinition more granularly such as addColumnDefinitions, insertColumnDefinitions, updateColumnDefinitions, removeColumnDefinitions, getColumnDefinitionById, etc.