Data Components Export to PDF

You can export Webix data components to the PDF format. The components don't require any special configuration to be exported.

The described functionality is available both in Standard and Pro versions, but pay attention that the IE browser is supported starting from version 10.

To export a component into a PDF file, you need to call the toPDF method. The method takes the next parameters:

  • id - (string, object) id or object of the exported view
  • config - (object) optional, configuration options

For example, if you want to export a list to a PDF file, you need to call the toPDF() method with the list id as a parameter:

webix.ui({
    view:"list",
    id: "mylist",
    // list configuration
    ...
});
 
webix.toPDF($$("mylist"));

Related sample:  DataTable Export to PDF

Returning a promise with data

The toPDF() method returns a promise object. The promise is resolved with the contents of a PDF file that is ready for downloading. So, if needed, you can access raw data of the exported file (a blob object):

webix.toPDF($$("mylist")).then(function(blob){
    // the logic of processing the blob
});

For example, you may need to disable file download and process raw data according to your needs.

Exporting Data Offline

The dependencies which are used for providing export possibilities are generally taken from Webix CDN online catalog. If you need to implement data export offline, you should complete the following steps:

webix.cdn = "/local_folder";

Note that specifying the path to the local CDN repository has some peculiarities:

1) in case you set the path relative to the current page, it should be specified as:

webix.cdn = "../../../../local_folder";

2) the absolute path to the repository should be specified as follows:

webix.cdn = "http://localhost/local_folder";

Changing Font for Exported File

By default, Webix provides the pt-sans.regular.ttf font file for export. If it doesn't suit you, e.g. you need specific characters that are not included in the font, you can add another file to the "extras" folder described above and define the fontName option:

webix.toPDF($$("mylist"), { fontName:"custom"});

Note that only .ttf font files are supported.

Customizing Export to PDF

The toPDF() method returns all data specified in component dataset or in the columns parameter of a datatable view. The data is exported into a PDF document with the "data" name.

However, you may need to get some particular data or customize file properties.

Export API allows

  1. providing a custom filename
  2. stripping HTML tags from the cells
  3. setting custom columns for export
  4. defining custom header, width or template for data in the specified column
  5. not rendering "hyphens" before child nodes in tree-like structures
  6. rendering a template set in the widget's dataset
  7. including extra fields into export
  8. defining the columns' width automatically
  9. defining the PDF page orientation
  10. displaying some text or image in the header of the export file
  11. disabling file download in a browser
  12. ignoring particular columns
  • providing a custom filename:
webix.toPDF($$("table"), {
     filename: "datatable"
});

Related sample:  DataTable Export to PDF

  • stripping HTML tags from the cells
webix.toPDF($$("table"), {
     filterHTML:true
});
  • setting columns you'd like to see in the export file. There are two ways to set the custom columns for export:

You can provide an associative array (hash) with column ids as keys. Their values can be either boolean for default parameters (taken from component configuration) or object for custom parameters:

webix.toPDF($$("table"), {
    columns:{
        "rank":true,
        "title":{ header:"Title", width:250}
    }
});

With such a notation the order of the columns in the resulting file is defined automatically with a for.. in loop. Sometimes it may be unreliable, e.g.:

webix.toPDF($$("table"), {
    columns:{
        "rank":true,
        "title":{ header:"Title", width:250},
        "2016":{ header:"Votes in 2016"},
        "2015":{ header:"Votes in 2015"}
    }
});

The order in the export file will be: "2015", "2016", "rank", "title" since numbers are processed first and come in the ascending order.

To ensure the strict order of columns in the resulting file, you can specify the columns as a plain array:

webix.toPDF($$("table"), {
    columns:[
        { id:"rank" },
        { id:"title", header:"Title", width:250},
        { id:"2016", header:"Votes in 2016"},
        { id:"2015", header:"Votes in 2015"}
    ]
});

Note that if you want to get the default column's parameters in this case, you should specify only the column's id (see the "rank" column).

  • defining custom parameters, such as header, width, template or format for data in the specified column:
webix.toPDF($$("mylist"), {
  columns:{
    title:{ header: "My title", width: 200, template: webix.template("#id#.#title#")},
    year:{ header:"Year", width:150}
  }
});

The column will be rendered with the stated additional properties, which may differ from the component's parameters.

  • not rendering "hyphens" before child nodes in tree-like structures by using the plainOutput option with the true value:
webix.toPDF($$("mytreetable"), {
    columns:{
        plainOutput:true
    }
});
  • rendering a template set in the widget's dataset via setting the rawValues option to false:
