Developers

Omnis Technical Note TNJC0012July 2021

PDF Printing in the JavaScript Client

for Omnis Studio 10.x or above
By Omnis Engineering

PDF or ‘Portable Document Format’ has become the dominant format for sharing documents and data, so for example when you download a bank statement or insurance document, or book a theatre ticket online, chances are you will be given a PDF. The alternatives to PDF would include different document formats (HTML, Word, or text) or image formats (PNG, JPG), but none of these are quite so convenient or universal, or potentially secure as PDF, especially in a cross-platform, multi-device setting when customers need to access documents or data on mobiles, tablets, or desktops, and on iOS, Android, Windows, or macOS. PDF caters to all these and is ideal for documents that are text or graphics heavy and need to be searchable.

Fortunately for Omnis developers, there is a PDF Device component that allows you to print a report to a PDF file, which can be displayed in the end user’s web browser, or sent to the Omnis HTML component, or alternatively the PDF file could be saved to a database or a folder location. At present the PDF Device requires Python to be installed (future versions may look at switching to Node.js), plus TrueType fonts must be used in the report class. For desktop apps, there is a ‘Print to PDF’ option in the File menu which creates a PDF from a report class and saves the file to a folder, but this tech note focuses on printing PDFs for web & mobile apps using the JavaScript Client.

PDF Printing Example App

There is an example app to show PDF printing via a remote form in the ‘Samples’ section of the HUB in the Studio Browser, and you can view and download the same app the JS Component Gallery app on the Omnis website: bit.ly/OmnisJSGallery. You should open Omnis Studio and go to the app ‘JS PDF Device’ in the Samples, or download it from the JS gallery (while there you may like to examine some of the other examples).

The example app provides a simple form to enter some text to be printed, but you can adapt the code to print your own reports to PDF. You need to examine the code behind the ‘Show PDF’ button, which itself calls a class method called ‘printPDF’:

PDF Device functions

First of all in the code, the current print destination is stored and the PDF device (kDevOmnisPDF) is assigned to $cdevice, the current printing device in Omnis. Then a couple of methods are called in the PDF device itself:

• $settemp specifies that the next report will print to a temporary PDF file in the omnispdf/temp folder and returns the name of the file in the lID local variable, and

• $setdocinfo specifies the author, title and subject that will be written to the PDF file (the values are taken from the remote form and are required meta-data in the PDF).

The PDF device also has the $encrypt function which sets up security properties for the PDF file, such as passwords and read access properties which are important for confidential documents (not used in this example).

Next the method prints the report class rPDFReport (using the $open method) to the current print device which in this case is PDF, passing in the report heading and body text as parameters (values taken from the remote form); the lReportInst local variable stores a reference to the report instance to be printed and currently held in memory.

PDF Print client commands

The print method in the example app next uses one of a couple of client commands:

• “showpdf” command is used to display the PDF in a new tab in the current web browser, or in a new browser window, on the desktop or mobile device (which depends on the settings in the browser whether or not a new tab is opened), or the

• “assignpdf” client command sends the PDF report to an HTML control in the remote form, which in turn will attempt to open the PDF viewer in the end user’s browser (if installed and enabled).

To use the client commands you need to use the $clientcommand method, sending the relevant command (showpdf or assignpdf), plus a row of parameters which can be passed using the row() function. So, the full syntax of these two commands would be:

Do $cinst.$clientcommand("showpdf", row(pdf-id, timeout, pdf-filename)) Do $cinst.$clientcommand("assignpdf", row(html-object-name, pdf-parameters, pdf-id, timeout, pdf-filename))

In the example app, the PDF report file is sent to an HTML object on the second page of a Paged pane in the form, unless a check box linked to the instance variable iNewPDFWindow is enabled (true), in which case the PDF is displayed in a new tab in the browser.

The following client command and parameters are used in the example app to send the report to an HTML object on the form:

Do $cinst.$clientcommand("assignpdf", row("HTML", "toolbar=1&zoom=100", lID, 20))

The row parameters include: HTML is the name of the HTML object on the 2nd page of the paged pane; the PDF parameters display the PDF viewer toolbar and sets the zoom factor; a reference to the PDF file is passed in local variable lID; and the timeout is set to 20 seconds (default is 60). When you print the report it should open in a new browser tab.

More information about PDF Printing

There is extensive information about the PDF device and printing reports to PDF in the online docs on the Omnis website, including more information about the PDF Device functions ($encrypt) and the showpdf and assignpdf client commands: see PDF Printing.

For any web or mobile based app, as well as enterprise level apps, PDF reports will probably be the required standard for critical reports, so we urge you to investigate this powerful feature of Omnis and the JS client.