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 = $('#myTable').DataTable();

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 = $('#myTable').DataTable();

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' ).

{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 = $('#example').DataTable( {
    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 = $('#example').DataTable( {
    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 = $('#example').DataTable();

$('#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 = $('#example').DataTable();

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 = $('#example').DataTable();

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