Column Interface
Your application interacts with columns through the grid's column interface. The column interface is defined as all the public facing parts of the columns that your application interacts with. This section list all the column methods, properties, events etc. for interacting with the grid's columns.
The column interface is the combination of the following items:
-
Column Properties:
Columns are configured through column definitions. A column definition contains the column properties
e.g.
colDef.pinned='left'
. -
Column API:
The column API is similar to the grid API, the difference is that the column API provides methods
relevant to columns e.g.
columnApi.setColumnVisible('country',false)
. -
Column Object:
Each column in the grid is represented by a Column object, which in turn has a reference to the column
definition provided by the application. The Column wraps the Column Definition.
The Column object has attributes, methods and events for interacting
with the specific column e.g.
column.isVisible()
.
Column Definitions
Each column in the grid is defined using a column definition. Columns are positioned in the grid according to the order the ColDef's are specified in the grid options. The following example shows a simple grid with 3 columns defined:
See Column Properties for a list of all properties that can be applied to a column.
If you want the columns to be grouped, then you include them as groups like the following:
Groups are explained in more detail in the section Column Groups.
Custom Column Types
In addition to the above, the grid provides additional ways to help simplify and avoid duplication of column definitions. This is done through the following:
- defaultColDef: contains column properties all columns will inherit.
- defaultColGroupDef: contains column group properties all column groups will inherit.
- columnTypes: specific column types containing properties that column definitions can inherit.
The following code snippet shows these three properties configures:
When the grid creates a column it starts with the default column, then adds in anything from the column type, then finally adds in items from the column definition.
For example, the following is an outline of the steps used when creating 'Col C' shown above:
The following examples demonstrates this configuration.
Provided Column Types
Numeric Columns
The grid provides a handy shortcut for formatting numeric columns.
Setting the column definition type to numericColumn
aligns the column header and contents to the right,
which makes the scanning of the data easier for the user.
Column ID's
Each column generated by the grid is given a unique ID. Parts of the Grid API use Column ID's (column identifiers).
If you are
using the API and the columns ID's are a little complex (eg what if two columns have the same field
,
or what if you are using valueGetter
instead of field
) then it is useful to understand
how columns ID's are decided.
If the user provides colId
in the column definition, then this is used, otherwise the field
is used. If both coldId
and field
then colId
gets preference. If neither
colId
or field
then numeric is provided. Then finally the ID ensured to be unique by
appending '_[n]' where n is the first positive number that allows uniqueness.
In the example below, columns are set up to demonstrate the different ways ID's are generated. Open the example in a new tab and observe the output in the dev console. Note the following:
-
Col 1 and Col 2 both use
colId
. The grid appends '_1' to Col 2 to make the ID unique. -
Col 3 and Col 4 both use
field
. The grid appends '_1' to Col 4 to make the ID unique. -
Col 5 and Col 6 have neither
colId
orfield
so the grid generates columns.
Saving and Restoring Column State
It is possible to save and subsequently restore the column state via the Column API. Examples of state include column visibility, width, row groups and values.
This is primarily achieved using the following methods:
columnApi.getColumnState()
: Returns the state of a particular column.columnApi.setColumnState(state)
: To set the state of a particular column.
The column state used by the above methods is an array of objects that mimic the colDef's which can be converted to and from JSON. An example is shown below:
The values have the following meaning:
colId
: The ID of the column.aggFunc
: If this column is a value column, this field specifies the aggregation function. If the column is not a value column, this field is null.hide
: True if the column is hidden, otherwise false.rowGroupIndex
: The index of the row group. If the column is not grouped, this field is null. If multiple columns are used to group, this index provides the order of the grouping.width
: The width of the column. If the column was resized, this reflects the new value.pinned
: The pinned state of the column. Can be either'left'
or'right'
columnApi.setColumnState(state)
, and also
columnApi.resetColumnState()
, use: gridOptions.suppressSetColumnStateEvents = true
.
Column API Example
The example below shows using the grid's Column API.
Column Changes
It is possible to add and remove columns after the grid is created. This is done by
either calling api.setColumnDefs()
or setting the bound property
columnDefs
.
When new columns are set, the grid will compare with current columns and work out which columns are old (to be removed), new (new columns created) or kept (columns that remain will keep their state including position, filter and sort).
Comparison of column definitions is done on 1) object reference comparison and 2)
column ID eg colDef.colId
. If either the object reference matches, or
the column ID matches, then the grid treats the columns as the same column. For example
if the grid has a column with ID 'country' and the user sets new columns, one of which
also has ID of 'country', then the old country column is kept in place of the new one
keeping it's internal state such as width, position, sort and filter.
The example below demonstrates changing columns. Select the checkboxes for the columns to display and hit Apply. Note the following:
- Column Width: If you change the width of a column (eg Year) and then add or remove other columns (eg remove Age) then the width of Year remains unchanged.
- Column Sort: If you sort the data by a column (eg Year) and then add or remove other columns (eg remove Age) then the sort remains unchanged. Conversely if you remove a column with a sort (eg remove Year while also sorting by Year) then the sort order is removed.
- Column Filter: If you filter the data by a column (eg Year) and then add or remove other columns (eg remove Year) then the filter remains unchanged. Conversely if you remove a column with a filter (eg remove Year while also filtering on Year) then the filter is removed.
- Row Group & Pivot: If you row group or pivot the data by a column (eg Year) and then add or remove other columns (eg remove Age) then the row group or pivot remains unchanged. Conversely if you remove a column with a row group or pivot (eg remove Year while also row grouping or pivoting on Year) then the row group or pivot is removed.
- The Columns Tool Panel and Filters Tool Panel updates with the new columns. The order of columns in both tool panels will always match the order of the columns supplied in the column definitions. To observe this, hit the Reverse button which does same as Apply but reverses the order of the columns first. This will result in the columns appearing in the tool panels in reverse order.
Delta Columns
By default when new columns are loaded into the grid, the following properties are not used:
- Column Order
- Aggregation Function
(colDef.aggFunc)
- Width (
colDef.width
) - Pivot (
colDef.pivot or colDef.pivotIndex
) - Row Group (
colDef.rowGroup or colDef.rowGroupIndex
) - Pinned (
colDef.pinned
)
For example - suppose the application user rearranges the order of the columns. Then if the application sets new column definitions for the purposes of adding one extra column into the grid, then it would be a bad user experience to reset the order of all the columns.
Likewise if the user changes an aggregation function, or the width of a column, or whether a column was pinned, all of these changes the user does should not get undone because the application decided to update the column definitions.
To change this behaviour and have column attributes above (order, width, row group etc) take effect
each time the application updates the grid columns, then set gridOption.deltaColumnMode=true
.
The responsibility is then on your application to make sure the provided column definitions are in sync
with what is in the grid if you don't want undesired visible changes - eg if the user changes the width
of a column, the application should listen to the grid event columnWidthChanged
and update
the applications column definition with the new width - otherwise the width will reset back to the default
after the application updates the column definitions into the grid.
The example below demonstrates Delta Column Mode. Note the following:
-
Grid property
deltaColumnMode
is set to true. - Each button sets a different list of columns into the grid. Because each column definition provides an ID, the grid knows the instance of the column is to be kept. This means any active sorting or filtering associated with the column will be kept between column changes.
-
Each button changes the column definitions in a way that would be otherwise ignored
if
deltaColumnMode
was not set. The changes are as follows:- Normal: Columns are set as normal. This is the default. It will make the other button actions easier to understand if Normal is pressed before pushing the other buttons.
- Reverse Order: Columns are provided in reverse order.
- Widths: Columns are provided with different widths.
-
Visibility: Columns are provided with
colDef.hidden=true
. The columns will still be in the grid and listed in the tool panel, however they will not be visible. - Grouping: Rows will be grouped by Sport.
- No Resize or Sort: Clicking the columns will not sort and it will not be possible to resize the column via dragging it's edge.
- Pinned: Columns will be pinned to the left and right.