Buttons

A common UI paradigm to use with interactive tables is to present buttons that will trigger some action - that may be to alter the table's state, modify the data in the table, gather the data from the table or even to activate some external process. Showing such buttons is an interface that end users are comfortable with, making them feel at home with the table.

The Buttons library for DataTables provides a framework with common options and API that can be used with DataTables, but is also very extensible, recognising that you will likely want to use buttons which perform an action unique to your applications.

Buttons has four sets of plug-ins that are part of the core software - they are not built into the core, but rather than be included as and when you need them, selecting only the software you require. Other extensions such as Editor and Select also provide buttons for use with this library, with actions unique to their own behaviours. This ensures a consistent interface for the interactions performed with your tables.

Download

The easiest way to get and use Buttons is to use the DataTables download builder where you can select the software that you wish to use on your page and have a single Javascript and CSS file created and hosted for you.

Alternatively, the individual files can be included on your page, a release package downloaded or the source control repository cloned on GitHub.

Initialisation

The Buttons library can be initialised and used in a number of different ways:

• As part of the DataTables constructor with the layout option and buttons feature (or for backward compatibility a top level buttons object).
• A new constructor
• Legacy dom option

It is important to note that multiple instances of Buttons can be created for use with a DataTable. This can be particularly useful if you want to present different sets of buttons to the end user - for example above and below the table.

In DataTables

As part of the DataTables constructor the buttons feature can be used with the layout option to place the Buttons (or multiple instances of Buttons) around the table. The example below shows the configuration of a specific set of buttons. See the examples for how to configure the buttons further.

new DataTable('#myTable', {
    layout: {
        topStart: {
            buttons: [
                'copy', 'excel', 'pdf'
            ]
        }
    }
});

Note that for backwards compatibility, it is also possible to define the buttons configuration through the top level buttons option (this method is limited to a single set of buttons per table), which looks like this:

new DataTable('#myTable', {
    buttons: [
        'copy', 'excel', 'pdf'
    ],
    layout: {
        topStart: 'buttons'
    }
});

Constructor

Button instances can also be created using the Javascript new keyword with the DataTable.Buttons function. This function takes two parameters:

1. The DataTable instance to apply the buttons to
2. The button options (this is the same as the options available for the buttons option.

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

new DataTable.Buttons(table, {
    buttons: [
        'copy', 'excel', 'pdf'
    ]
});

This method of initialisation is particularly useful for cases when you wish to present the buttons somewhere other than immediately around the table. Use the buttons().container() method to get the button's container element so you can insert into the DOM wherever you require:

table.buttons().container()
    .appendTo( '#toolbar' );

Legacy dom option

If you are working with DataTables 1.x code, you might see the dom parameter being used, which uses an ASCII string to define where to put the table control elements. The letter for Buttons is B - e.g.:

$('#myTable').DataTable({
    dom: 'Bftip',
    buttons: [
        'copy', 'excel', 'pdf'
    ]
});

This will still work with DataTables 2 (but not as the same time as layout - they are mutually exclusive), but it is recommended that you update to use layout.

Features

Buttons provides the following features: