PdfExport
Feature

Generates PDF/PNG files from the Grid component.

A server-side service is required to perform the export operation. Check out PDF Export Server documentation and installation steps here

When your server is up and running, it listens to requests. The Export feature sends a request to the specified URL with the HTML fragments. The server generates a PDF (or PNG) file and returns a download link (or binary, depending on sendAsBinary config). Then the Export feature opens the link in a new tab and the file is automatically downloaded by your browser. This is configurable, see openAfterExport config.

The exportServer URL must be configured. The URL can be localhost if you start the server locally, or your remote server address.

This feature will not work properly when Store uses lazyLoad

Usage

const grid = new Grid({
    features : {
        pdfExport : {
            exportServer : 'http://localhost:8080' // Required
        }
    }
})

// Opens popup allowing to customize export settings
grid.features.pdfExport.showExportDialog();

// Simple export
grid.features.pdfExport.export({
    columns : grid.columns.map(c => c.id)
}).then(result => {
    // Response instance and response content in JSON
    let { response } = result;
});

Exporting large datasets

PDF Export feature supports streaming generated pages using WebSocket connection. If server does not support it, then feature will use single HTTP request with all the data. For big datasets that can lead to page crashing when running out of memory. WebSocket support allows feature to send pages to the server one by one and then wait for the server to respond with a link to the file or the file itself.

Feature will check API status of the export server and starting from version 2.0.1, the server response will allow WebSocket connections.

Exporters

There are three exporters available by default: singlepage, multipage and multipagevertical:

singlepage - generates single page with content scaled to fit the provided paperFormat
multipage - generates as many pages as required to fit all requested content, unscaled
multipagevertical - a combination of two above: it scales content horizontally to fit into page width and then puts overflowing content on vertical pages. Like a scroll.

Loading resources

If you face a problem with loading resources when exporting, the cause might be that the application and the export server are hosted on different servers. This is due to Cross-Origin Resource Sharing (CORS). There are 2 options how to handle this:

Allow cross-origin requests from the server where your export is hosted to the server where your application is hosted;
Copy all resources keeping the folder hierarchy from the server where your application is hosted to the server where your export is hosted and setup paths using translateURLsToAbsolute config and configure the export server to give access to the path:

const grid = new Grid({
    features : {
        pdfExport : {
            exportServer : 'http://localhost:8080',
            // '/resources' is hardcoded in WebServer implementation
            translateURLsToAbsolute : 'http://localhost:8080/resources'
        }
    }
})

// Following path would be served by this address: http://localhost:8080/resources/
node ./src/server.js -h 8080 -r web/application/styles

where web/application/styles is a physical root location of the copied resources, for example:

This feature is disabled by default. For info on enabling it, see GridFeatures.

Configs

Configs are options you supply in a configuration object when creating an instance of this class

alignRows : Booleanfalse

Set to true to align row top to the page top on every exported page. Only applied to multipage export.
clientURL : String

Export server will navigate to this url first and then will change page content to whatever client sent. This option is useful with react dev server, which uses a strict CORS policy.
exportDialog : ExportDialogConfig

A config object to apply to the ExportDialog widget.

Has a corresponding runtime exportDialog property.
exportMask : String"Generating pages..."

A message to be shown when Export feature is performing export.
exportProgressMask : String"Waiting for response from server..."

A message to be shown when export is almost done.
exportServer : String

URL of the print server.
exporterConfig : Object

private

Config for exporter.
exporterType : 'singlepage'/'singlepageunscaled'/'multipage'/'multipagevertical'/Stringsinglepage

Type of the exporter to use. Should be one of the configured exporters
exporters : Exporter[]["SinglePageExporter","SinglePageUnscaledExporter","MultiPageExporter","MultiPageVerticalExporter"]

List of exporter classes to use in export feature
fetchOptions : FetchOptions

An object containing the Fetch options to pass to the export server request. Use this to control if credentials are sent and other options, read more at MDN.

footerTpl : Function

A template function used to generate a page footer. It is passed an object with ´currentPage´ and `totalPages´ properties.

let grid = new Grid({
     appendTo   : 'container',
     features : {
         pdfExport : {
             exportServer : 'http://localhost:8080/',
             footerTpl    : () => '<div class="demo-export-footer"><h3>© 2020 CoolCorp Inc</h3></div>'
         }
     }
});

Parameters

data : Object

Data object
currentPage : Number

Current page number
totalPages : Number

Tolal pages count

Returns

String

headerTpl : Function

A template function used to generate a page header. It is passed an object with ´currentPage´ and `totalPages´ properties.

