inforama document automation manual

D o cu m e n t A u tom a tio n w ith In fo ra m a■■■

Inforama Community Edition

1

Document Automation with InforamaInforama Community EditionVersion 1.5

Copyright © 2008-2010 Inforama Limitedwww.in4ama.org

This document is subject to change without notice

LicenseThe contents of this document are subject to the General Public License (GPL). You maynot use this document except in compliance with this license.

DisclaimerYour Warranty, Limitations of liability and Indemnity are expressly stated in the Agreement.

If you need technical support for this product, contact Customer Support by email at [email protected]. If you have comments or suggestions about this documentation, contact us at [email protected]

UpdatesAs of version 1.4 of Inforama, this document will be phased out and be replaced with documentation which can be accessed via the Inforama website. Tutorials can be viewed at http://www.in4ama.org/web/guest/community/wiki/-/wiki/Main/Tutorials

Other technical articles can be viewed on the community Wiki at http://www.in4ama.org/web/guest/community/wiki

2

http://www.openedgesoft.com/

http://www.in4ama.org/web/guest/community/wiki

http://www.in4ama.org/web/guest/community/wiki/-/wiki/Main/Tutorials

mailto:[email protected]

Contents at a glanceChapter 1 – Introduction........................................................................................................6Chapter 2 – Getting Started.................................................................................................10Chapter 3 – Data Sources and Datasets.............................................................................15Chapter 4 – OpenOffice Letters and Letter Fragments.......................................................26Chapter 5 – Working with Acrobat Forms............................................................................34Chapter 6 – Acrobat forms from OpenOffice Documents....................................................42Chapter 7 – Editing Emails..................................................................................................49Chapter 8 – Iterating Datasets.............................................................................................52Chapter 9 – Data Formatting...............................................................................................59Chapter 10 – Managing Documents and Packs..................................................................63Chapter 11 – Printing...........................................................................................................68Chapter 12 – Document Generation Wizard........................................................................70Chapter 13 – Table Formatting............................................................................................76

3

Table of ContentsChapter 1 – Introduction........................................................................................................6

What is Inforama?..............................................................................................................6Letter Generation...............................................................................................................6Acrobat Form Generation..................................................................................................7Other Features...................................................................................................................7Advanced Features............................................................................................................7Inforama Community/Enterprise Edition............................................................................7Related Technologies........................................................................................................8License Information...........................................................................................................9More information................................................................................................................9

Chapter 2 – Getting Started.................................................................................................10System Requirements.....................................................................................................10Running Inforama Studio.................................................................................................10

Windows Users............................................................................................................10Linux Users..................................................................................................................10

Quick Tour of Inforama Studio.........................................................................................11Creating a new Inforama Project.....................................................................................13

Chapter 3 – Data Sources and Datasets.............................................................................15Creating a new “JDBC Connection” data source............................................................15Creating Parameters........................................................................................................17Creating a new “JDBC Connection” data set..................................................................18Using datasources and datasets.....................................................................................19Creating a new “Spreadsheet” data source.....................................................................22Creating a new “Spreadsheet” data set...........................................................................23Creating custom datasources and datasets....................................................................24

Chapter 4 – OpenOffice Letters and Letter Fragments.......................................................26Creating OpenOffice Letters............................................................................................26Adding Parameters to Letters..........................................................................................27Adding Data Fields to Letters..........................................................................................29Creating Letter Fragments...............................................................................................31

Chapter 5 – Working with Acrobat Forms............................................................................34Creating and binding Acrobat Fields...............................................................................34Creating new Acrobat Fields within the Studio................................................................36Acrobat Field binding types.............................................................................................36

Text field binding.........................................................................................................36Image binding .............................................................................................................37Barcode binding...........................................................................................................39Checkbox binding .......................................................................................................40

Chapter 6 – Acrobat forms from OpenOffice Documents....................................................42Creating an Acrobat Form from OpenOffice....................................................................42Switching to the Acrobat Form View................................................................................45Binding to the Acrobat Fields...........................................................................................46Previewing the Document................................................................................................47

Chapter 7 – Editing Emails..................................................................................................49Creating an Email Document from OpenOffice...............................................................49Previewing Emails...........................................................................................................50

Chapter 8 – Iterating Datasets.............................................................................................52

4

Accessing database data (DataSources and DataSets).................................................52Data Set Iteration.............................................................................................................52Nested Data Set Iteration................................................................................................54Table Row Iteration..........................................................................................................55Table Cell Iteration...........................................................................................................57

Chapter 9 – Data Formatting...............................................................................................59Basic Formatters..............................................................................................................59Creating a custom data formatter ...................................................................................60Using a Custom Formatter...............................................................................................62

Chapter 10 – Managing Documents and Packs..................................................................63Managing Documents......................................................................................................63Creating a Single Document............................................................................................63Creating Compound Documents from Letter Fragments................................................64Working with the Preview Dialog.....................................................................................65Associating Emails with Documents................................................................................66Setting the Background Document..................................................................................66Applying Display Conditions............................................................................................67

Chapter 11 – Printing...........................................................................................................68Acrobat Command...........................................................................................................68Foxit Command................................................................................................................68JPedal Printer..................................................................................................................69PDF Supporting Printer....................................................................................................69Creating a Custom Printer Class.....................................................................................69

Chapter 12 – Document Generation Wizard........................................................................70Generating Documents and Packs..................................................................................70Generating Mailshots.......................................................................................................73

Chapter 13 – Table Formatting............................................................................................76Introduction......................................................................................................................76Getting started with Table Formatters.............................................................................76Sub Tables.......................................................................................................................77Using Table Templates....................................................................................................78Applying header templates..............................................................................................80Including Sub Table Templates.......................................................................................81Manipulating tables from custom Java classes...............................................................82

5

C h a p t e r 1 – I n t r o d u c t i o n

What is Inforama?Inforama is an Open Source document automation system for generating, distributing and archiving dynamic and personalised PDF documents. Many technologies exist today that can generate and manipulate PDF documents and Inforama brings them together to create a single system that can manage documents in businesses large and small.

There are two main document types that can be created within Inforama Studio – Letters and Acrobat Forms. Letters are for freeflowing text where data can be dynamically inserted without interfering with the flow of the text within the document.

Acrobat Forms are typically used where content is fixed in absolute positions throughout the document. Examples of Acrobat Forms would be application type forms as would be used by financial institutions, insurance companies and government agencies.

Acrobat Forms are a PDF format and can be created by commonly available applications such as Adobe Illustrator, Adobe Acrobat Professional and OpenOffice. Once created in these applications PDF Acrobat Forms can be easily imported into Inforama Studio to enable binding to database data.

Sample Acrobat Forms can be viewed or downloaded from...

http://www.irs.gov/pub/irs-pdf/

http://www.revenue.ie/index.htm?/publications/curntfms/curfrms.htm

http://www.ehic.ie/includes/ehic_app_eng.pdf

Letter GenerationMail merging documents is nothing new but with Inforama you can create letters using the powerful OpenOffice writer wordprocesser which will eventually get transformed into high quality PDF documents. PDF document letterheads can also be applied to letters in order to achieve a consistent, mananged and professional feel to correspondence.

Some technologies and solutions currently exist which automate OpenOffice on the server to generate documents but this is a significant overhead as OpenOffice takes up a large amount of resources and can be slow to process documents in this way. With Inforama, the OpenOffice documents are created within the studio and as they are saved they are automatically transformed into an XML format. In this way, only the XML documents are used to generate the PDFs and the original OpenOffice documents do not need to be loaded into OpenOffice each time.

The PDFs generated from OpenOffice are not always pixel perfect replicas of what has been created in the OpenOffice editor. It may be necessary at times to edit the document, preview it and tweak it until the generated PDF is rendered as required.

Letter fragments can also be merged to create single documents allowing users to create a repository of fragments or paragraphs. Again, PDF letterheads can be applied to the resulting letters.

6 Chapter 1 – Introduction

http://www.ehic.ie/includes/ehic_app_eng.pdf

http://www.revenue.ie/index.htm?/publications/curntfms/curfrms.htm

http://www.irs.gov/pub/irs-pdf/