webix.ui({
  rows:[
    { 
      view:"datatable", 
      data:grid_data, 
      columns:[{id:"title", fillspace:true, template:"Film #title#"}]
    }
  ]
});
 
webix.toPDF($$("$datatable1"),{
    columns:{
        rawValues:false
    }
});
  • including extra fields into export by forming them right within the export function:
webix.toPDF($$("mylist"), { 
    columns:{ 
        Custom1:{
            template:function(obj){
                return "Year " + obj.year;
            },
            width:50,
            header:"Year"
        },
        //other columns
        title:true
    }
});

"Custom1" (any name can be used) receives data from the year field even if it is not seen in this component but is presented in its dataset. The field is rendered with width and template as well as header that will be the header of the corresponding column in the resulting table.

  • specifying the autowidth parameter to define the columns' width automatically. By default, the paper size of a PDF document is A4. If you set the autowidth property to true, columns will be able to have any possible width that will define the width of a PDF page
webix.toPDF($$("mylist"), {
    autowidth:true
});
  • setting the orientation parameter which defines the PDF page orientation: portrait (default) or landscape
webix.toPDF($$("mylist"), {
    orientation:"landscape"
});
  • specifying the docHeader and docHeaderImage parameters to display some text or image in the header of the export file
// setting a custom text in the header of the PDF file
webix.toPDF($$("mylist"), {
    docHeader:"This document was made with Webix library. http://webix.com"
});
 
// setting a custom image in the header of the PDF file
webix.toPDF($$("mylist"), {
    docHeaderImage:"../common/logo.jpg"
});

Related sample:  DataTable Export to PDF: Custom configuration

Setting the headers order

By default the text header (docHeader) goes first. You can define a different order of headers with the help of the order attribute. For this, you need to specify docHeader and docHeaderImage properties as objects and set the order attribute with the number value. The header with the larger value will take the top position:

// the image header will be on top
webix.toPDF($$("mylist"), {
    docHeader: {text:"The text header", order:1},
    docHeaderImage: { url:"logo.jpg", order:0 }
});
  • disabling file download in a browser if necessary, via the download property set to false:
webix.toPDF($$("table"), {
   download:false
}).then(function(blob){
   //process raw data
});
  • ignoring particular columns during export via the ignore property. You need to set its value as an object with a list of columns names to ignore. For example:
webix.toPDF($$("table"), {
    ignore: { "votes":true, "rating":true }
});

Styling the exported data

Since data export to PDF is implemented with the help of the third-party library, you can tune the appearance of elements in the exported PDF document using properties described in its documentation.

Configuring the document's header

To configure the header of the exported PDF document, you can set a configuration object as a value of the docHeader property. Inside this object besides the text string specify all the needed properties, e.g. define the text alignment and color.

An example config may look as:

webix.toPDF($$("mylist"), {
    docHeader:{
        text: "List with custom styling",
        textAlign:"center",
        color:0x663399
    }
});

Pay attention that the color should be set in hex format starting from the 0x prefix.

There are many other possible properties of the config object. You can look all them up in the corresponding documentation (follow the "document/headeropts" section).

Configuring the header image

The export API allows you not only to set the link to the image, but also to specify an object with the necessary configuration properties of the image:

webix.toPDF($$("mylist"), {
    docHeaderImage:{ 
        url:"link", 
        align:"left", // "right"/"center"
        width:300, 
        height:20 
    }
});

Thus, you can configure the image's alignment, as well as its width and the height. More options are enumerated in the specific documentation (see the "document/imageimg-opts" section).

Related sample:  DataTable Export to PDF: extended configuration

Configuring the document's table

It's also quite easy to configure the look of the resulting table with data. You can manage the table's elements to get the desired result:

  • the table's header, e.g. set text alignment, the font size, the background color and the color of the text:
webix.toPDF($$("mylist"), {
    header:{
        textAlign:"center",
        fontSize:13,
        backgroundColor:0x3498DB,
        color:0xFFFFFF
    }
});
  • the table itself, e.g. align the text in it:
webix.toPDF($$("mylist"), {
    table:{
        textAlign:"center"
    }
});
  • the table's footer, e.g. by specifying the font size, its height and text alignment:
webix.toPDF($$("mylist"), {
    footer:{
        fontSize:9,
        height:20,
        textAlign:"right"
    }
});

Related sample:  DataTable Export to PDF: extended configuration

More possible configuration properties are described in the corresponding documentation (follow the "document/tableopts" section).

Back to top