button-group-selector

Button group selector (multiple button instances).
Please note - this property requires the Buttons extension for DataTables.

Description

The Buttons extension for DataTables can have multiple instances of the DataTable.Buttons object created and attached to a single DataTable, giving the ability to display different button sets to the end user. For example, you could display identical buttons both above and below the table, or show entirely different button sets in two different locations around the table if your design calls for it.

As a result of this multi-instance behaviour, the buttons() and button() methods provide the option to select buttons from one or more button instances that are attached to a DataTable.

Options

The button group selector can be given in a number of different forms to ensure that the API is flexible for your use case:

• No selector - Select all button instances
• integer - Instance index selector
• string - Instance name selector (set by buttons.name)
• node - div element of the button group (since 3.0.2).
• array - Array containing any combination of the above options

No selector

If no button group selector is given (i.e. undefined), all buttons instances that are available to the tables in the DataTables API context are selected (i.e. an API instance that contains a reference to multiple tables is fully supported).

Disable all buttons on the page:

var allTables = DataTable.tables({api: true});
allTables.buttons().disable();

Enable all buttons using an existing DataTables instance:

table.buttons().enable();

integer

The Button instances are stored in an array that is attached to each DataTable. As a result they can be accessed by index.

Please note that the index of each instance can be changed if the buttons().destroy() method is used to remove a Buttons instance - as such, using the string selector for instance names is often preferable. As new Buttons instances are created, they are always pushed onto the end of the array.

Select the first button instance and disable the second button

var table = new DataTable('#myTable');

table.buttons(0, 1).disable();

string

Each Button instance can be given a name using the buttons.name option to allow it to be individually selected without being required to track instance indexes as you would with an integer selector. Additionally, instance names do not need to be unique, so a single name can refer to multiple Button instances.

In addition to being able to select a single instance with a string, multiple instances can be selected using a comma separator (in much the same way as multiple elements can be selected using a comma in CSS or jQuery selectors).

Table with two button sets; enable button index 0 from the main instance

var table = new DataTable('#myTable', {
    layout: {
        topStart: {
            buttons: {
                name: 'main',
                buttons: [
                    // ...
                ]
            }
        },
        bottomStart: {
            buttons: {
                name: 'commands',
                buttons: [
                    // ...
                ]
            }
        }
    }
});

table.buttons('main', 0).enable();

Using a comma to select two button instances

var table = new DataTable('#myTable', {
    layout: {
        topStart: {
            buttons: {
                name: 'main',
                buttons: [
                    // ...
                ]
            }
        },
        bottomStart: {
            buttons: {
                name: 'commands',
                buttons: [
                    // ...
                ]
            }
        }
    }
});

// Note the use of `null` in the second parameter to act as the button selector
// since `buttons()` with a single parameter will treat the first parameter as
// a button selector. See the `buttons()` documentation for full details.
table.buttons('export, commands', null).containers().appendTo('#panel');

node

A div element can be used to select the button instance group using the container element. This can be useful if working with multiple button sets and you need to select a specific group based on an interaction with a button contained within it.

Please note that this needs to be a plain div, not a jQuery object with the div inside it. Use $().get() if you used jQuery to select the container.

Select a button group from a div

// Note `this` might be a button element itself
let groupEl = this.closest('div.dt-buttons');

table
    .buttons(groupEl, null)
    .containers()
    .appendTo('#panel');

array

As an array, the button group selector can select one or more button instances. This allows you to operate on multiple selected instances with a single API call. If the same instance is selected multiple times using this method, it will automatically be reduced to a single selection.

Same as the comma string selector example above, but using an array of strings

table
    .buttons(['export', 'commands'], null)
    .containers()
    .appendTo('#panel');