collection

Since: Buttons 1.0.0

A button which triggers a drop down with another set of buttons.
Please note - this property requires the Buttons extension for DataTables.

Description

The collection button type is integral to Buttons as it provides the ability to show one or more "sub-buttons" in a drop down that is displayed when the button is activated. This provides a method of collecting like buttons and displaying them in a space efficient manner for the end user.

The key aspect of this button type is the buttons option, which is an array of the buttons that you want to show in the drop down. The buttons defined here are exactly the same as any other button and can also be accessed via the API and manipulated as such.

Options

This button can have the following options set in its configuration object to customise its actions and display, in addition to those options which are available for all buttons (e.g. buttons.buttons.text):

`action`

Type: function
Default: Unset

Show the collection

`align`

Type: string
Default: dt-container
Since: 1.6.0

The horizontal alignment of the popover relative to the button. It may be one of:

button-left - Align to the left of the activation button.
button-right - Align to the right of the activation button.
container - Align to the left and right of the DataTables' container (since 2.2.2)
dt-container - Align to the left of the DataTables' container and span its full width - deprecated, use container and the span option.

`autoClose`

Type: integer
Default: false
Since: 1.1.2

Automatically close the collection when a button inside the collection is activated.

`background`

Type: boolean
Default: true

Show (true) a background element, which can be styled using CSS to visually highlight the collection by fading out the rest of the page, or not (false).

`backgroundClassName`

Type: string
Default: dt-button-background

Class name to add to the background element if it is enabled.

`buttons`

Type: array
Default: []

The buttons to show in the collection. The elements in this array follow the same rules as the buttons.buttons array - i.e. it can contain strings, objects and functions that describe buttons. As of Buttons 1.1 this can also include buttons that trigger other collections to be shown (i.e. nested collections).

`className`

Type: string
Default: buttons-collection

The button's class name. See buttons.buttons.className for details.

`collectionLayout`

Type: string
Default: ``

Layout options for the buttons shown in the collection. This is a string which can have:

Position:
dropdown - Drop the collection down from the host button
fixed - Display the collection centred over the window
Column layout:
columns - Automatic column display (based on screen size), upto maximum of four columns
two-column - Display in two columns
three-column - Display in three columns
four-column - Display in four columns

The column layout can be use with the default absolute positioning of the drop down, or with the fixed position layout option. To use fixed positioning and multi-column layout, simply space separate the options - e.g. fixed columns.

`collectionTitle`

Type: string
Default: ``
Since: 1.5.4

Deprecated in Favour of popoverTitle - will be removed version 3.0.0

A text string to show at the top of a collection. This can be useful for multi-level collections to ensure the end user knows what the current menu refers to.

`dropup`

Type: boolean
Default: false

When true, the dropdown collection always drops up. When false, the collection drops down or up depending on the available overflow.

`fade`

Type: integer
Default: 400

Animation speed that the collection is faded in and out of the display. This is an integer value that represents the animation duration in milliseconds. For no animation use the value 0.

`popoverTitle`

Type: string
Default: ``
Since: 2.0.0

A text string to show at the top of a collection. This can be useful for multi-level collections to ensure the end user knows what the current menu refers to.

`postfixButtons`

Type: array
Default: undefined

A list of buttons that should be postfixed to an existing collection (see the buttons option). This provides the ability for a button that extends a collection to add items to the end of the collection's sub-buttons. Like the buttons option the elements in this array follow the same rules as the buttons.buttons array.

`prefixButtons`

Type: array
Default: undefined

A list of buttons that should be prefixed to an existing collection (see the buttons option). This provides the ability for a button that extends a collection to add items to the start of the collection's sub-buttons. Like the buttons option the elements in this array follow the same rules as the buttons.buttons array.

`span`

Type: string
Default: container
Since: 2.2.2

Match the width of the dropdown to the datatables container.:

default - width of the collection dropdown is defined by the CSS.
container - Span its full width of the DataTables' container (good for large content areas).

`text`

Type: string
Default: Collection

The button's display text. The text can be configured using this option (see buttons.buttons.text) or the buttons.print option of the DataTables language object.

Example

DataTables initialisation: Create an export collection:

new DataTable('#myTable', {
	layout: {
		topStart: {
			buttons: [
				{
					extend: 'collection',
					text: 'Export',
					buttons: ['csv', 'excel', 'pdf']
				}
			]
		}
	}
});