print

Since: Buttons 1.0.0

Button show a printable view of the table's data.
Please note - this property requires the Buttons extension for DataTables.

Description

The print view button will take a copy of the data displayed in a table (based on the selector options given in the exportOptions parameter) and construct a new, temporary, table that is shown in a new window. The browser's print command is then automatically invoked (although this can be disabled - see the autoPrint option below) and finally the window closed when the print action has been completed or cancelled by the end user.

The constructed table does not retain the full information from the original table (table row and cell classes are not copied across for example), but the stylesheets from the original document are copied to the print document so the basic styling of the table can be retained.

Customisation of the printed view is available through the title and message options for simple description strings and through the customize option for complete control over the generated document (allowing, for example images to be added, etc).

Please note that the print button will set the decodeEntities option of buttons.exportData() to false to prevent XSS attacks.

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 print view

`autoPrint`

Type: boolean
Default: true

Indicate if the browser's window.print() method should be called when the print view page has been displayed:

true - window.print() will be called and then immediately upon completion the window.close() function will be closed to hide the print view document.
false - No action is taken once the print view document has been created. The window is not automatically closed.

`className`

Type: string
Default: buttons-print

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

`customScripts`

Type: array
Default: null

An array of URLs pointing to scripts that should be included in the print view document. This can be useful for including additional libraries that are required for the document to be displayed correctly. Function that is executed when the window that contains the print view document has been displayed.

`customize`

Type: function
Default: null

Function that is executed when the window that contains the print view document has been displayed.

As of Buttons 1.5.2 this function is passed three parameters:

object window - The window object for the new window. As such the document body can be accessed using window.document.body and manipulated using jQuery / DOM methods as any element can be.
object - The button configuration object
DataTable.Api - A DataTables API instance for the table the button belongs to.

No return value is expected or acted upon.

`exportOptions`

Type: object
Default: {}

Select the data to be gathered from the DataTable for export. This includes options for which columns, rows, ordering and search. Please see the buttons.exportData() method for full details - the object given by this parameter is passed directly into that action to gather the required data.

`footer`

Type: boolean
Default: true

Indicate if the table footer should be included in the print view or not. Please note that the default for this parameter was updated in Buttons 3.0.1 to be true. In earlier versions it was false.

`header`

Type: boolean
Default: true

Indicate if the table header should be included in the print view or not.

`message`

Type: string|function
Default: ``

Description message that can be shown in the print view document. This can include HTML.

As well as a string value, a function may also be assigned to the message property. This function will be executed when the button needs to display the message and the returned value from the function will be used. The function is passed in three parameters:

DataTables.Api - The DataTable API instance
jQuery - jQuery object for the button node
object - Configuration object for the button.

`messageBottom`

Type: string|function
Default: *
Since: 1.4.0

Message to be shown at the bottom of the table, or the caption tag if displayed at the bottom of the table.

`messageTop`

Type: string|function
Default: *
Since: 1.4.0

Message to be shown at the top of the table, or the caption tag if displayed at the top of the table.

`text`

Type: string
Default: Print

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.

`title`

Type: string|function
Default: *

Title of the table that will be included in the exported data. Please see buttons.exportInfo() for all options relating to this parameter.

Examples

DataTables initialisation: Show a print button:

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

DataTables initialisation: Disable auto display of the print dialogue box:

new DataTable('#myTable', {
	layout: {
		topStart: {
			buttons: [
				{
					extend: 'print',
					text: 'Print current page',
					autoPrint: false
				}
			]
		}
	}
});

DataTables initialisation: Use the exportOptions to print only the current DataTable page:

new DataTable('#myTable', {
	layout: {
		topStart: {
			buttons: [
				{
					extend: 'print',
					text: 'Print current page',
					exportOptions: {
						modifier: {
							page: 'current'
						}
					}
				}
			]
		}
	}
});