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

Name	Type	Default
`action`
Show the collection
`align` Since: 1.6.0		dt-container
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` Since: 1.1.2		false
Automatically close the collection when a button inside the collection is activated.
`background`		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`		dt-button-background
Class name to add to the background element if it is enabled.
`buttons`		[]
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`		buttons-collection
The button's class name. See `buttons.buttons.className` for details.
`collectionLayout`
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` 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`		false
When `true`, the dropdown collection always drops up. When `false`, the collection drops down or up depending on the available overflow.
`fade`		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` 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`		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`		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` Since: 2.2.2		container
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`		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']
				}
			]
		}
	}
});