Configuration
Initialisation and configuration of ColumnControl is performed through the columnControl
initialisation option for DataTables. The configuration given here is applied to all columns in the table. There is also columns.columnControl
which works in exactly the same way, but is applied to specific columns (typically through columnDefs.targets
).
To keep your development process easy and code clean columnControl
can take multiple forms as described below.
Content array
The most simple form for configuring ColumnControl is with an array of strings, where the strings represent the content types to display. Furthermore, an inner array can also be used to create a dropdown - e.g.:
new DataTable('#myTable', {
columnControl: ['order', ['orderAsc', 'orderDesc', 'search']]
});
The reference documentation contains a full list of all content types that are built into ColumnControl, and extensive documentation for each one.
Content types can also be represented by an object as well as a string. The basic structure for a content type object is one with an extend
property that matches the content type name. For example, the following is exactly equivalent to the string based configuration above:
new DataTable('#myTable', {
columnControl: [
{ extend: 'order' },
[{ extend: 'orderAsc' }, { extend: 'orderDesc' }, { extend: 'search' }]
]
});
While more verbose, the object form has the advantage that it provides the ability to set configuration options for each content type. Each content type can provide options for its own configuration, e.g. colVis
has a columns
option that can be used to control which columns can have their visibility toggled by the control. The following shows this being used to create a dropdown control allowing all but the first column to have their visibility toggled:
new DataTable('#myTable', {
columnControl: [
[
{
extend: 'colVis',
columns: ':gt(0)'
}
]
]
});
Refer to the reference documentation for each content type for the options that each one provides.
Expanded form
One of the key abilities of ColumnControl is that it can at content to any row in the table header or footer. In fact, it can actually add content to multiple rows. This is done by telling ColumnControl which row you want it to insert content by using it in an object form and using the columnControl.target
option.
The above form of defining the content to show at the top level is shorthand for the columnControl.content
option. The following is functionally identical, but now gives us access to the target
property:
new DataTable('#myTable', {
columnControl: {
target: 0,
content: ['order', ['orderAsc', 'orderDesc', 'search']]
}
});
The target
value can be one of:
thead:\d
- add the content to the table header, the row index defined by a digit (\d
) - e.g.thead:0
for the first row in the header,thead:2
for the third, etc.tfoot:\d
- as above, but inserting content into the table footer.tfoot
- add the content to the first row in the table footer (i.e. a shorthand fortfoot:0
).
It is important to note that if you specify a row which doesn't exist in the table's HTML, ColumnControl will create the row for you automatically, with the correct number of cells for the number of columns in the table (one per column).
Multiple targets
To insert content into multiple rows in the header / footer, this expanded form can also be used as an array. As an example, the following will show an order
button on the first row and a search
in the table's footer:
new DataTable('#example', {
columnControl: [
{
target: 0,
content: ['order']
},
{
target: 'tfoot',
content: ['search']
}
]
});
ColumnControl will differentiate between a "content array" and an array of "expanded forms" by looking for the target
property on the objects it contains.