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 PartialColumnDefinition
id
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.