Columns Tool Panel
The columns tool panel provides functions for managing the grid's columns.
Below shows a simple example of the columns tool panel. The following can be noted:
- Grid property
toolPanel='columns'which shows only the columns tool panel.
enablePivotset. This means all columns can be dragged to any of the Row Groups, Values and Column sections. Although each column can be dragged to these sections, it does not make sense to do so. For example, it does not make sense to aggregate the country column, but it does make sense to group rows by country.
Things to try:
- Checking / unchecking columns will show / hide the columns.
- Drag a column (e.g. Country) to Row Groups to group rows.
- Drag a column (e.g. Gold) to Values to aggregate.
Reset (refresh) the demo and do the following:
- Click 'Pivot Mode'.
- Drag 'Country' to 'Row Groups'.
- Drag 'Year' to 'Column Labels'.
- Drag 'Gold' to 'Values'.
enablePivotfor pivoting and
enableValuefor aggregation, otherwise you won't be able to drag and drop the columns to the desired sections.
Selecting columns means different things depending on whether the grid is in pivot mode or not as follows:
- Pivot Mode Off: When pivot mode is off, selecting a column toggles the visibility of the column. A selected column is visible and an unselected column is hidden. If you drag a column from the tool panel onto the grid it will make it visible.
- Pivot Mode On: When pivot mode is on, selecting a column will trigger the column to be either aggregated, grouped or pivoted depending on what is allowed for that column.
Column Tool Panel Sections
The column tool panel is split into different sections as follows:
- Pivot Mode Section: Check the 'Pivot Mode' checkbox to turn the grid into Pivot Mode. Uncheck to take the grid out of pivot mode.
- Expand / Collapse All: Toggle to expand or collapse all column groups.
- Columns Section: Display all columns, grouped by column groups, that are available to be displayed in the grid. By default the order of the columns is kept in sync with the order they are shown in the grid, but this behaviour can be disabled.
- Select / Un-select All: Toggle to select or un-select all columns in the columns section.
- Select / Un-Select Column (or Group): Each column can be individually selected. What selection means depends on pivot mode and is explained below*.
Drag Handle: Each column can be dragged either with the mouse or via touch on touch devices.
The column can then be dragged to one of the following:
- Row Groups Section
- Values (Pivot) Section
- Column Labels Section
- Onto the grid (
- Row Groups Section: Columns here will form the grid's Row Grouping.
- Values Section: Columns here will form the grid's Aggregations. The grid calls this function 'Aggregations', however for the UI we follow the Excel naming convention and call it 'Values'.
- Column Labels (Pivot) Section: Columns here will form the grid's Pivot. The grid calls this function 'Pivot', however for the UI we follow the Excel naming convention and call it 'Column Labels'.
It is possible to remove items from the tool panel. Items are suppressed by setting one or more of the
true whenever you are using the agColumnsToolPanel component properties:
suppressRowGroups: to suppress Row Groups section.
suppressValues: to suppress Values section.
suppressPivots: to suppress Column Labels (Pivot) section.
suppressPivotMode: to suppress Pivot Mode section.
suppressColumnFilter: to suppress Column Filter section.
suppressColumnSelectAll: to suppress Select / Un-select all widget.
suppressColumnExpandAll: to suppress Expand / Collapse all widget.
contractColumnSelection: by default, column groups start expanded. Pass true to default to contracted groups.
suppressSyncLayoutWithGrid: to suppress updating the layout of columns in this panel as they are rearranged in the grid.
To remove a particular column from the tool panel, set the column property
This is useful when you have a column working in the background, e.g. a column you want to group by,
but not visible to the user.
It is also possible to show and hide the sections of the Column Tool Panel using the following methods provided
The example below demonstrates the suppress options / methods described above. Note the following:
- The following sections are not present in the tool panel: Row Groups, Values, Column Labels, Pivot Mode, Side Buttons, Column Filter, Select / Un-select All, Expand / Collapse All.
The date column is hidden from the tool panel using:
- Clicking Show Pivot Mode Section invokes
setPivotModeSectionVisible(true)on the column tool panel instance.
- Clicking Show Row Groups Section invokes
showRowGroupsSection(true)on the column tool panel instance.
- Clicking Show Values Section invokes
showValuesSection(true)on the column tool panel instance.
- Clicking Show Pivot Section invokes
showPivotSection(true)on the column tool panel instance.
You can add a CSS class to the columns in the tool panel by specifying
in the column definition as follows:
Column Tool Panel Example
The example below demonstrates the column tool panel using a mixture of items explained above. Note the following:
sportcolumns all have
enablePivot=true. This means you can drag the columns to the group and pivot sections, but you cannot drag them to the values sections.
bronzecolumns all have
enableValue=true. This means you can drag the columns to the values section, but you cannot drag them to the group or pivot sections.
bronzecolumns have style applied using
- The country column uses a
headerValueGetterto give the column a slightly different name dependent on where it appears using the
Read Only Functions
By setting the property
functionsReadOnly=true, the grid will prevent changes to group, pivot or
values through the GUI. This is useful if you want to show the user the group, pivot and values panel,
so they can see which columns are used, but prevent them from making changes to the selection.
Expand / Collapse Column Groups
It is possible to expand and collapse the column groups in the Columns Tool Panel by invoking methods on the Columns Tool Panel Instance. These methods are shown below:
The code snippet below shows how to expand and collapse column groups using the Columns Tool Panel instance:
Notice in the snippet above that it's possible to target individual column groups by supplying
The example below demonstrates these methods in action. Note the following:
- When the grid is initialised,
collapseColumnGroups()is invoked using the
onGridReadycallback to collapse all column groups in the tool panel.
- Clicking Expand All expands all column groups using
- Clicking Collapse All collapses all column groups using
- Clicking Expand Athlete & Competition expands only the 'Athlete' and 'Competition' column groups
- Clicking Collapse Competition collapses only the 'Competition' column group
Custom Column Layout
The order of columns in the Columns Tool Panel is derived from the
columnDefs supplied in the
grid options, and is kept in sync with the grid when columns are moved by default. However custom column layouts
can also be defined by invoking the following method on the Columns Tool Panel Instance:
Notice that the same Column Definitions
that are supplied in the grid options are also passed to
The code snippet below shows how to set custom column layouts using the Columns Tool Panel instance:
Notice from the snippet above that it's possible to define column groups in the tool panel that don't exist in the grid. Also note that columns can be omitted or positioned in a different order but all referenced columns must already exist in the grid.
suppressSyncLayoutWithGridin the tool panel params to prevent users changing the layout when moving columns in the grid.
The example below shows two custom layouts for the Columns Tool Panel. Note the following:
- When the grid is initialised the column layout in the Columns Tool Panel matches what is supplied to the
- Clicking Custom Sort Layout invokes
setColumnLayout(colDefs)with a list of column definitions arranged in ascending order.
- Clicking Custom Group Layout invokes
setColumnLayout(colDefs)with a list of column definitions containing groups that don't appear in the grid.
- Moving columns in the grid won't affect the custom layouts as
Now that we covered the Columns Tool Panel, continue to the next section to learn about the Filters Tool Panel.