PDF Exporter
Xpages Custom Control
Documentation
PDF Exporter Custom Control
Version 1.1. / Nov. 1st 2011
2(12)
Rami Muurimki
1 What is this custom control and what it does...........................................................3
1.1 PDF template....................................................................................................3
1.2 How to use Open Office Impress / Lotus Symphony Presentation.....................4
2 Technical overview..................................................................................................4
3 Installation how to use the custom control.............................................................6
3.1 PDF Template location......................................................................................7
3.1.1 File resource inside the NSF.......................................................................7
3.1.2 Public server...............................................................................................8
3.1.3 Disc resource..............................................................................................8
3.1.4 Design File Resource..................................................................................8
4 Custom Control properties.......................................................................................9
5 Known limitations...................................................................................................11
PDF Exporter Custom Control
Version 1.1. / Nov. 1st 2011
3(12)
Rami Muurimki
What is this custom control and what it does
With this XPages custom control you are able to create a fully customized PDF
document containing your design and your data and view the created PDF document
with a browser or PDF document reader (e.g. Adobe Reader, FoxIt reader etc.). The
source of your PDF document data can be a Notes Document or almost anything
else.
So far there have been PDF export related solutions where you can create PDF
documents from Notes databases using iText Open Source Java library. Using this
technique the PDF document is been created on the fly, both the design and the
data. The technique is fine with simple PDF documents but with more complex PDF
document design would be a real pain to create on the fly.
Using this Custom Control you are able to separate the UI design part elsewhere.
This gives you the flexibility to focus only on the data in your code.
As a result you get a new PDF document which is a mix of your own PDF template
file (design) and your own data.
1.1
PDF template
From the technical point of view the PDF template is an Adobe Acro Form - just a
normal PDF document containing just some Acro Fields with unique names (IDs).
Really short definition of Acro Form may be that they were originally designed to be
like interactive web forms. In this solution here, instead of letting users to enter the
values in the PDF interactive PDF document, this custom control sets the values at
code level by setting the named Acro Fields in the PDF template.
Here is one definition of the Acro Forms:
http://en.wikipedia.org/wiki/Portable_Document_Format#AcroForms
PDF Exporter Custom Control
Version 1.1. / Nov. 1st 2011
4(12)
Rami Muurimki
PDF templates (Acro Forms) can be created with several tools:
Lotus Symphony Presentation and Writer
Open Office / Libre Office Impress
Open Office / Libre Office Writer
Adobe Acrobat Professional
FoxIt Reader Form designer (foxit reader plugin)
etc.
So you have several tools to choose from. From the list above only the Open Office /
Libre Office Impress & Writer and Lotus Symphony Presentation have been
tested so far. With these free WYSIWYG editors you can design your PDF template
by adding your custom design elements, images and not forgetting the Acro Text
Fields. Best part is that Lotus Notes 8.5.x. is shipped with one editor with you you
can create PDF templates, Lotus Symphony (optional installation).
1.2
How to use Open Office Impress / Lotus Symphony Presentation
The basic design of the template file is based on a normal Impress slides (or Writer
document). There is nothing special in that. The slide(s) can contain any number of
design elements, images and other resources. The template can have one or more
slides (pages) as well.
The magic is been made with the Text Field Controls which must be added to show
any data in the PDF document. To be able to add controls, you need to open the
Form Controls toolbar by selecting it from View ==> Toolbars ==> Form Controls
menu.
After this you just set the form to design mode and draw the text fields where ever
you like on your design.
One important thing is that you must give a unique name to each Text Field you add.
This name is been used when the data is been pushed by the custom control.
After you are done with your design, final step is to export the template as a PDF file
(File ==> export as PDF). In Symphony the PDF export can be located from File ==>
Export menu.
Images
External images uses the Text Field controls also. The Text Field is been used only
on positioning and resizeing the image. Technically the image is a floating element
on top of the Text Field.
Technical overview
Custom Control requires Lotus Notes / Domino 8.5.2 client / server (or newer). So far
it has been tested with 8.5.2 and 8.5.3. Custom Control does not require any
extension libraries.
Custom control works both in Notes Client (8.5.2 / 8.5.3) and in browser (server) it's
Xpages right? :)
PDF Exporter Custom Control
Version 1.1. / Nov. 1st 2011
5(12)
Rami Muurimki
As been told already this custom control is based on the Adobe Acro Forms
technique. The actual implementation uses the Java iText PDF Open Source library
as the Acro Forms implementation. You can download the full binay distribution and
view the iText documentation from their web site http://itextpdf.com/
This custom control consists of following design elements that are shipped in the
example database.
Export PDF Custom Control
The core design element of the system.
Required design element.
BL_pdfExport Script Library
SSJS Script Library which contains the
business logic of the whole system.
Required design element.
PdfDataHelper Script Library
SSJS Script Library which contains some
helper functions which can be used if
wanted.
Optional design element. The Custom
Control itself does not require this. Use
this in your own Xpages or elsewhere.
Itext pdf jar file
Itext pdf Open Source project JAR file
(Java). See this documentation how to
import this resource to the project.
Supported (and tested) version of iText is
2.1.7.
CSS resource
Style settings for the button element.
Optional design element.
PDF Exporter Custom Control
Version 1.1. / Nov. 1st 2011
6(12)
Rami Muurimki
Installation how to use the custom control
Here is an overview of required phases to do before you can use this custom control
in your own application. First thing is to copy all the required design elements, see
the image and table in previous chapter for details of required and optional elements.
Copy paste is always easy. Just copy the required and optional design elements to
your application. Perhaps the trickiest part is to set the JAR resource to you
application build path. Here are quick instructions how and where to put it so that the
custom control works properly:
open Domino Designer (DDE)
select Window ==> Open Perspective ==> Java
find your project from the list and open the file structure
open WebContent\WEB-INF folder and create a new lib subfolder
under it.
right click and select New ==> Folder and enter the folder name (lib)
select your lib folder, right click and select Import ==> File system
find the itext JAR file from your file system.and import it to the lib folder
See the zip file (or download from itextpdf web site)
select Build Path ==> Configure Build Path from right click menu
select libraries tab from the dialog and click add JARs... button
select your project and browse to your lib folder (/webContent/WEBINF/lib) and select the JAR file you just imported.
OK
Window ==> Open Perspective ==> Domino Designer to go back to
normal look of the IDE.
Now you have imported a JAR file to your project and you are ready to go.
Select.
There's one known issue with JavaScript library loading. This custom control code is
based on a Script Library and it is been loaded normally by the Custom Control.
However the same JavaScript code is been used already by the Xpage where this
custom control has been added. This causes a JavaScript error since the Xpage is
not able to see the library and it's pdfData class yet (the library is been read
afterwards by the custom control). This issua can be fixed by adding the
BL_pdfExport script library as a resource to the xpage aswell. See the example
page. This issue has been reported in IBM web site https://www304.ibm.com/support/docview.wss?uid=swg21380793
I'm working on with this issue. There for the API of this custom control might change
a little bit in the future.
Don't forget to set the Custom Control's custom properties like the URL / file resource
of the PDF Template file.
PDF Exporter Custom Control
Version 1.1. / Nov. 1st 2011
3.1
7(12)
Rami Muurimki
PDF Template location
The PDF templates can locate in following places:
3.1.1
File resource inside the NSF
The PDF templates locating as file resources in side the NSF are accessed by using
HTTP protocol and ?OpenFileResource URL command. E.g.
http://localhost/rmu/xpages/pdfexport.nsf/test-pdf-template3.pdf?OpenFileResource
Note!! There's an ACL related issue in this technique.
In the example database's ACL the anonymous user has author access. In real life
anonymous access would be usually prohibited. By this the PDF exporter control is
unable to access the file resources using HTTP.
There's at least two work arounds to fix this problem:
Set the anonymous access as no access but allow to read and write public
documents (see image below).
In addition you need to set the public access to the file resources aswell:
PDF Exporter Custom Control
Version 1.1. / Nov. 1st 2011
8(12)
Rami Muurimki
By this the files can be accessed again using anonymous access.
Note!! I'm still trying to solve a way to access the files located in Resource ==> File
by using Java code.
3.1.2
Public server
PDF Templates can be located in a public server and they can be accessed with
normal URL-address.
3.1.3
Disc resource
Template files can be located also from client / server disc (depending on where you
run the application).
3.1.4
Design File Resource
Template files can be set inside the NSF files as a design file resource. Files are
located among the source code. This gives an opportunity to access the template
files internally by code, not by using HTTP (and anonymous access can be prohibited
in the ACL).
To configure the design resource files:
open the Java Perspective (Window ==> Open Perspective ==> Java)
open the WebContent/WEB-INF folder
create a new subfolder structuture under it e.g. src/templates
configure the new folders as a source folder by right clicking the src folder
and selecting Build Path ==> Use as Source Folder
If src already exists, just create the new templates folder
PDF Exporter Custom Control
Version 1.1. / Nov. 1st 2011
9(12)
Rami Muurimki
The idea is to set the new templates folder as a part of the class path. By this the
files in this folder are accessible at code level.
This is new feature in version 1.1.
Note!! I'm still trying to solve a way to access the files located in Resource ==> File
by using Java code.
Custom Control properties
After inserting the custom control to your xpage, you need to set some of the
following custom control properties:
PdfData
This property holds all the data (field values) that you like
to push to the PDF document.
From version 1.0.
Example
var pdfdata = new pdfData();
pdfdata.addNewData("name", "Jane Doe");
pdfdata.addNewData("id", "123456");
pdfdata.addNewData("email", "
[email protected]");
pdfdata.addNewData("checkbox1", "Off");
//
Values: Yes | Off
pdfdata.addNewData("RadioGroup1", "1");
pdfdata.addNewData("birthday", formatDate(new
java.util.Date(), "dd.MM.yyyy"));
PDF Exporter Custom Control
Version 1.1. / Nov. 1st 2011
10(12)
Rami Muurimki
// add image(s)
pdfdata.addNewImage("image1",
"http://itextpdf.com/img/iia.jpg", false);
return pdfdata;
The pdfData is a JavaScript object which holds the Text
Field values and Image data.
addNewData function
First parameter in addNewData is the id of the Acro Form
Text Field.
Second parameter is the value (in text format).
addNewDynamicData function (from version 1.1)
By dynamic data you can read values from Xpages' fields
by using the getComponent() function. In addition you can
execute fully dynamic eval JavaScript syntax as well (see
example below).
First parameter in addNewData is the id of the Acro Form
Text Field.
Second parameter is the value (in text format). If using eval
syntax, use eval: prefix as a eval function marker.
var data = new pdfData();
// read values from xpages fields
data.addNewDynamicData("id", "id");
data.addNewDynamicData("lastname", "lastname");
data.addNewDynamicData("firstname",
"firstname");
// set some values based on JS eval syntax
sessionScope.put("test", "this is just a test
from sessionScope variable!");
data.addNewDynamicData("sessionscope",
"eval:sessionScope.test");
//data.addNewDynamicData("formulas",
"eval:@UpperCase('hello world')");
data.addNewDynamicData("formulas",
"eval:@UpperCase(getComponent('lastname').getVal
ue())");
data.addNewDynamicData("formulas2",
"eval:@UserName()");
return data;
addNewImage
First parameter is the id of the Acro form Text Field which
will set the position of the image in PDF.
Second parameter is the image resource (URL address or
filename with full file path).
Third parameter enables or disables the image scale (true |
PDF Exporter Custom Control
Version 1.1. / Nov. 1st 2011
11(12)
Rami Muurimki
false).
PdfRenderType
ComboBox choice of the rendering type
From version 1.0.
- File
- OutputStream
File Creates a File in to the file system
OutputStream Creates the PDF document and renders it
to the Java Servlet output stream.
TargetFilename
Name of the final target PDF document.
From version 1.0.
This property is been used only when pdfRenderType is
been set as File.
TemplateFilename
Name and location of the PDF template to be used.
From version 1.0.
The file can reside
- behind an URL address
- in the local file system (server / client)
- inside the NSF as a file resource
Use http:// prefix if the PDF template is been accessed by
HTTP protocol (public server, file resources inside the
NSF).
Use fileres: prefix when using the design element location
to store the PDF templates. E.g.
fileres:templates/mypdftemplate.pdf
When using files in file system use e.g.
c:/dev/yourtemplate.pdf syntax.
You can also use the computed value to set a fully
customized location of the template file.
ButtonText
Button text
From version 1.0.
ButtonStyleClass
Button style class (optional).
From version 1.0.
You can use your own CSS styles as you like.
RedirectPage
Redirect user to selected Xpage after the PDF file has
been created.
From version 1.0.
Affects only when pdfRenderType is FILE.
PDF Exporter Custom Control
Version 1.1. / Nov. 1st 2011
12(12)
Rami Muurimki
Known limitations
All Text Fields in Acro Forms are always text type of fields. There for all data to be
inserted in to the PDF document needs to be in text format.
Custom Control does not support (yet) Rich Text items and their value. The
problem is that all Acro Fields are text fields.
A controller for list type of data (datagrid) is also a limitation.
Accessing File Resources by Java code. Now they are accessed only by using HTTP
and ?OpenFileResource URL command.
