XPages to PDF

XPages is rapidly gaining popularity as a rapid web and mobile application development platform. Developers often come across the need to create PDF from XPages. For certain non-business applications where the performance or the stability is not critical, developers can use open source technologies like iText or a variety of print drivers. At DominoPDF, we've received a growing number of support requests to understand the usage of DominoPDF for XPages to PDF conversion.

This article explains how XPages to PDF conversion can be achieved with DominoPDF, either using URL's or Notes Selection Formulas, and important considerations when converting XPages content.

Converting XPages URL's to PDF

DominoPDF accepts any HTTP URL and there's no difference whether the input URI is .html, .php or .xsp (XPages).

The first step in using DominoPDF to convert a URL to PDF is to include the Declare statement for calling the DominoPDF DLL and the DoPDF() method.

Declare Function DoPDF Lib "DOMINOPDF.DLL" (Byval szInput As String, Byval szOutput As String, Byval szOptions as String) As Long

The function accepts 3 arguments; szInput, szOutput and szOptions.

szInput: The input argument is where the URL is specified. An example for processing an XPage URL would be http://localhost/xpages.nsf/propCatResViews.xsp

szOutput: the output argument is the file name and path of the PDF file to be generated. For example, c:\my documents\CatResViews.pdf

szOptions: The options argument is a semi-colon (;) delimited list of name=value pairs for controlling PDF processing and output. A full list of supported options can be found in the DominoPDF Help.

Once the DoPDF() method has been declared it can be called anywhere in an application that LotusScript is supported. For example, in an agent, action button or hotspot, etc.

As the method only accepts 3 arguments it's very quick and easy to get up and running. To convert our XPage URL a sample DoPDF() method call would be as follows.

Call DoPDF("http://localhost/xpages.nsf/propCatResViews.xsp", "c:\my documents\CatResViews.pdf", "PageSize=A4;TopMargin=10")

In this sample we pass the URL to convert in the first argument, "http://localhost/xpages.nsf/propCatResViews.xsp", the PDF to generate on disk in the second argument, "c:\my documents\CatResViews.pdf" and any appropriate options in the third argument (setting Page Size to A4 and a Top Margin of 10mm).

When the method is called DominoPDF connects to the URL, streams the content and processes any external references, such as CSS, images, etc., applies any settings and saves the resulting PDF to the specified output location.

Note: If the URL connection requires authorisation the HTTP username and password can be specified in the szOptions argument.

The authentication options are WebUsername= and WebPassword=, for example;

Call DoPDF("http://localhost/xpages.nsf/propCatResViews.xsp", "c:\my documents\CatResViews.pdf", "PageSize=A4;TopMargin=10;WebUsername=John Doe;WebPasword=secret")

Important Considerations

When converting XPages to PDF with DominoPDF it is important to note that DominoPDF does not support JavaScript.

XPages makes use of JavaScript and as it's not supported by DominoPDF you'll need to ensure that any DOM / document processing actions, formatting or layout, etc. is executed before the final URL output is passed to DominoPDF.

For example, if categorised content is displayed collapsed by default you'll need to pass in URL arguments to expand the content or expand the content by default before display.

Converting XPages Selection Formulas to PDF

DominoPDF can accept a Notes selection formula for determining an input source and supports any valid selection formula as per the Notes guidelines.

The first step in using DominoPDF to convert a selection formula to PDF is to include the Declare statement for calling the DominoPDF DLL and the DoPDF() method as detailed above.

Declare Function DoPDF Lib "DOMINOPDF.DLL" (Byval szInput As String, Byval szOutput As String, Byval szOptions as String) As Long

The function accepts 3 arguments; szInput, szOutput and szOptions.

szInput: The input argument is where the selection formula is specified. An example for processing an XPage document would be; Select @Text(@DocumentUniqueID) = "8B2D1460C4D1AA6180257AA00036A39B"

szOutput: the output argument is the file name and path of the PDF file to be generated. For example, c:\my documents\xdoc.pdf

szOptions: The options argument is a semi-colon (;) delimited list of name=value pairs for controlling PDF processing and output. A full list of supported options can be found in the DominoPDF Help.

2 important options MUST be included for selection formula conversion, Server= and Database=.

Server= - Specify the server to use when evaluating a selection formula as input. If left blank or not specified then the Local server will be assumed.

Database= - Specify the database to use when evaluating a selection formula as input. The database path is relative to the Notes \data directory, for example, mail.nsf or project\marketing.nsf. The fully qualified path of the database should be used if the database is outside the Notes \data directory. For example, c:\data\mail.nsf.

Once the DoPDF() method has been declared it can be called anywhere in an application that LotusScript is supported. For example, in an agent, action button or hotspot, etc.

As the method only accepts 3 arguments it's very quick and easy to get up and running. To convert our XPage document a sample DoPDF() method call would be as follows.

Call DoPDF(|Select @Text(@DocumentUniqueID) = "8B2D1460C4D1AA6180257AA00036A39B"|, "c:\my documents\xdoc.pdf", "Server=Local;Database=xpages.nsf")

In this sample we pass the selection formula to convert in the first argument, Select @Text(@DocumentUniqueID) = "8B2D1460C4D1AA6180257AA00036A39B", the PDF to generate on disk in the second argument, "c:\my documents\xdoc.pdf" and the required options in the third argument (server is Local and database path is xpages.nsf).

When the method is called DominoPDF connects to the Notes API, generates the content and processes any external references, such as resources, images, etc., applies any settings and saves the resulting PDF to the specified output location.

JoomShaper