Button configuration

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!

Customising buttons

The [index](initialisation guide) shows how buttons can be used by referencing the button type with a simple string matching the button's name:

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

This 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:

$('#myTable').DataTable( {
    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 are 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:

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