Acrobat Form GenerationAcrobat Forms are a ubiquitous format for data capture in many market sectors including financial services, government and insurance. Typically these forms are forwarded to applicants by post and returned once filled in. With Inforama these forms can be prepopulated with database data and emailed to the customer. This reduces postage costs, time delays, data entry mistakes and the amount of paper being used. If also provides the customer with a sense of relief at not having to tackle lengthy application forms.

Acrobat Forms can also be tagged with barcodes allowing them to be scanned when returned to the originating office. Using this method companies can streamline their workflow processes by automatically identifying the customer and the document type.

Other FeaturesWith Inforama Studio it is also possible to group letters and document together in document packs which get generated in a single call. Email templates can be edited using the embedded OpenOffice editor providing the user with all of the advanced features of this environment. Built in data formatters allow data to be manipulated as it's inserted into documents.

Advanced FeaturesMore complex manipulation of documents can be achieved by embedding Groovy script in documents. This feature requires the document author to have some knowledge of Groovy and Java.

Java developers can also write their own custom data sources, formatters and document lifecycle classes which can be used to further extend the capabilities of Inforama.

It is also possible to create complex table structures with the help of built in table formatters which can be extended by using custom Java code.

Inforama Enterprise allows users to automatically store generated documents in a document repository on the server along with parameters and actions which were carried out on the documents.

Inforama Community/Enterprise EditionInforama comes in two flavours – the free to use Open Source Community version and the commercial Open Source version.

Inforama Community verison includes...

● Inforama Studio – A powerful Java editor application which embeds OpenOffice and allows users to import database data to merge with letters and Acrobat Forms.

● Inforama Data Source Manager – Allows access to various databases via JDBC connections. Also allows for non-database data to be imported from sources such as Spring and Hibernate. Advanced users can write their own data access components to access data from other data sources.

● Inforama Automator – Manages documents and document packs and provides information about how they are configured and used.

● Inforama Engine – Takes care of document generation. Retrieves the resources required for a document generation job and takes care of merging data and generating the eventual PDF files.


Inforama Enterprise version includes...

● Inforama Data Source Manager, Automator and Engine as described above and...

● Inforama Server – Projects created in Inforama Studio can get deployed to Inforama Server allowing documents to be generated in a central and managed environment. Inforama Server allows documents to be generated via web services calls where they can be emailed, printed and returned to the calling applicaiton. Documents can also be stored in a document repository on the server allowing tracking of activity and retrieval of previously generated documents.

For more information on Inforama Enterprise contact [email protected]

Related TechnologiesThe following Open Source projects are used by Inforama and knowledge of them may provide developers with the ability to enhance and extend Inforama.

Technology License Website Description

OpenOfficeWriter

LGPL http://www.openoffice.org

WRITER has everything you would expect from a modern, fully equipped word processor or desktop publisher.

iText MPL & LGPL http://www.lowagie.com/iText

iText is a library that allows you to generate PDF files on the fly.

Apache FOP Apache License, 2.0

http://xmlgraphics.apache.org/fop

Apache FOP (Formatting Objects Processor) is a print formatter driven by XSL formatting objects (XSL-FO) and an output independent formatter. It is a Java application that reads a formatting object (FO) tree and renders the resulting pages to a specified output. Output formats currently supported include PDF, PS, PCL, AFP, XML (area tree representation), Print, AWT and PNG, and to a lesser extent, RTF and TXT. The primary output target is PDF.

Office2fO GPL http://www.sf.net/projects/office2fo

The Office2FO project is a set of XSLT files which will transform OASIS Open Document Format files to the XSL-FO format. The XSLT files can be used directly within OpenOffice to export documents to the XSL-FO format.

Groovy Apache License, 2.0

http://groovy.codehaus.org

An agile and dynamic language for the Java Virtual Machine.

* Spring Apache License, 2.0

http://www.springframework.org

Spring is an Open Source framework which was created as a reaction to the complexity of traditional enterprise Java application development. Spring is a modular framework allowing selectivity when it comes to your choice of it's functionality.

* Used only in Inforama Enterprise.


http://www.springframework.org/

http://www.springframework.org/

http://groovy.codehaus.org/


http://www.sf.net/projects/office2fo

http://www.sf.net/projects/office2fo

http://xmlgraphics.apache.org/fop/0.95/output.html



http://www.lowagie.com/iText

http://www.lowagie.com/iText

http://www.openoffice.org/



License InformationInforama Studio Edition is released under the GPL license.

Inforama Enterprise is release under a commercial Open Source license. For more information on Inforama Enterprise contact [email protected]

More informationAnyone can get involved in the development and activities surrounding Inforama by visiting http://www.in4ama.org or http://www.sourceforge.net/projects/inforama


http://www.sourceforge.net/projects/inforama

http://www.in4ama.org/


C h a p t e r 2 – G e t t i n g S t a r t e d

System RequirementsJava – A Java Runtime version 1.5 or greater is required to run Inforama Studio

OpenOffice – OpenOffice Writer version 2.0 or greater is required on the machine where Inforama Studio will be running. Version 1.1 of Inforama Studio has been updated to work with OpenOffice 3.0.0.

Running Inforama StudioInforama studio embeds OpenOffice Writer in order to provide letter writing capabilities using a powerful, modern word processer. So before starting you will need to install OpenOffice Writer on the machine where the editor will be run. OpenOffice is a free to use Open Source office suite from Sun Microsystems and it can be downloaded from http://www.openoffice.org

Once OpenOffice has been installed, you can download Inforama studio from http://sourceforge.net/project/showfiles.php?group_id=229527. Download the file InforamaStudio.zip and extract it to a folder on the local file system.

There are 3 different startup files depending on which version of OpenOffice you are using and whether you are running Windows or Linux.

Windows UsersFor users of OpenOffice 2.x, open the file run-oo2.bat in a text editor and set the path to the OpenOffice directory. The default entry is SET OOPATH=C:\Program Files\OpenOffice.org 2.4. This will need to be changed to the path where OpenOffice was installed. Now you can double click the run-oo2.bat file to launch Inforama studio.

For users of OpenOffice 3.x, open the file run-oo3.bat in a text editor and set the path to the OpenOffice directory. The default entry is SET OOPATH=C:\Program Files\OpenOffice.org 3. This will need to be changed to the path where OpenOffice was installed. Now you can double click the run-oo3.bat file to launch Inforama studio.

Linux UsersFor users of OpenOffice 2.x, open the file run-oo2.sh in a text editor and set the path to the OpenOffice directory. The default entry is OOPATH="/usr/lib/openoffice". This will need to be changed to the path where OpenOffice was installed. Now you can double click the run-oo2.bat file to launch Inforama studio.

There is a problem with locating the OpenOffice program on some Linux distributions. This can be resolved by adding a symbolic link to the OpenOffice program folder from the root directory as follows...

ln -s /usr/lib/openoffice/program/soffice /soffice Work on the Linux shell script for OpenOffice 3 is underway.

Once started, the Inforama Studio application will appear as shown in Figure 11.

10 Chapter 2 – Getting Started

http://sourceforge.net/project/showfiles.php?group_id=229527


Quick Tour of Inforama StudioInforama Studio is a docking application with the main document editor occupying the centre content frame. The application docking frames can be seen in Figure 2 below.


Figure 1: Inforama Studio Application

Frame # Description

1 – Toolbar Shortcut toolbar for quick access to application functions.

2 – Documents Frame List of documents contained in the current project. Documents can be opened for editing by double-clicking the document name in this frame. When a new document is created in the editor or is imported into the project it will appear automatically in this frame.

3 – Acrobat Fields Frame When editing Acrobat Forms, the acrobat fields contained in the Acrobat Form are listed in this frame. The icon beside the acrobat field indicates whether the acrobat field is a text field, a check box, an image, or a bar code. The Acrobat Field Value text area at the bottom of this frame is where data bindings and evaluations are defined. When a binding is created by double-clicking the data field list in the Data frame described below, it will appear in this text area.

4 – Main Document Editor When a new document is created or is opened by double-clicking a document in the documents frame described above, it will appear for editing within this main content frame. There are two main types of document which can appear in this frame – OpenOffice Documents or Acrobat Forms. When an Acrobat Form from OpenOffice document is opened in this editor there is the option to switch between document and Acrobat Form mode.

5 – Data Frame Datasets defined within the Inforama project are listed here and can be


Figure 2: Main Windows in Inforama Studio

