button-selector

Button selector.
Please note - this property requires the Buttons extension for DataTables.

Description

The Buttons extension for DataTables provides a flexible API that use the buttons() and button() methods as its basic access points. Using these two methods you can select one or more buttons, from one or more button groups (instances), and then perform an action on those selected buttons. This is designed to match be behaviour of the core DataTables API for row, column and cell selection to provide a consistent API interface for all DataTables interactions.

Options

The following options can be used as a button selector for the buttons() and button() methods:

• No selector - Select all buttons
• null - Alias of No selector
• integer - Select a button based on index
• {\d} or {\d}-{\d} - Button index selector, including sub-buttons (e.g. 2-1)
• {string}:name - Button name selector
• string - jQuery selector (performed on the button nodes)
• node - DOM element selector
• jQuery - DOM element selector
• array - Array containing any combination of the above options

No selector

No selector (i.e. undefined or null) will select all buttons available in a collection, including any buttons in collections. This provides the ability to perform an operation on all buttons in an instance at the same time.

Disable all buttons:

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

table.buttons().disable();

integer

An integer selector will select top level buttons (i.e. those which are always visible - not those in collections) as a simple index counter. Buttons are added and stored by index, thus giving this simple selector option, which can be very useful if you are not dynamically adding and removing buttons (if you are, consider using the button name selector below).

Disable the second button only:

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

table.button(1).disable();

{\d} or {\d}-{\d}

As noted above, integer selectors can select top level buttons only, but it is also possible to select buttons that are in collections using indexes as well. In this case the selector given is {topIndex}-{collectionIndex} where both indexes are 0 based.

# Consider for example the button structure:

buttons: [
    'add',
    'edit',
    'remove',
    {
        text: 'Export',
        buttons: ['csv', 'pdf']
    }
]

The top level Export button can be selected using table.button( 3 ), while the CSV button can be selected using table.button( '3-0' ).

It is worth noting here that there is no limit to the depth of the collections. If there was a structure in place along the lines of collection button > sub-collection > sub-sub-collection then to select the first button in the sub-sub-collection the selector would take the form {\d}-{\d}-{\d}, or with real numbers, 0-0-0.

{string}:name

Each button can be given a name using the buttons.buttons.name option to allow it to be individually selected without being require to track button indexes as you would with the index selector options above. Additionally, buttons names do not need to be unique, so a single name can refer to multiple buttons.

In addition to being able to select a single button with a string, multiple buttons 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).

Disable a button using a name selector

var table = new DataTable('#myTable', {
    buttons: [{ extend: 'csv', name: 'csv' }]
});

table.buttons('csv:name').disable();

string

If a string is given as a selector, it will initially be checked to see if it matches one of the selector options above - specifically an index or name selector. If not, the button nodes are collected into a jQuery instance and the selector given run as a filter. This is particularly useful for selecting based on class name (settable using buttons.buttons.className and other common DOM properties.

Disable a button using a class name selector

var table = new DataTable('#myTable', {
    buttons: [{ extend: 'csv', className: 'csv' }]
});

table.buttons('.csv').disable();

node

Select a button using a DOM element. This can be useful if you are using DOM events with the buttons and only have a node to reference it.

Enable a button on mouse enter

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

$('#content').on('mouseenter', 'a.dt-button', function (e) {
    table.button(this).enable();
});

jQuery

Very similar to the above node type (since a jQuery object is an array-like list of DOM nodes), a jQuery instance can be given as a button selector. This can be useful if you have selected the nodes that you want to perform an operation on.

Disable buttons which have the class name csv

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

table.buttons($('a.dt-button.csv')).disable();

array

Any combination of the above options can be given as selector together, providing a method to select multiple buttons, or to mix selector types, by simply providing the selector options you want in an array. Buttons will automatically remove any duplicates to ensure that whatever actions are requested via the API occur only once for each button.

Disable button index 0 and all buttons with the class csv

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

table.buttons([0, '.csv']).disable();