let grid = new Grid({
    appendTo   : 'container',
    features : {
        pdfExport : {
            exportServer : 'http://localhost:8080/',
            headerTpl : ({ currentPage, totalPages }) => `
                <div class="demo-export-header">
                    <img src="coolcorp-logo.png"/>
                    <dl>
                        <dt>Date: ${DateHelper.format(new Date(), 'll LT')}</dt>
                        <dd>${totalPages ? `Page: ${currentPage + 1}/${totalPages}` : ''}</dd>
                    </dl>
                </div>`
         }
    }
});

Parameters

data : Object

Data object
currentPage : Number

Current page number
totalPages : Number

Tolal pages count

Returns

String

keepPathName : Booleantrue

When true links are converted to absolute by combining current window location (with replaced origin) with resource link. When false links are converted by combining new origin with resource link (for angular)
keepRegionSizes : Object<String, Boolean>
By default, subGrid width is changed to fit all exported columns. To keep certain subGrid size specify it in the following form:
```
keepRegionSizes : {
    locked : true
}
```
lockPaperSize : Booleanfalse

Defines if printed/exported page should contain @page style with paper size and orientation specified.
openAfterExport : Booleantrue

When true, page will attempt to download generated file.
openInNewTab : Booleanfalse

False to open in the current tab, true - in a new tab
repeatHeader : Booleanfalse

Set to true to show column headers on every page. This will also set alignRows to true. Only applies to MultiPageVertical exporter.
rowReadyCondition : Function
A function that determines when to capture the HTML for exported rows. When set to null (the default), the export happens immediately without waiting. The function receives the export configuration as a parameter. The rendering process works in chunks, using the same approach as the Grid component - displaying visible rows with an additional buffer.

Examples:
```
// simple timeout
new Grid({
    features : {
        pdfExport : {
            rowReadyCondition : async () => await new Promise(resolve => setTimeout(resolve, 100))
        }
    }
});

// waiting for a condition
new Grid({
    features : {
        pdfExport : {
            rowReadyCondition : async () => await promiseWithCondition
        }
    }
});
```
Returns

void

Has a corresponding runtime rowReadyCondition property.
sendAsBinary : Booleanfalse

Set to true to receive binary file from the server instead of download link.
showErrorToast : Booleantrue

Set to false to not show Toast message on export error.
translateURLsToAbsolute : Boolean/Stringtrue

True to replace all linked CSS files URLs to absolute before passing HTML to the server. When passing a string the current origin of the CSS files URLS will be replaced by the passed origin.

For example: css files pointing to /app.css will be translated from current origin to {translateURLsToAbsolute}/app.css
useBrowserPrint : Booleanfalse

private

When true, export feature will use an iframe and browser's default print dialog, which allows saving as PDF. Content is optimized for chrome/edge to exact page size in the specified orientation and no margins. If you only see grid header or blank pages, try using different scale value in the print dialog NOTE: Not supported in Safari. Print works, but Safari cannot seem to fit content to one page correctly.
useRenderedColumnWidth : Boolean

private

This config forces exporter to always use rendered column width. Used by Agenda view in Calendar
webSocketAvailable : Boolean

Determines whether to stream exported pages directly to the export server using WebSocket connection to offload client application. false - use legacy mode which first collected all pages locally and then passed them in a single request true - stream pages directly to the server null (default) - ask export server for WebSocket support and use it if possible

Has a corresponding runtime webSocketAvailable property.
webSocketRequestTimeout : Number

Maximum time in ms to wait for the response over the websocket connection

Has a corresponding runtime webSocketRequestTimeout property.
fileFormat : 'pdf'/'png'pdf

Format of the exported file, either pdf or png.
fileName : String

Name of the exported file.
orientation : 'portrait'/'landscape'portrait

Orientation. Options are portrait and landscape.
paperFormat : 'A0'/'A1'/'A2'/'A3'/'A4'+ 3 moreA4

Export paper format. Available options are A1...A5, Legal, Letter.
rowsRange : 'all'/'visible'all

Specifies which rows to export. all for complete set of rows, visible for only rows currently visible.

Properties

Properties are getters/setters or publicly accessible variables on this class

isPdfExport : Booleantrue

READONLY

static

ADVANCED

Identifies an object as an instance of PdfExport class, or subclass thereof.

currentExportPromise : Promise/null

When export is started from GUI (ExportDialog), export promise can be accessed via this property.
exportDialog : ExportDialog

Returns the instantiated export dialog widget as configured by exportDialog

Has a corresponding exportDialog config.
isExporting : Boolean

READONLY

This yields true if an export/print operation is ongoing.
rowReadyCondition : Function
A function that determines when to capture the HTML for exported rows. When set to null (the default), the export happens immediately without waiting. The function receives the export configuration as a parameter. The rendering process works in chunks, using the same approach as the Grid component - displaying visible rows with an additional buffer.

