Web Workers

This sample describes how to use Web Workers to export FlexGrid to PDF or generate custom PDF in a background thread.

Concept

The export of FlexGrid containing many cells can take up a long time and slow down or block the main thread. Web Workers allow to run JavaScript in the background thread, thus allowing to perform intensive calculations, such as an export, in a separate thread without blocking the UI thread.

From now on, the code that is executed inside the main thread will be called a client code, and the one in the Web Worker's thread - a server code.

How to use

The library provides two classes to work with Web Workers, PdfWebWorker and PdfWebWorkerClient. The first one contains methods designed to work on the server, the second one - on the client.

This is how the interaction with these classes looks like in general:

• User creates a Web Worker and calls one of the PdfWebWorkerClient's export methods, exportGrid or export, passing the created instance of Web Worker as an argument. The client sends the necessary data to server and waits for the answer.
• Inside the server code, the corresponding method of PdfWebWorker class with 'init' prefix (initExportGrid or initExport) should be called symmetrically. The server starts to await the data from the client, it generates a PDF after data retrieving is complete, and sends that PDF back to the client.

Important: In the server code all relative paths (to fonts, images, and so on) must be specified relatively to the place where the Web Worker script itself is located.

There are three possible scenarios of using these classes:

• Simple single grid export.

  This is an analog of the FlexGridPdfConverter.export method, it doesn't allow any customization.

  PdfWebWorkerClient.exportGrid method has to be called on the client, it must be provided with Web Worker instance, FlexGrid instance and file name to export to as an arguments.

  PdfWebWorker.initExportGrid method is called on the server.

  client.js:

  var worker = new Worker('worker.js');
  wijmo.grid.pdf.PdfWebWorkerClient.exportGrid(worker, grid, 'FlexGrid.pdf', settings);
  

  worker.js:

  wijmo.grid.pdf.PdfWebWorker.initExportGrid();
  

• Custom document generation.

  Allows user to create complex documents on the server using PdfDocument API and FlexGridPdfConverter exactly the same way as if it was done on the client.

  PdfWebWorkerClient.export has to be called on the client, it must be provided with Web Worker instance and callback function to be called after document generation is complete. Additionally, the user has access to addGrid, addImage and addString methods of PdfWebWorkerClient class, which are designed to pass to the server the instance of FlexGrid class, image or string, respectively.

  PdfWebWorker.initExport method is called on the server, provided with the function which will handle the document drawing. This drawing function accepts an instance of PdfDocument class created on server and data which was added on the client using addGrid/addImage/addString methods, as an arguments.

  client.js:

  var worker = new Worker('worker.js');
  
  wijmo.grid.pdf.PdfWebWorkerClient.addString(worker, 'Title', 'title');
  wijmo.grid.pdf.PdfWebWorkerClient.addGrid(worker, grid, 'grid', gridExportSettings);
  
  wijmo.grid.pdf.PdfWebWorkerClient.export(worker, null, function (data) {
      wijmo.pdf.saveBlob(data.blob, 'Document.pdf');
  });
  

  worker.js:

  wijmo.grid.pdf.PdfWebWorker.initExport(function (doc, clientData) {
      doc.drawText(clientData\['title'\].content);
      wijmo.grid.pdf.FlexGridPdfConverter.draw(clientData\['grid'\].content, doc, null, null, clientData\['grid'\].settings);
  doc.end();
  });
  

• Low-level usage of Web Workers API.

  User arranges the interaction between the client and the server by himself in this scenario, using Web Workers API.

  The library provides the methods to serialize and deserialize a FlexGrid, PdfWebWorkerClient.serializeGrid and PdfWebWorker.deserializeGrid, respectively. The deserialized object can be passed to the draw and drawToPosition methods of FlexGridPdfConverter as a regular instance of FlexGrid.

Limitations

Because of data being passed between the threads in a serialized form, and server code having no access to DOM, the usage of Web Workers has certain limitations:

• Functions and event handlers passed to server in the form of object properties (such as IFlexGridExportSettings, IFlexGridDrawSettings and PdfDocument settings) won't work.
• SVG drawing is not supported out of the box, because Workers don't have access to the DOM. It could be overrun by plugging in the library on the server, which would implement DOM and DOMParser (xmldom, for example).
• The customCellContent mode is not supported.