previewed in the table. When bindings are required within documents the fields within this frame can be double-clicked in order to create them. This frame also contains buttons at the bottom to allow fields to be formatted using the data formatters within Inforama.

6 – Parameters Frame When generating documents, parameters are provided which are used by the datasets in order to retrieve the relevant datasets. These parameters are added and removed within this frame. Parameters can also be bound directly to documents allowing them to be send directly to the document generation engine. As with the Data frame, a button at the bottom of this frame allows access to the data formatter.

7 – Properties Frame When editing Acrobat Forms this frame is populated with Acrobat Field properties when an Acrobat Field within the document is selected. Different properties will appear depending on the type of Acrobat Field selected. Properties can be changed from here and will be applied to the document when it is saved.

Creating a new Inforama ProjectA new Inforama project can be created by clicking the File -> New Project... menu or by clicking the New Project toolbar button as shown in Figure 3

This will present the user with the New Project dialog as shown in Figure 4.

Locate the folder where you wish to create the new project and enter the name of the project. Click the Create button to create the project. When this has been done the inforama project file will be created in the specified directory.

Once a project has been created the user can begin to create project resources such as documents, data


Figure 3: New Project Toolbar Button

Figure 4: New Project Dialog

sources and datasets.


C h a p t e r 3 – D a t a S o u r c e s a n d D a t a s e t s

A data source provides a connection to data that can be used throughout a project. Currently the only data source type supported in Inforama is the JDBC type. Inforama, however, has been created in such a way that data sources can be quite easily added which may give access to data from spreadsheets, Hibernate or other data sources.

Creating a new “JDBC Connection” data source.The most common example of a data source is a JDBC Connection. This data source handles a database connection and allows a dataset object to be created which stores the results SQL queries.

Before creating a new JDBC Connection data source make sure that the jar file containing required JDBC driver is in the classpath. To add a new driver to the class path select the Options -> Set Classpath... menu option and locate the required JDBC driver JAR file using the Set Classpath dialog shown in Figure 10.

Once this is done you can create a new JDBC Connection data source. In order to do that select the Data -> Connection/Data Sources menu item. The dialog listing existing data sources of the project will appear as in Figure 12.

15 Chapter 3 – Data Sources and Datasets

Figure 5: Importing a JDBC driver

Click the New button to bring up the New Datasource dialog that will allow to set up a new data source as shown in Figure 9.

Choose a JDBC Connection data source type and click Next. The configuration dialog will appear as in Figure 8.


Figure 6: Dataconnections dialog

Figure 7: Dataconnection types dialog

Specify a unique connection name, fully qualified driver class (e.g. for MySql -> com.mysql.jdbc.Driver), connection URL, user name and password. You can test the configured connection by pressing the Test Connection button.

Please note that the New Datasource screen has a drop down list of configurations for some common JDBC drivers. Importing a JDBC driver in the classpath dialog will not mean that the JDBC settings will be listed. If the setting for the JDBC driver you wish to use are not listed then it just a matter of overwriting the information in the text fields.

Once this is done press the save button, the new JDBC data source will appear in the list of available data sources.

Creating Parameters.In most cases datasets will be created from queries which will have one or more parameters specified. So before creating a dataset, open the parameters frame on the bottom right of the Studio application and click the add parameter icon. Enter the name of the parameter you wish to add, click OK and the new parameter will appear in the list as shown in Figure 5 below.


Figure 8: JDBC Configuration Settings Dialog

Figure 9: The Parameters Frame

Creating a new “JDBC Connection” data set.A dataset stores data which has been retrieved via a data source. For instance, in case of JDBC Connection data source, the relevant data set object (JDBC Data set) stores the result of an executed query. The relationship between data sources and datasets is “one-to-many”.

To create a new data set click the Data –> Datasets menu item and the JDBC Dataset configuration dialog will appear as in Figure 6.

Edit the query which needs to be executed to retrieve the data. If you wish to add a parameter to the query click the Add Parameter button and the dialog shown in figure 7 will appear.

Select the parameter you wish to add to the query and click the OK button. The parameter will appear in the query in the format $P{policy_id}. This parameter will now need to be specified when generating a document which uses the created dataset.


Figure 10: Dataset Configuration Dialog

Figure 11: The Add Parameter Dialog

In the Datasets dialog specify a name for the new data set query and select the underlying JDBC Datasource object. Once this is done press the Save button to store the specified JDBC Dataset properties. The created data set can now be used throughout in a project.

Using datasources and datasets.Once datasets have been configured you can refer to them from them from your project,either by binding them, in case of PDF documents, to Acrobat fields or by inserting them directly into a document, in case of OpenOffice documents.

The following syntax should be used: $F{[dataSet].[dataField]},– [dataField] is the name of the data field whose value should be inserted – in case of JDBC Dataset

this would be the name of the column of the underlying SQL query execution result.– [dataSet] is the name of the Datasource object.

Inserting the datasets can be simplified in the editor by double-clicking the name of the data field in the Data frame – the selected data field will be either inserted into current Open Office document or bound to the currently selected Acrobat field of a PDF document.

If more than one dataset has been created in the project it's possible to switch them in the Data frame using the dataset hyper link as shown in figure 11 below.


Figure 12: Binding Data Within Inforama Studio

If you wish to preview the data in the Data frame you can do so by clicking the parameters button on the bottom of the frame.

The dialog shown in figure 13 will appear with a list of parameters which are in use by the dataset.

In this case there is only one parameter specified in the dataset. Enter a value for it and the data will appear in the table as shown in figure 14 below.

In some cases it may be necessary to specify a dataset field using the table qualifier. This may happen when two fields of the same name but from different tables are returned from the query. Click the table icon in the Data frame as shown below.


Figure 13: The Datasets Menu

Figure 14: Parameters Icon

Figure 15: Parameters Specification Dialog

When toggled, the fields in the Data frame list will be prefixed with the table from which they originate as shown in figure 15 below.

Now whenever a field is inserted into a document it will be be inserted in the format F{[dataSet].[dataTable].[dataField]}


Figure 16: Previewing Data in the Data Frame

Figure 17: Tables Icon

Figure 18: Data List with Table Prefix

Creating a new “Spreadsheet” data source.Since version 1.2

To create a spreadsheet data source, you need to have a spreadsheet containing data which you would like to use in the documents created in Inforama. An example is shown below in figure 16. Any spreadsheet which is to be used as a datasource needs to have it's data starting in the first row and the first column with the first row containing the names of the columns.

Open the New Datasource dialog as shown in Figure 9 and select Spreadsheet file as the datasource type. Click the next button to continue.

On the next screen as shown below in figure 17 enter the name of the datasource and locate the spreadsheet file which is to be used.


Figure 19: Spreadsheet to be used as a datasource

Click the save button and the new spreadsheet datasource will appear in the dialog listing project datasources as shown in figure 12.

Creating a new “Spreadsheet” data set.A dataset based on a spreadsheet datasource can be created in much the same way as a dataset derived from a database datasource. To do this click the Data –> Datasets menu item and the Dataset configuration dialog will appear as in Figure 18.

Begin by selecting the spreadsheet datasource in the dropdown list on the top left of the page. In order to extract data from the spreadsheet, you write an SQL-like statement. In the example above the statement is


Figure 20: Spreadsheet configuration page

SELECT * FROM sheet1 where EmailOptOut = ''

This is very similar to SQL for databases with the limitation that only one condition can be used in the statement.

Click the Execute button and the list of fields will be listed on the right of the page. Now click the Save button and the new dataset will appear in the Existing datasets list on the left.

This dataset can now be used throughout the studio to embed data and letters and PDF forms in the very same way as a database dataset is used.

Creating custom datasources and datasets.In order to create a custom Data Source object a class implementing the org.in4ama.datasourcemanager.DataSource interface must be created as well as relevant implementors of the org.in4ama.datasourcemanager.DataSet object.

The example below shows how to write a wrapper for a JNDI Data source, which can be used to fill documents with data on a server side.

The class below extends a AbstractDataSource class which is just an abstract skeleton implementation of the DataSource interface.