Examples:
```
// simple timeout
new Grid({
    features : {
        pdfExport : {
            rowReadyCondition : async () => await new Promise(resolve => setTimeout(resolve, 100))
        }
    }
});

// waiting for a condition
new Grid({
    features : {
        pdfExport : {
            rowReadyCondition : async () => await promiseWithCondition
        }
    }
});
```
Has a corresponding rowReadyCondition config.
webSocketAvailable : Boolean

Determines whether to stream exported pages directly to the export server using WebSocket connection to offload client application. false - use legacy mode which first collected all pages locally and then passed them in a single request true - stream pages directly to the server null (default) - ask export server for WebSocket support and use it if possible

Has a corresponding webSocketAvailable config.
webSocketRequestTimeout : Number

Maximum time in ms to wait for the response over the websocket connection

Has a corresponding webSocketRequestTimeout config.
isPdfExport : Booleantrue

READONLY

ADVANCED

Identifies an object as an instance of PdfExport class, or subclass thereof.

Functions

Functions are methods available for calling on the class

downloadLink( name, href )

private

Creates link to download the file.
export( config )
: Promise

ASYNC

Starts the export process. Accepts a config object which overrides any default configs. NOTE. Component should not be interacted with when export is in progress

filterStyles( styles )

: String[]

This method accepts all stylesheets (link and style tags) which are supposed to be put on the page. Use this hook method to filter or modify them.

new Grid({
    features: {
        pdfExport: {
            // filter out inline styles and bootstrap.css
            filterStyles: styles => styles.filter(item => !/(link|bootstrap.css)/.test(item))
        }
    }
});

getConsumer( config )
: Promise

private

ASYNC

Returns consumer instance
getExporter( config )
: ExporterBase

private

Returns instance of the exporter
processExportContent( response, config )
: Promise

ASYNC
Handles output of the receiveExportContent. Server response can be of two different types depending on sendAsBinary config:
- application/json In this case JSON response contains url of the file to download
- application/octet-stream In this case response contains stream of file binary data
If openAfterExport is true, this method will try to download content.

receiveExportContent( pages, config )

: Promise

ASYNC

Sends request to the export server and returns Response instance. This promise can be cancelled by the user by clicking on the toast message. When the user clicks on the toast, abort method is called on the promise returned by this method. If you override this method you can implement abort method like in the snippet below to cancel the request.

class MyPdfExport extends PdfExport {
    receiveExportContent(pages, config) {
        let controller;

        const promise = new Promise(resolve => {
            controller = new AbortController();
            const signal = controller.signal;

            fetch(url, { signal })
                .then(response => resolve(response));
        });

        // This method will be called when user clicks on the toast message to cancel the request
        promise.abort = () => controller.abort();

        return promise;
    }
}

const grid = new Grid({ features: { myPdfExport : {...} } });

grid.features.myPdfExport.export().catch(e => {
    // In case of aborted request do nothing
    if (e.name !== 'AbortError') {
        // handle other exceptions
    }
});

responseBlobToObjectURL( response, mimeType )
: Promise

private

ASYNC

Creates object URL from response content with given mimeType
showExportDialog( )
: Promise

ASYNC

Shows export dialog

Events

Events are triggered for certain actions in this class and can be listened for to react to those actions in your code

beforePdfExport

PREVENTABLE

ON-OWNER

Fires on the owning Grid before export started. Return false to cancel the export.

Note that this event is triggered on the owning widget:
exportStep

Fires when export progress changes
pdfExport

ON-OWNER

Fires on the owning Grid when export has finished

Note that this event is triggered on the owning widget:

Event handlers

Event handlers are callbacks called as a result of certain actions in this class

onBeforePdfExport

PREVENTABLE

ON-OWNER

Called on the owning Grid before export started. Return false to cancel the export.

Note that this handler is called on the owning widget:
onExportStep

Called when export progress changes
onPdfExport

ON-OWNER

Called on the owning Grid when export has finished

Note that this handler is called on the owning widget:

id: pdfExport

Source path

Grid/feature/export/PdfExport.js

Demo

examples/export

PdfExport
Feature

Usage

Exporting large datasets

Exporters

Loading resources

See also

Configs

Parameters

Returns

Parameters

Returns

Returns

Properties

Functions

Events

Event handlers

Source path

Demo

Inheritance tree3

Mixins2

Contents

PdfExport Feature

Usage

Exporting large datasets

Exporters

Loading resources

See also

Configs

Parameters

Returns

Parameters

Returns

Returns

Properties

Functions

Events

Event handlers

Source path

Demo

Inheritance tree3

Mixins2

Contents

PdfExport
Feature