Usage

The DataTables extensions provide a number of pre-configured buttons which can be used without any customisation. However, you will inevitably wish to alter the buttons' properties to suit your needs - this can be as simple as changing the displayed text, or as complex as providing a custom callback to modify the layout of a PDF document!

Initialising Buttons

The Buttons extension adds a "feature" to DataTables - that is, a component which can be used in the layout option of DataTables, allowing you to place buttons around the table as your UI requires. In this way, you can also have multiple independent sets of buttons, with different button types shown.

In its basic form, Buttons is initialised with an array of strings, matching the names of the buttons you wish to show, inside the layout target location. In the following, topStart (i.e. top left for left-to-right languages) is used, and a list of buttons is provided.

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

It is easy to see from this how you can customise the buttons to be shown.

Legacy option

Prior to the introduction of the layout option in DataTables, layout was done with the dom option (which continues to be supported in DataTables 2 and 3). That option didn't provide the ability to configure the components it was displaying, so a top-level buttons option was used. This also continues to be supported and can be used for the configuration of Buttons:

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

In this case, the feature from topStart: 'buttons' will use the configuration from the buttons option. The disadvantage of this is that you can only specify a single configuration. The initial method above is preferred.

Customising buttons

When you use a string to define a button (as above), it tells Buttons simply to use the default options for the button of that name. The string is expanded automatically by Buttons to a button definition object - this object contains the individual properties of the buttons.

We can also pass an object in that extends from the available buttons:

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

Notice that we still have three buttons as before, but the first button, originally represented by a string, has been replaced by an object. The buttons.buttons.extend option is used to tell Buttons what button type to use as a base of the button (this is optional if you wish to define a custom button!).

In the case above the buttons.buttons.text option has been used to set the text for the button. This option is common to all buttons - there are a number of common options (see below), and each button type also has the ability to define options which are specific to itself - the reference documentation for each button should be referred to for the full options available.

Extending upon this concept - using { extend: 'excel' } (i.e. no other parameters) is functionality equivalent as simply using 'excel'!

Built in options

The Buttons library provides a number of core options that are common to all button types. The most commonly used of these are:

• buttons.buttons.action - Action to take when the button is activated
• buttons.buttons.className - Set the class name for the button
• buttons.buttons.extend - Define which button type the button should be based on
• buttons.buttons.key - Define an activation key for a button
• buttons.buttons.text - The text to show in the button

The full list of options is available in the initialisation options reference.

Key access

One of the more interesting built-in options for buttons is the buttons.buttons.key option. This provides the ability to assign a custom keystroke to trigger the button's action. For example, you could set it up so that a key press of e (with or without any modifier keys) would trigger editing of the selected rows.

Keystrokes are only acted upon when there is no other focused element on the page. So if, for example, you did bind a button to the e key, and the user were entering text into the DataTables search box, it would not trigger when they press the e key!

The buttons.buttons.key option can be given as either a string (simple character binding), or as an object which allows modifier keys to also be required.

For example, consider the following:

new DataTable('#myTable', {
    layout: {
        topStart: {
            buttons: [
                {
                    extend: 'copy',
                    text: '<u>C</u>opy',
                    key: {
                        key: 'c',
                        altKey: true
                    }
                }
            ]
        }
    }
});

In this case the copy action is triggered when the alt key + c key combination is pressed. Note also that the text property has been used to highlight to the end user that the c key will do something.