public class JndiDataSource extends AbstractDataSource {

[...]


Figure 21: Creating a spreadsheet dataset

/** * Create a dataset defined by the specified QUERY. */ public DataSet createDataSet(DataSetConfiguration dataSetConf) { String dataSetName = dataSetConfiguration.getName();// get the QUERY property which will be used to build a ResultSet. String query = (String) dataSetConf.getProperty(QUERY).getValue(); DataSet dataSet = null; Connection conn = null; Statement stmt = null; conn = dataSource.getConnection(); ResultSet rs = stmt.executeQuery(query);

// since the JdbcDataSet uses ResultSet there is no need to create a new DataSet // object dataSet = new JdbcDataSet(dataSetName, this, rs); return dataSet;}

/** * Sets up all required properties. */ public void initialise() {// JNDINAME is the sole property of this data source jndiName = (String) properties.get(JNDINAME);// look up the JNDI data sources. InitialContext ctx = new InitialContext();// store it for the later data retrieval dataSource = (DataSource) ctx.lookup(jndiName); }

[...]

}


C h a p t e r 4 – O p e n O f f i c e L e t t e r s a n d L e t t e r F r a g m e n t s

Inforama Studio allows users to create letters, letter fragments and emails. This is achieved by embedding and automating OpenOffice Writer within the Inforama studio application. OpenOffice Writer is a powerful and full-featured competitor to Microsoft Word with most of the features plus a few more.

The OpenOffice Writer embedded in Inforama Studio can also be used to generate PDF letterheads and Acrobat Forms. For more on this see Chapter 6 (Acrobat Forms from OpenOffice Documents).

Inforama studio has been designed in such a way that the editors to create the XHTML required for generating the PDFs can be replaced with relative ease. This may facilitate such replacements in the future but for the moment the best option for generating the XHTML is the OpenOffice Writer word processor.

Creating OpenOffice LettersIn order to create a new OpenOffice letter select File -> New document... from the menu which will bring up the New Document dialog where you can specify the document's name and type as shown in Figure 22.

Once this is done the new document will be listed on the left-side Documents frame and will become a part of the current project.

26 Chapter 4 – OpenOffice Letters and Letter Fragments

Figure 22: New Document Dialog

Double-click the document's name on the list to open an embed OpenOffice editor.

Adding Parameters to LettersParameters can be added in the Parameters Frame. Click the add parameter button and enter the name user_name as shown in Figure 24.

A parameter can then be added to the open document by double-clicking the parameter name in the parameters frame. The parameter will then appear in the letter enclosed in curly braces using the syntax $P{user_name}. As shown in Figure 25.

In order to preview the document, click the Project -> Manage Documents menu item and the Letter manager dialog will appear as in Figure 26.


Figure 23: Documents Frame

Figure 24: The Parameters Frame

Select the modified letter in the master documents tree and click the right arrow to move it to the Selected Fragments list. Click the Preview button and the PDF preview dialog will appear, Before the document will render however, it's necessary to specify any required parameters as shown in Figure 27.

Select the parameter and click the modify parameter button. Enter the value of the parameter and the document will generate with the entered value replacing the parameter placeholder in the document as shown in Figure 28.


Figure 25: Parameter Added to a Letter

Figure 26: The Letter Manager Dialog

Figure 27: The Parameters List in the PDF Preview Dialog

Adding Data Fields to LettersData placeholders can be added to letters in much the same way as parameters outlined above. In order to start using data fields data sources and datasets need to be created as outlined in Chapter 3 (Data Sources and Datasets). Select a dataset from the link in the Data frame and click the down arrow to list the fields in the dataset as shown in Figure 29.


Figure 28: Letter Generated with the Specified Parameter Value

When the data fields have been listed in the Data Frame they can be double-clicked in order to create the data placeholders in the active document. The data placeholders will be in the format $F{first_name} as shown in Figure 30.

Again the modified document can be previewed using the Letter Manager dialog. The generated document is displayed in Figure 31.


Figure 29: The Data Frame

Figure 30: Inserting Data Placeholders in Letters

Creating Letter FragmentsLetter fragments are essentially the very same as Letters but in categorising them separately it's more obvious what their role is within a project. To create a letter fragment select File -> New document... from the menu which will bring up the New Document dialog where you can specify the fragment's name and type as shown in Figure 32.


Figure 31: Previewing Data Fields in the Letter

Once created the new fragment will open in the OpenOffice editor and can be edited in the same way as a letter and it will also be added to the document tree as shown in figure 33 below.

In order to preview how letter fragments will appear open the Letter Manager Dialog as shown in figure 23 and select the From Fragments check box. The documents tree will be replaced with the fragments master list. Select the fragments you wish to appear in the document and click the Preview button to generate it.


Figure 32: Creating a new Letter Fragment with the New Document Dialog

Figure 33: The new letter fragment in the document tree


Figure 34: Selecting letter fragments in the letter manager dialog

C h a p t e r 5 – W o r k i n g w i t h A c r o b a t F o r m s

Creating and binding Acrobat Fields.Inforama studio allows to create and modify Acrobat fields when working with a PDF document. Acrobat forms can be created within the studio application by creating an OpenOffice document first and converting it to PDF. For more on this see chapter 6 - 'Acrobat Forms from OpenOffice Documents'.

In many cases however, users will want to import Acrobat forms or PDFs that have been created by third parties or using other graphic design tools such as Adobe Illustrator. In order to do this click the File -> Import Document menu item and the dialog shown in figure 35 below.

In the dialog select Acrobat Form or PDF as the import type and locate the document you wish to import into the project. The Import as text field allows you to import the file using a different file name. Click the import document and the document will be copied to the current project and opened for editing in the Document frame.

Once opened a list of the Acrobat form's fields will be listed in the Components frame on the bottom left of the Studio as shown in figure 36 below. The Data Value text area is where bindings for the various fields is specified. Each Acrobat field can be bound to any of - fixed value, parameter, data field, expression or any combination of these. Figure 36 shows an Acrobat Form being edited with Inforama Studio.

34 Chapter 5 – Working with Acrobat Forms

Figure 35: The import document dialog

When an Acrobat field is selected, it's properties will be listed in the Properties Frame as shown below in Figure 41. A number of the properties such as name, x, y, width, height and data are common to all Acrobat field types and some are field specific such as the checktype and checkmark color properties shown for the check box field.


Figure 36: Editing Acrobat forms

Figure 37: Acrobat field properties frame

Creating new Acrobat Fields within the StudioIf new Acrobat fields needs to be added to an existing Acrobat this can be done within the Studio. The Acrobat form editor includes a toolbar which allows the user to add new text fields, barcodes, images and check boxes. It also allows the user to select the page of the Acrobat form they are working on as well as zooming in and out of the form and removing existing fields. The lock button prevents fields from inadvertently moving when the user selects them.

To create a new Acrobat field click the button corresponding to the type of field to be created and then click the Acrobat form in the location where it should be positioned. The fields will always be created with the same dimensions but can be resized and moved.

Acrobat Field binding typesThere are four supported types of Acrobat field bindings, each of which defines how the bound value will be interpreted when generating a final document.

Text field bindingThis is the simplest type of binding. Simply type the text that you want to appear in the Data Value text area and this will be used when generating the PDF. A sample binding and a preview of the final document can be seen in Figure 39 below.


Figure 38: The Acrobat form toolbar

Image binding There are several ways to bind to an image. The most basic is simply to enter the path to the image and this image will be inserted into the image field when the document is created as shown in figure 40 below.

Similarly, it is possible to embed an image which is retrieved via a http connection for example 'http://in4ama.org/images/in4amalogo.jpg'


Figure 39: Entering a Text Value Binding

http://in4ama.org/images/in4amalogo.jpg

If you wish to make different images appear depending on parameter or field values this can be done by embedding some Groovy scripting such as...

$E{ $P{useimg}.equals("yes") ? "http://www.openedgesoft.com/images/openedgelogo.jpg" : "http://in4ama.org/images/in4amalogo.jpg" }

Now with this syntax different images will appear depending on the useimg parameter.


Figure 40: Binding an image field to a file

It is also possible to embed an image from a BLOB field in a dataset. When a BLOB field is returned as part of a query you can specify that the field should be used by referring to the field with the syntax $F{field_name}.

Barcode bindingDisplaying a barcode in the image field is a simple matter of creating a barcode field and specifying what data is to be encoded in the Data Value text area. Figure Error: Reference source not found shows how this is specified in the editor and Figure shows how it appears when generated into a PDF.


Figure 41: Different images depending on parameter

Checkbox binding This will display a check box which can toggle between two states: on and off, depending on the bound value. Figure 38 below shows how the state of the check box can be set with either of the values 'on' or 'off'. The same can be achieved with the values 'yes' or 'no' and 'true' and 'false'.

As with the image binding the state of the check box can be set depending on the value contained in parameter or field values.

For example the value $P{useimg} will evaluate to either 'yes' or 'no', changing the state of the check box in the document.


Figure 42: Creating barcodes


Figure 43: Setting the state of a check box

C h a p t e r 6 – A c r o b a t f o r m s f r o m O p e n O f f i c e D o c u m e n t s

Sometimes it's necessary to create documents which have a more exact layout than can be achieved with an OpenOffice document on it's own. It's possible within Inforama Studio to create an OpenOffice document which is converted to an Acrobat Form before data binding is carried out on it. This makes it possible to position document elements more precisely within OpenOfice and to limit the size of the elements.

Scenarios where this might be useful are where textfields are given an absolute position within a document or where document frames are used to position content.

Creating an Acrobat Form from OpenOfficeStart by selecting File -> New document... from the menu and the New Document dialog will appear allowing you to specify the document's name and type as shown in Figure 44.

Once this is done the new document will be listed on the left-side Documents frame and will become a part of the current project.

42 Chapter 6 – Acrobat forms from OpenOffice Documents

Figure 44: New Document Dialog

Figure 45: Documents Frame

Double-click the document's name in the list to open the document in the embedded OpenOffice editor. In order to illustrate the idea of absolute positioning of document elements we can look at the example of a motor insurance certificate where the tax disc will be printed onto perforated paper allowing it to be removed and placed in the windscreen of a car. An example of this type of pre-perforated paper is shown in Figure 46.

In order to place an element at the bottom of the document you will need to turn on the menu in the embedded OpenOffice editor. This is done by clicking the File button in the OpenOffice document editor as shown in Figure 47.

Now select Insert -> Frame... from the OpenOffice menu. The inserted frame can be positioned anywhere in the document and it's properties set using standard OpenOffice formatting.

Now make the OpenOffice Form Controls toolbar visible by clicking the OpenOffice View -> Toolbars -> Form Controls menu item. This will enable the Form Controls toolbar as shown in Figure 48.


Figure 46: Perforated Paper for Printing

Figure 47: Enabling the OpenOffice Menu

Create a table in the frame within which prompts and data will appear as shown below in Figure 49.

Now click the Text Box button on the Form Controls toolbar and draw Text Boxes in the second column of the frame.


Figure 48: OpenOffice Form Controls Toolbar

Figure 49: Basic Table with Prompts

The inserted Text Boxes can be formatted by double-clicking them. The properties dialog for the selected component will appear as in Figure 50.

Switching to the Acrobat Form ViewSave the document and switch to PDF mode by clicking the PDF icon at the top of the OpenOffice editor page as illustrated in Figure 51.

Now the document will be exported as a PDF and re-opened in the Acrobat Form editor as shown in Figure 52. It's important to note that when editing Acrobat forms in this mode any changes apart from the databindings will be lost when you switch back to the OpenOffice view and save the document again. If the position, name or any other properties need to be changed these changes should be made to the OpenOffice document and not to the exported PDF file.


Figure 50: Formatting Text Boxes

Figure 51: The PDF Button on the OpenOffice Editor

On the left hand side of the editor the Acrobat Fields frame is populated with a list of the AcfoFields found within the Acrobat Form. You can select an Acrobat Field by selecting it in the list or by clicking it within the editor. The properties frame on the right hand side of the editor displays a list of properties for the currently selected Acrobat Field.

Binding to the Acrobat FieldsNow you can begin the task of binding data to the Acrobat Fields. Display the Data frame and click the arrow to display a list of the fields in the list as shown in Figure53. Double-click a field name in the Data frame and the binding will appear in the Acrobat Field Value text area in the Acrobat Fields frame. The data field will appear in the format $F{dataset.fieldname}.


Figure 52: The Exported Acrobat Form

Previewing the DocumentNow you can preview how the document will appear when generated by selecting the Project -> Manage Documents... menu item. The Document Manager dialog will appear as in Figure 54.

Select the document from the main list of documents in the center of the dialog and click the right arrow to


Figure 53: Binding Database Data to an Acrobat Field

Figure 54: The Document Manager Dialog

make it appear in the Selected Fragments list. Now click the Preview button and the document will be generated within the Document Preview dialog as shown in Figure 45.

Different rows within the dataset can be previewed by modifying the parameters within the dialog.


Figure 55: Previewing the Document in the Editor

C h a p t e r 7 – E d i t i n g E m a i l sWhen PDF documents have been generated it may be necessary to email them to customers or other parties. In these cases it would be desirable to create a template for the email body or the text that arrives in the mailbox of the recipient. This can be done in the same way that OpenOffice letters are created within Inforama studio.

Creating an Email Document from OpenOfficeStart by selecting File -> New document... from the menu and the New Document dialog will appear allowing you to specify the document's name and type as shown in Figure .

The Email document will appear in the Documents frame on the left hand side of the studio application and will become part of the current project as shown in figure 56.

Double-click the document's name in the list to open the document in the embedded OpenOffice editor. Now you can simply edit the OpenOffice document as normal and insert data and parameter placeholders as you

49 Chapter 7 – Editing Emails

Figure 56: Create the Email with the New Document Dialog

Figure 57: New Email in the Documents Frame

would for the OpenOffice Letter editing.

Previewing EmailsYou can preview the emails you have created by emailing them to your own email account but before that can be done you will need to configure the SMTP settings in the project properties dialog. Click the Project -> Properties menu item or click on the project properties button on the main application toolbar as shown in Figure 58.

The Project Properties dialog will appear as shown in Figure 59.

Click on the email node in the tree on the left hand side of the dialog and the SMTP settings will appear in the main content area. The following information can be set...


Figure 58: The Project Properties Toolbar Button

Figure 59: Project Properties Dialog

Setting Description

SMTP Server The server through which emails will be sent

SMTP User The user name required for authentication by the SMTP server

SMTP Password The password for the user authenticating against the SMTP server

From address The address which will appear in emails sent via Inforama for this project

Reply to address When a user choses to reply to an email sent from Inforama, this is the email address to which it will default.

At the top of the embedded OpenOffice editor you will see an email toolbar button as shown in 60.

Click this button and the Email Parameters Dialog will appear as in Figure 57 below.

Enter the email address to which you wish to send the email and the subject which is to appear. In the Parameters frame, a list of parameters which the email references is included. Enter valid values for each parameter that appears in this list. Click the send email button and the email will be sent to the specified email address with data and parameters replaced throughout the email document.


Figure 60: The Email Preview Toolbar Button

Figure 61: The Email Parameters Dialog

C h a p t e r 8 – I t e r a t i n g D a t a s e t s

Accessing database data (DataSources and DataSets)Data Sources define physical connections to the databases and can be registered either with JDBC or JNDI. Each data source is tasked with producing datasets which, in case of SQL database, are the light wrappers for JDBC ResultSet objects.

The syntax for accessing the datasets within documents is as follows:

$F{[data_set_name].[data_field_name]},

where– [data_set_name] – is the name of the data sets.– [data_field_name] – the label of the column in the SQL query that was used to create the data set.

The reference $F{[data_set_name].[data_field_name]} will return the value in the [data_field_name] column in the current row of the underlying ResultSet object.

Example: An example of a data set defininition (datasets.xml file) is shown below.

<dataset name=”allUsers” datasource=”some_db”><property query=”select * from users”/>

</dataset>

The definition above defines a dataset named allUsers which will basically contain all rows from the users table from the database defined by the Users data source.

Data Set IterationThe syntax for iterating over the rows contained in a data set is as follows.

$beginIteration{[data_set_name]}some content to be iterated, e.g $F{allUsers.firstName}

$endIteration{[data_set_name]}

For example, a data set “allUsers” as above can be used in the template definition as shown in Figure 62 below

52 Chapter 8 – Iterating Datasets

For a two rows Users table the generated document will appear as in Figure 63 below.


Figure 62: Iteration Defined Within OpenOffice Document

Figure 63: PDF Preview of Iterated Elements

Nested Data Set IterationIn some cases it is required to iterate over data sets which depend on another (e.g. in case of“one-to-many” relationship between database tables).

For example we may want to generate a document listing all departments (stored in the Departments database table) and for each department list all its employees (stored in the Emloyees database table). In this case the data sets defintion may look as shown below:

<dataset name=”departments” datasource=”some_db”><property query=”select * from Departments”/>

</dataset>

<dataset name=”emps” datasource=”some_db”><property query=”select * from Employees where Users.departmentId=$F{departments.departmentId)”/>

</dataset>

The definition above specifies that each time the usersInDepartment data set is to be created the defining query will be filled with the id of the current department (as defined by the departments data set).

The screenshot in Figure 64 below shows an example of nested iteration defintion. The generated document will list all departments with its employees.


Table Row IterationThe syntax for iterating over data sets that are to be shown in a table rows is as follows:

$iterateCells{[data_set_name]}some content inside a table row to be iterated.

This type of iteration inside OpenOffice documents is show in Figure 65 below.


Figure 64: A Nested Iteration

The $iterateCells tag indicates that within the boundaries of a loop only the table rows should be iterated rather than entire table.

For the example above the generated document appears as in Figure 66 below.


Figure 65: Iterating Tables in OpenOffice Documents

Table Cell IterationIn some cases, when iterating over data sets, it is required to insert data to successive table cells. In order to that the following syntax should be used.

$iteateCells{[data_set_name], [num_cols]}some content inside a table cell to be iterated

The num_cols parameter defines the number of columns that should be created in the result table. The data_set_name parameter specifies the name of the data set to be iterated.This type of iteration inside OpenOffice document is shown in the Figure 67 below.


Figure 66: Generated Table Previewed in PDF

The $iterateCells tag indicates that the first occurence of the table cell definition should be used during the iteration.

For the example above the generated document appears as in Figure 68 below.


Figure 67: Iterating Table Cells in OpenOffice Documents

Figure 68: Generated Table Previewed in PDF

C h a p t e r 9 – D a t a F o r m a t t i n gMuch of the time simple formatting is sufficient to display the information provided by a dataset or parameter data. There will be times, however when you will need to manipulate the data from these sources into a format more suited to the documents you are generating. This is where data formatters come into play.

Basic FormattersThere are a number of basic formatter objects which are included by default with Inforama. In order to view these you can click the formatter button on the data frame as shown in Figure 69.

Select a data field in the data table and click the data formatter button. The data formatter dialog will appear as in Figure 70.

There are five default formatters built into Inforama – Date, Time, String, Number and Currency. When a formatter is selected on the left-hand side of the dialog a list of formatter masks will appear in the list on the right hand side of the dialog. Selecting one of these will change the Format Mask text field. The Expression text area at the bottom of the dialog provides a preview of the text that will be inserted into the document in order to carry out the formatting. This uses the following syntax...

59 Chapter 9 – Data Formatting

Figure 69: The Data Formatter Button in the Data Frame

$E{$V{DateFormatter}.format($F{policies.address_town}, "dd MM yyyy")}

The entire expression is contained within $E{...}. This identifies it as a Groovy Expression. For more information on working with Groovy go to http://groovy.codehaus.org. The value $V{DateFormatter} specifies the variable that is used to evaluate the expression. In this case the DateFormatter variable is mapped to the class org.in4ama.documentengine.format.DateFormatter. We will see how this is done and how it can be customised in the next section

Creating a custom data formatter When you create a new project, a file named variables.xml is created in the root directory of the project. The format of this file is as follows...

<variables> <variable name="DateFormatter" class="org.in4ama.documentengine.format.DateFormatter" /> ...</variables>

The name attribute specifies the name that is used throughout Inforama for the individual formatters. In the example above the DateFormatter variable is used to represent the org.in4ama.documentengine.format.DateFormatter class file. It's possible to create a custom class for data formatting by creating it in the editor of your choice. As an example we can create a BooleanFormatter which will determine whether a checkbox on an Acrobat form will be checked when generated.

The following BooleanFormatter class file is created which has the static method format. This returns a true or false which determines whether the checkbox should be checked or not. It also accepts two parameters,


Figure 70: Data Format Wizard Dialog


value and format. The value parameter is the field, parameter or absolute value which is sent into the function. For the purposes of this example the format parameter can be ignored.

package com.openedgesoft.formatters;

public class BooleanFormatter {

public static boolean format( String value, String format ) {if ( value.equals( "1" ) ) {

return true;} else {

return false;}

}

}

Once created, the class can be bundled into a jar file. This should be a relatively simple process if using an editor such as Eclipse or NetBeans. Now, in order to reference the new formatter class from your project, click the Options -> Set Classpath... button within Inforama Studio and the dialog shown in Figure 71 will appear.

Click the Add Jar button and locate the jar which you created. The path to the jar file will now appear in the dialog as shown in Figure 71 above. Click the Save Classpath button and click the dialog will be hidden. Now open the variables.xml file in a text editor and add the following line to it...

<variable name="BooleanFormatter" class="com.openedgesoft.formatters.BooleanFormatter" />


Figure 71: The Classpath Dialog

Using a Custom FormatterRestart the editor and you will be able to start using the custom formatter. Open an Acrobat form as shown in Figure 72.

In Figure 72 a checkbox field is selected in the main editor. In the Components Frame the following text is entered into the Data Value text field...

$E{$V{BooleanFormatter}.format($F{policies.cheque_to_account}, "")}

As you can see the class com.openedgesoft.formatters.BooleanFormatter is represented by the variable BooleanFormatter throughout the project making it easier to reference. The very same could be achieved with the following code...

$E{com.openedgesoft.formatters.BooleanFormatter .format($F{policies.cheque_to_account}, "")}

However the method of associating variables with formatters make the expressions much less verbose.


Figure 72: Using the Custom Formatter in an Acrobat Form Binding

C h a p t e r 1 0 – M a n a g i n g D o c u m e n t s a n d P a c k s

When the work of authoring documents and emails has been completed it may be desirable to organise them into packs which can be generated in a single call. The Document Manager and Pack Manager built into Inforama allows the user to do just this.

Managing DocumentsTo launch the document manager click the Project -> Manage Documents... menu item. The dialog as shown in Figure 73 will appear.

There are two different types of documents which can be created within the Document Manager Dialog – From document fragments or from a single document.

Creating a Single DocumentCreating a single document is very straightforward. You simply select the document you want to generate from the main list of documents and click the right arrow to move it to the Selected Fragments list. This is

63 Chapter 10 – Managing Documents and Packs

Figure 73: Document Manager Dialog

sufficient to generate a single document. Now click the Preview button and the generated document will appear in the document preview dialog.

Creating Compound Documents from Letter FragmentsA single document can be created from a series of document fragments. Take for example the two letter fragments shown in Figure 74. These fragments can be merged into a single document which will be rendered into a PDF document.

In order to merge these to Letter Fragments click the From Fragments checkbox in the Document Manager dialog. The Document Fragments contained in the project are displayed in the list as shown in Figure 75.

Select the fragments you wish to include in the document and click the right arrow to move them into the selected fragments list. The order of the fragments can be amended by click the up and down arrows on the right of the dialog. Now the Preview button can be clicked and the generated document will appear as shown in Figure 76.


Figure 74: Letter Fragments Within the Editor

Figure 75: Managing Letter Fragments

Working with the Preview DialogWhen a document is first displayed in the preview dialog, any required parameters need to be input before it is generated. In order to do this click the Modify button as shown in Figure 77. Any further modifications to the parameters in this list will result in the document being generated once again.

The preview dialog offers the user various options to manipulate the generated PDF document. Along with the various zooming buttons there are also the following options.

Icon Function Description

Refresh Regenerate the displayed document.

Print Print the generated document

Save Save the generated document. The user will be asked to specify the location to which the PDF file should be saved

Display in Acrobat

This button is enabled once the generated document has been saved. Click this button to launch the saved document in the default PDF viewer. This is usually Adobe Acrobat.


Figure 76: Preview the Generated Letter Fragments Document

Figure 77: Document Parameters

Generated PDF documents can consist of more than a single page. Each page can be displayed by clicking the page number in the pages list on the top left of the dialog as shown in Figure 78.

Associating Emails with DocumentsWhen generating documents and sending them via email, the body of the email is specified by an OpenOffice document created within the studio. Any of the emails within the project can be selected from the Email Template dropdown list in the Document Manager dialog as shown in Figure 79.

Now when this document is generated and the email action is specified the body of the email will contain the content of the mailshot document.

Setting the Background DocumentFor any document or compound document, a background can be applied. In order to do this select the document required for the background from the Background dropdown list in the Document Manager dialog.

Taking the document fragments generated in Figure 76 above, selecting a background and previewing it will result in a document such as shown in Figure 80. Note that the text in the Letter Fragments documents needs to be moved down in order accommodate the content of the background.


Figure 79: Specify the Email Template

Figure 78: The Pages List

Applying Display ConditionsFragments can be included or not depending on the values of variables, fields or parameters. This is done by specifying the display condition in the Display Condition textarea in Figure 73 above. For example the condition text $E{$F{policyds.contains_named}.equals(“1”)} will evaluate and display if the result is true but will not if the result is false.


Figure 80: Applying a Background to a Generated Document

C h a p t e r 1 1 – P r i n t i n g

There are a number of ways in which the documents generated in Inforama can be printed. In order to see these options open an Inforama project within Inforama Studion and click the Project -> Properties menu item. The dialog shown in Figure will be displayed.

The Printer Type dropdown list provides the user with options for how generated documents will be printed by Inforama. Selecting any of these options will change the Printer Class edit field. This is the class which will be invoked when PDF are printed.

The options offered by Inforama by default are as follows.

Acrobat CommandThis will send a print command to Adobe Acrobat. In order to do this the full path to the Adobe Acrobat Reader application needs to be entered into the Acrobat Path edit field. Note that when PDF files are printed in this way the Adobe Acrobat Reader will be launched in the background. Only one instance of this application will be launched no matter how many files are printed during a session.

Foxit CommandThis is very similar to the Acrobat Command described above except that it uses the Foxit PDF reader to print the generated documents. In this case specify the path to the Foxit reader in the Application Path

68 Chapter 11 – Printing

Figure 81: Project Properties Dialog

text field.

This command will work with Foxit version 2.3 if a particular printer needs to be specified. If Foxit 2.2 is required then please contact OpenEdge about how to implement printing with this version.

For more information on Foxit go to http://www.foxitsoftware.com/pdf/rd_intro.php

JPedal PrinterJPedal is an open source library for rendering and printing PDF documents. Selecting this printing option will cause generated PDF documents to be loaded into the JPedal library and printed using it.

PDF Supporting PrinterThis is for use with printers that support the PDF format natively. When this is used generated PDF documents will be streamed directly to the printer.

Creating a Custom Printer ClassIf printing options other that those provided are required, it's possible to create a new printer class. The fully qualified class name can be entered into the Printer Class edit field. In order to create a custom printer class it's necessary to create a class which extends the org.in4ama.documentengine.print.Printer abstract class.

The abstract method printPDFs as shown below needs to be implemented in the custom class.

public void printPDFs(PDFPrintJob[] printJobs, String printServiceName)throws Exception {

There are two parameters to this method

Parameter Description

printJobs An array of print instructions which are required to be carried out.

printServiceName If specified, the name of the printer to use. If this isn't provided it's possible to get the name of the default printer using the lookupDefaultPrintService function.

69 Chapter 11 – Printing

http://www.foxitsoftware.com/pdf/rd_intro.php

C h a p t e r 1 2 – D o c u m e n t G e n e r a t i o n W i z a r d

Once documents and packs have been created, it's possible to start the process of generating documents from within Inforama Studio with actions to email, print and return. It's also possible to create mailshots which will get sent to multiple recipients. For more on how to define documents and packs within Inforama Studio see Chapter 10.

Generating Documents and PacksBegin by clicking the Project -> Generate Documents and Packs... menu item. The Document Generation Wizard dialog will appear as in Figure 70.

Make sure the Generate Documents or Packs radio button is selected. Select the packs or documents you wish to generate and click the next button. The second page of the dialog will appear as in Figure 83 below. There are three possible actions which can be carried out on the generated documents. They are as described in the table below.

Action OptionsEmail There are text fields for the To, CC and BCC addresses. If more than one

recipient is required in any of these fields they can be separated by commas.

70 Chapter 12 – Document Generation Wizard

Figure 82: Document Generator Wizard Dialog

Print This will print the generated document. If the Target text field is left blank then the document will print to the default printer. If you wish to print to a printer other than the default, the name of the printer can be specified in the Target field.

Return Clicking this checkbox will return the generated document to the client application where it can be saved, viewed and manipulated.

When all of the required actions have been specified, click the next button. The next page in the wizard displays any parameters that the document or pack being generated expects as shown in Figure 84. Enter valid values for the parameters and click the next button.


Figure 83: Specify the Actions

Click the next button and the screen shown in Figure 85 will be displayed.

Click the Show Document button and the preview dialog will be displayed as in Figure 86.


Figure 84: Specifying the Parameters

Figure 85: Final Wizard Page

Generating MailshotsOpen the generation wizard once again by clicking the Project -> Generate Documents and Packs... menu item. This time select the Run a Mailshot radio button as shown in figure 87.


Figure 86: Generated Document Preview

Figure 87: Document Generation Wizard - Running a Mailshot

A drop down list will appear at the top right of the dialog which lists the datasets contained within the project. Select the dataset that you wish to use. The dataset you use will need to contain an email address field that will be used to send the generated mailshot to similar to the following...

SELECT first_name, last_name, email1 FROM contacts c where email primary_address_city = '$P{mailshot_city}'

This is a query which has been executed against a sample SugarCRM 5 database. The field email will be used as the delivery address of the mailshot for each record found. The query also filters the records based on the city the customer is located in using the mailshot_city parameter which needs to be passed to the generation job. Other fields in the query such as first_name, last_name, etc can be used to populate data in the generated emails and attached documents if there are any.

In the dialog shown in figure 87 select the document you wish to be sent to each of the recipients. Click next to proceed to the next screen shown in figure 88.

On this screen select the document and then select the Email action check box. Now, because it's a mailshot to several customers, the recipient address isn't known in advance but it is contained in the dataset being used. So the way we tell the Inforama Engine to use the data set email field is to use the syntax $F{[datasetname].[email_field_name]}. In this example the value will be $F{mailshot.email1}.

Click the next button to proceed to the next screen which is shown below in figure 89. This screen is where


Figure 88: Specifying the recipient address

the parameters for the dataset, email and any documents which are included in the job are specified. One of the parameters is the name of the dataset to be used. In this example the dataset to be iterated is the mailshot parameter.

Click the next button to finish the wizard and send the mailshots.


Figure 89: Specifying mailshot parameters

C h a p t e r 1 3 – T a b l e F o r m a t t i n g

Since version 1.1

IntroductionIn many cases the basic iterators described in Chapter 8 – Iterating Datasets are sufficient for presenting data in a tabular manner. There may be times however, when more advanced formatting may be required in order to apply logic and present the data in a different way depending on the data, parameters or the context within which the table is being generated. This is where the advanced table formatting ablilities of Inforama come into play. These formatters also allow the user to ignore rows or columns or to embed complex objects withing table cells depending on the requirements.

The formatters can be manipulated using embedded Groovy scripting within documents or custom versions of the the built-in formatters can be created enabling users to carry out even more complex manipulation of the tables using Java code.

Getting started with Table FormattersIn order to make use of a table formatter it's necessary to create a single cell table within a document and then place the following instruction before the table.

$createTable{[datasetname], [list_of_formatting_handlers}}

Then insert the text $F{customers} into the table cell and format the cell and font with whatever properties and styles that you wish to use.

Figure 90 shows how the table is created and figure 91 shows a screenshot of the document when it is generated in the previewer.

This document was generated with the simple SQL statement SELECT * FROM customers. When the process outlined above is followed each row is iterated and each column found in the dataset is displayed.

76 Chapter 13 – Table Formatting

Figure 90: Creating the basic table template

Figure 91: Preview of the basic table

Using the same SQL statement it's possible to specify which columns appear in the table using the following embedded Groovy code.

$createTable{customers, $numCols{2}, $include{customers.column() == 'first_name' || customers.column() == 'last_name'}}

The createTable function is passed two new parameters. The numCols parameter tells the formatter how many columns will be used from the dataset to create the table. The include instruction allows the user to examine information in the dataset so that the required fields can be included in the table.

Sub TablesThere are times when it's desirable to embed tables within tables in order to product report like output. In order to do this we can create table within a table as shown in figure 93 below.

In this screenshot the parent table has two rows and four columns. The second row has been merged into a single cell within which is another single cell table. The table processing command for the parent table is before the table. It's font size has been reduced so as to make it less prominent. The command will be using the following accounts dataset.

SELECT id, name as Name, billing_address_city as City, billing_address_state as State, billing_address_postalcode as Postcode FROM accounts WHERE industry = 'Banking'

The command which appears before the parent table is

$createTable{accounts, $numCols{accounts.numCols() -1}, $columns{accounts.allCols().except('id')}, $step{*.(2)1=>false}, $cellSpan{0.(2)1=>accounts.numCols() - 1, *.(2)1=>0}}

The second table uses the following dataset called account_contacts.

SELECT first_name, last_name, title FROM contacts, accounts_contacts WHERE contacts.id = accounts_contacts.contact_id AND accounts_contacts.account_id =


Figure 92: Preview of the modified table

Figure 93: Sub table definition within a document

'$F{accounts.id}'

This dataset uses the accounts.id field from the parent dataset to retrieve the correct rows from the contacts table. The command before the sub table is as follows.

$createTable{account_contacts}

When this table is processed it will appear as shown in figure 94 below.

Using Table TemplatesIn the examples so far It has only been possible to apply formatting to a single cell so that whatever cells are created in the generated table will have that same style applied to them. In order to apply styles it's possible to create table templates which include formatting information which can be applied to individual cells. This formatting can be applied to both the font and the cells.

In order to create a new table template click the File -> New Template... menu item and the new template dialog shown in figure 95 will be displayed.

Enter the name of the template you wish to create, click the Create button and the new template will be created and listed in the project frame as shown in figure 96.


Figure 94: Sub table preview

The table template document is an OpenOffice document which should contain only the table which you wish to create a template for. Within the document create a table with the formatting that you wish to use as shown in figure 97.

Now re-open the document winin which the table will be generated and change the table instruction to

$createTable{customers, $numCols{2}, $include{customers.column() == 'first_name' || customers.column() == 'last_name'}, $template{if (context.row(2) == 0) return myTemplate1.at(0,0); else return myTemplate1.at(0,1);}}

This call now includes a fourth parameter which instructs the table formatter to use the table template. It uses Groovy scripting to determine whether the current row is even or odd and applies the format for the appropriate cell in the table template. In this way it's possible to mix styles from templates in different files.

Now when the document is generated within the previewer the output will look something like that shown in figure 98 below.


Figure 95: New Template Dialog

Figure 96: Table template listed in the project frame

Figure 97: Table Template

Applying header templatesThe example above doesn't have a header containing the column names but if a header is needed it's a simple matter of again using a tempate to apply the header style. The following table instruction will result in the column names being output as the table header using the specified template.

$createTable{contacts, $template{if (context.row() == 0) return myTemplate1.at(0,0);}, $step{context.row() > 0}, $value{if(context.row() == 0) return contacts.column(context.column());}}

This will output the table shown in figure 99.


Figure 98: Table template preview

Including Sub Table TemplatesIt is possible to create sub tables within tables in order to generate report style output. Begin by creating a new table template as shown below in figure 100.

Next create two datasets which will be output. Again we are using the sample SugarCRM database which has an accounts table, a contacts table and an accounts_contacts join table. The accounts query is shown below.

SELECT id, name as Name, billing_address_city as City, billing_address_state as State, billing_address_postalcode as Postcode FROM accounts WHERE industry = 'Banking'

Next we can define the sub query which will populate the sub table as follows

SELECT first_name, last_name, title, primary_address_street FROM contacts, accounts_contacts WHERE contacts.id = accounts_contacts.contact_id AND accounts_contacts.account_id = '$F{accounts.id}'

Now create a single cell table in the document as follows


Figure 99: Preview of table with header

Figure 100: Sub table template

$createTable{accounts, $numCols{4}, $include{accounts.column() != 'id'}, $template{if (context.row(2) == 1 && context.column() == 0) return myTemplate2.at(0,1);}, $includeCell{context.column() == 0 || context.row(2)!=1}, $step{context.row(2) == 0}, $value{if (context.row(2) == 0) return '$F{accounts}';}}

Manipulating tables from custom Java classesSome of the examples shown above are quite verbose in the way the tables are declared within the documents. It's possible to move some of this table formatting and manipulation into custom Java classes which can be included in the project. The following code shows a class that does just this.

package org.in4ama.tabletest.table;

import java.util.Properties;import org.in4ama.documentautomator.templates.TemplateRepository;import org.in4ama.documentengine.format.table.DataSetTableFormatter;

/** Defines formatting for table showing the "accounts" data set * For convenience it extends DataSetTableFormatter (implementation iterating the specified data set * is inherited). * */public class MyTableFormatter extends DataSetTableFormatter {

/** Don't include the ID column in the result table */ @Override public boolean isCurrentIncluded() { int currentCol = dataSet.getCurrentColumn(); return (!dataSet.getColumnName(currentCol).equalsIgnoreCase("id")); }

/** Gets the number of columns that should appear, * since we don't include the "id" column, subtract "1" from what would be * returned by default. */ @Override public int getNumCols() { return super.getNumCols() - 1; }


/** Change the column widths of the first and fourth column * (column indexes start with 0, hence "2" and "0" in the conditions) */ @Override public Properties getColumnProperties(int colIdx) { Properties properties = super.getColumnProperties(colIdx); if (colIdx == 2) { properties.put("column-width", "3cm"); } else if (colIdx == 0) { properties.put("column-width", "8cm"); } return properties; }

/** Change the properties of the cell contents in the first column, * use the "myTemplate1" template's first cell. */ @Override public Properties getCurrentContentProperties() { Properties properties = super.getCurrentContentProperties(); if (getCurrentColumn() == 0) { // get the template repository TemplateRepository templateRepository = evaluationContext.getProjectContext().getTemplateRepository(); // get the properties of the first cell from "myTemplate1" template. properties = templateRepository.

getTableTemplate("myTemplate1").getContentProperties(0, 0); } return properties; }

/** Change the properties of the cells in the first column, * use the "myTemplate1" template's first cell. For the other * cells use the properties of the first row's last cell in the * "myTemplate1" template. */ @Override public Properties getCurrentCellProperties() { Properties properties = super.getCurrentCellProperties();


// get the template repository TemplateRepository templateRepository =

evaluationContext.getProjectContext().getTemplateRepository();

if (getCurrentColumn() == 0) { // get the properties of the first cell from "myTemplate1" template. properties = templateRepository.

getTableTemplate("myTemplate1").getCellProperties(0, 0); } else { properties = templateRepository.getTableTemplate("myTemplate1").

getCellProperties(3,0); } return properties; }}

This class extends the DataSetTableFormatter class and overrides some ot it's methods. If you look at the function isCurrentIncluded the first thing to note is that access to the current dataset is provided via the dataSet variable. This allows us to tell what column and row is currently being processed.

Now if you look at the getColumnProperties method you will see that cell properties can be set which will affect the look of the cell. In this example if column 2 is being processed the width is set to 3 cm whereas if the current column is 0 the width is set to 8 cm.

The getCurrentContentProperties and getCurrentCellProperties functions show how table templates can be accessed via the TemplateRepository class allowing us to apply different styles depending on the row, column and dataset data.

From this class we can also access information in the current EvaluationContext via the evaluationContext variable in the super class. This class will give access to request parameters, datasets, variables and formatters if they are needed.

Now that the class has been created it's necessary to compile it and to create a jar file from it. Once the jar file has been created it can be imported into Inforama by clicking the Options -> Set Classpath... menu item. The classpath dialog will open as shown in figure 101 below.

Click the Save Classpath button to save the classpath. Now this jar will be available to all Inforama projects running on the machine where Inforama studion is running.


Now in order to use the class within a document create a document with a table command as shown in figure 102 below.

When generated this table will then appear in the previewer as shown in figure 92.


Figure 101: The classpath dialog

Figure 102: Defining the custom table in a document

Figure 103: Preview of the Java generated table