Printing

Overview
Print Styling
Full Page Printing

Overview

Print functionality is provided by the Print Module

Tabulator offers a range of print styling options, from deciding how your table should look on the page when the site is printed to printing full page tables.

Print Controls

Loading Example...

Source Code

HTML

<div>
    <button id="print-table">Print Table</button>
</div>

<div id="example-table"></div>

CSS

/*Horizontally center header and footer*/
.tabulator-print-header, tabulator-print-footer{
    text-align:center;
}

JavaScript

//Build Tabulator
var table = new Tabulator("#example-table", {
    height:"311px",
    layout:"fitColumns",
    printAsHtml:true,
    printHeader:"<h1>Example Table Header<h1>",
    printFooter:"<h2>Example Table Footer<h2>",
    columns:[
    {title:"Name", field:"name", width:200, editor:"input"},
    {title:"Progress", field:"progress", hozAlign:"right", editor:"input"},
    {title:"Gender", field:"gender", editor:"input"},
    {title:"Rating", field:"rating",  hozAlign:"center", width:100},
    {title:"Favourite Color", field:"col"},
    {title:"Date Of Birth", field:"dob", sorter:"date", hozAlign:"center"},
    {title:"Driver", field:"car", hozAlign:"center", sorter:"boolean"},
    ],
});

//print button
document.getElementById("print-table").addEventListener("click", function(){
   table.print(false, true);
});

Note: The print module does not support nested tables

By Default when a page is printed that includes a Tabulator it will be rendered on the page exactly as the table is drawn. While this is useful in most cases, some users prefer to have more controll over the print output, for example showing all rows of the table, instead of just those visible with the current position of the scroll bar.

Tabulator provides a print styling mode that will replace the Tabulator with an HTML table for the printout giving you much more control over the look and feel of the table for the print out., to enable this mode, set the printAsHtml option to true in the table constructor.

var table = new Tabulator("#example-table", {
    printAsHtml:true, //enable html table printing
});

This will replace the table (in print outs only) with a simple HTML table with the class tabulator-print-table that you can use to style the table in any way you like.

It also has the benifit that because it is an HTML table, if it crosses a page break your browser will uatomatically add the column headers in at the top of the next page.

Table Contents

The HTML table will contain column header groups, row groups, data trees and column calculations.

You can choose to remove any of these from the output data by setting the values in the printConfig option in the table definition:

var table = new Tabulator("#example-table", {
    printConfig:{
        columnHeaders:false, //do not include column headers in printed table
        columnGroups:false, //do not include column groups in column headers for printed table
        rowHeaders:false, //do not include row headers in printed table
        rowGroups:false, //do not include row groups in printed table
        columnCalcs:false, //do not include column calcs in printed table
        dataTree:false, //do not include data tree in printed table
        formatCells:false, //show raw cell values without formatter
    },
});

Field Data
It is worth noting that only columns with a field set in their definitions will be included in the output, this is because exports are generated from table data, and if a column has no field it has no data.

Table Styling

If you want your printed table to be styled to match your Tabulator you can set the printStyled to true, this will copy key layout styling to the printed table

var table = new Tabulator("#example-table", {
    printAsHtml:true, //enable html table printing
    printStyled:true, //copy Tabulator styling to HTML table
});

Row Range

By default, only the rows currently visible in the table viewport will be added to the HTML table, the printRowRange option takes a Row Range Lookup value and allows you to choose which rows are included in the print output:

visible - Rows currently visible in the table viewport
active - Rows currently in the table (rows that pass current filters etc)
selected - Rows currently selected by the selection module (this includes not currently active rows)
all - All rows in the table regardless of filters

var table = new Tabulator("#example-table", {
    printRowRange:"selected", //change default selector to selected
});

Render Time
Because generating a table containing a lot of rows takes a lot of time and consumes a lot of memory, it is not advised to show all rows in your table if there are more than 1000 rows.

Custom Row Range

For custom row ranges it is also possible to pass a function into the printRowRange option that should return an array of Row Components:

var table = new Tabulator("#example-table", {
    printRowRange:function(){
        //only copy rows to print where the age is over 18
        return this.getRows().filter((row) => {
            return row.getData().age > 18;
        });
    },
});

Column Visibility

If you don't want to show a particular column in the print table you can set the print property in its column definition object to false:

var table = new Tabulator("#example-table", {
    columns:[
        {title:"Hidden Column", field:"secret", print:false} //hide data in print data
    ]
});

You can also force a hidden column to be visibile in the print by setting the print property in its column definition object to true:

var table = new Tabulator("#example-table", {
    columns:[
        {title:"Hidden Column", field:"secret", visible:false, print:true} //show hidden column when printing
    ]
});

For more complex usage cases you can pass a callback function to the print option, this will be called just before the print output is generated. The function will be passed the Column Component of its column as the first argument and should return a boolean indicating the columns visibility.

var table = new Tabulator("#example-table", {
    columns:[
        {title:"id", field:"id", print:function(column){
            //column - column component for current column

            return true; //make column visible in print
        }} 
    ]
});

Change Column Title in Print

You can add a custom column title to be used in the printing data instead of the usual title by setting the titlePrint property in the column definition object:

var table = new Tabulator("#example-table", {
    columns:[
        {title:"Name", field:"name", titlePrint:"Full Name"} //change column title to "Full Name" in print
    ]
});

Print Accessors

