colVis

Since: ColumnControl 1.0.0

A list of toggle buttons to control column visibility.
Please note - this property requires the ColumnControl extension for DataTables.

Description

This content type provides a list of buttons that can be used to control the visibility of columns in the table. It is very similar to the colVis type for DataTable's Buttons extension, but in this case, the control is in the table header/footer cells, rather than placed in the table control layout.

This content type is relatively unusual in ColumnControl in that it can affect other columns, rather than the actions being limited to the host column alone.

The toggle state of the buttons will reflect the initial visibility state of each column, as set by columns.visible. The text shown as the name for the button will be the same as that retrieved by column().title(), and the order of the buttons matches the order of the columns in the table. The order is updated if ColReorder is used to modify the order.

Examples showing the use of this content type are available on the DataTables website.

Display

It is expected that this content type will be used inside a dropdown. Placing it at the top level can result in a very confusing UI. ColumnControl, however, does not restrict you from doing that if you require it.

It is worth noting that if you are using a dropdown specifically for only this content type, you will be better served to use colVisDropdown as it sets a suitable icon and text for the dropdown button.

Options

This button can have the following options set in its configuration object to customise its actions and display, in addition to those options which are available for all buttons (e.g. buttons.buttons.text):

`columns`

Type: column-selector
Default: ``

Column selector to pick which columns should be shown in the list.

`search`

Type: boolean
Default: false

The toggle list can show a search box which allows the list of column names to be searched. This can be useful if you have a large number of columns in the table.

`select`

Type: boolean
Default: false

This option will show "Select all" and "Select none" links at the top of the toggle list, allowing quick interaction for the end user.

`title`

Type: string
Default: ``

Text that is shown at the top of the toggle list. This can be information text to tell the end user what the list is for - e.g. "Change column visibility", etc.

Examples

List columns in a dropdown, allowing their visibility to be toggled:

new DataTable('#example', {
    columnControl: [
        'order',
        ['colVis']
    ],
    ordering: {
        indicators: false,
        handler: false
    }
});

Allow only selected columns to be toggled:

new DataTable('#example', {
    columnControl: [
        'order',
        [
            {
                extend: 'colVis',
                columns: ':not(.always-visible)'
            }
        ]
    ]
    ordering: {
        indicators: false,
        handler: false
    }
});