You can use the accessorPrint and accessorPrintParams options on a column definition to alter the value of data in a column before it is printed.

The example below will transform all ages into a boolean, showing if they are over 18 or not. The accessorPrintParams is used to pass the age limit to the accessor so the same accessor function can be used on multiple columns with different age limits:

var ageAccessor = function(value, data, type, params, column){
    return value >= params.legalAge;
}

{title:"Under Age", field:"age", accessorPrint:ageAccessor, accessorPrintParams:{legalAge:18} }

Full details of how accessors work can be found in the Accessors Documentation.

Formatters

Cell Formatters

When printing you may want to apply a different formatter from the one usualy used to format the cell, you can do this using the formatterPrint column definition option.

You can use the formatterPrintParams to pass in any additional params to the formatter

These properties take the same inputs as the standard formatter property

//define print formatter
function printFormatter(cell, formatterParams, onRendered){
    return cell.getValue() ? "YES" : "NO";
}

//column definition
{title:"Driver", field:"driver", formatter:"tickCross", formatterPrint:printFormatter} //show "YES"/"NO" in the cell when printing

Passing a value of false into the formatter will cause the value to be shown as plain text without a formatter

Row Formatter

When printing you may want to apply a different formatter may want to apply a different formatter from the one usualy used to format the row. You can now do this using the rowFormatterPrint table option, which takes the same inputs as the standard rowFormatter property.

var table = new Tabulator("#example-table", {
    rowFormatter:function(row){
        //row - row component

        var data = row.getData();

        if(data.col == "blue"){
            row.getElement().style.backgroundColor = "#1e3b20";
        }
    },
    rowFormatterPrint:function(row){
        //row - row component

        var data = row.getData();

        if(data.col == "blue"){
            row.getElement().style.backgroundColor = "#0000ff"; //use a different shade of blue background when printing
        }
    },
});

Passing a value of false into the formatter prevent the default row formatter from being run during print

Group Headers

When printing you may want to apply a different group header from the one usualy used in the table. You can now do this using the groupHeaderPrint table option, which takes the same inputs as the standard groupHeader property.

var table = new Tabulator("#example-table", {
    groupHeader: function(value, count, data, group){
        return value + "<span style='color:#d00; margin-left:10px;'>(" + count + " item)</span>";
    },
    groupHeaderPrint: function(value, count, data, group){
        return value + "<span style='color:#d00; margin-left:10px;'></span>";
    },
});

Passing a value of false into groupHeaderPrint will cause the header to show the groups key as plain text

Full Page Printing

You can use the print function to trigger a full page printing of the contents of the table without any other elements from the page.

table.print();

There are three arguments that can be passed into the function to configure the output. The first argument is a Row Range Lookup value that determins which rows are shown in the printed table, if no value is set it will use the value set in the printRowRange option.

The second argument is a boolean that determines if the output of the function should be styled to match the table (true) or be a blank html table (false), if you leave this argument out it will take the value of the printStyled option

The third argument takes an object that can be used to override the object set on the printConfig option

table.print("active", true, {columnGroups:false}); //full page print the table for visible rows of table that copies the table style without grouped column headers

Header

You can use the printHeader table setup option to define a header to be displayed when the table is printed.

var table = new Tabulator("#example-table", {
    printHeader:"<h1>THIS IS MY COOL TABLE</h1>", // set header content on printed table
});

This option can take one of three types of value:

string - you can pass an HTML string to be set as the contents header
DOM Node - you can pass DOM Node to be used as the header
function - a function that will be called when the table is printed, it should return either a string or DOM Node

The header contents will be placed inside a div with a class of tabulator-print-header to allow you to style your header with CSS

Print Header Placement
The print header will be inserted above the table on the printout, this will only occur on the first page of the print out, this should not be used as a page header.

Footer

You can use the printFooter table setup option to define a footer to be displayed when the table is printed.

var table = new Tabulator("#example-table", {
    printFooter:"<h3>THANKS FOR LOOKING AT MY TABLE</h3>", // set footer content on printed table
});

This option can take one of three types of value:

string - you can pass an HTML string to be set as the contents footer
DOM Node - you can pass DOM Node to be used as the footer
function - a function that will be called when the table is printed, it should return either a string or DOM Node

The footer contents will be placed inside a div with a class of tabulator-print-footer to allow you to style your footer with CSS

Print Footer Placement
The print footer will be inserted below the table on the printout, this will only occur on the last page of the print out, this should not be used as a page footer.

Print Formatting

The printFormatter table setup option allows you to carry out any manipulation of the print output before it is displayed to the user for printing

var table = new Tabulator("#example-table", {
    printFormatter:function(tableHolderElement, tableElement){
        //tableHolderElement - The element that holds the header, footer and table elements
        //tableElement - The table
    }
});

Cell Formatters onRendered Callback

When cell formatters are used in printed columns, the onRendered callback passed into the formatter may behave differently from usual table operation.

Because there is no way to know when the HTML generated by this functionality is actualy visible as it is never added to the DOM, the onRendered function is triggered as soon as the formatter returns its contents, which may result in a malfunction for some custom formatters.

If you need your custom formatter to behave differently under these circumstances, you can perform the following check on the cell variable passed into the formatter to see if you need to take any specific action

onRendered(function(){
    if(!(cell instanceof CellComponent)){
        // formatter being called for print or getHTML output
    }
}

Version 6.3 Released!