Document Automation with Inforama Inforama Community Edition Version 1.5 Copyright 2008-2010 Inforama Limited www.in4ama.org This document is subject to change without notice
License
The contents of this document are subject to the General Public License (GPL). You may not use this document except in compliance with this license.
Disclaimer
Your 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 support@in4ama.org. If you have comments or suggestions about this documentation, contact us at documentation@in4ama.org
Updates
As 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
Contents at a glance
Chapter 1 Introduction........................................................................................................6 Chapter 2 Getting Started.................................................................................................10 Chapter 3 Data Sources and Datasets.............................................................................15 Chapter 4 OpenOffice Letters and Letter Fragments.......................................................26 Chapter 5 Working with Acrobat Forms............................................................................34 Chapter 6 Acrobat forms from OpenOffice Documents....................................................42 Chapter 7 Editing Emails..................................................................................................49 Chapter 8 Iterating Datasets.............................................................................................52 Chapter 9 Data Formatting...............................................................................................59 Chapter 10 Managing Documents and Packs..................................................................63 Chapter 11 Printing...........................................................................................................68 Chapter 12 Document Generation Wizard........................................................................70 Chapter 13 Table Formatting............................................................................................76
Table of Contents
Chapter 1 Introduction........................................................................................................6 What is Inforama?..............................................................................................................6 Letter Generation...............................................................................................................6 Acrobat Form Generation..................................................................................................7 Other Features...................................................................................................................7 Advanced Features............................................................................................................7 Inforama Community/Enterprise Edition............................................................................7 Related Technologies........................................................................................................8 License Information...........................................................................................................9 More information................................................................................................................9 Chapter 2 Getting Started.................................................................................................10 System Requirements.....................................................................................................10 Running Inforama Studio.................................................................................................10 Windows Users............................................................................................................10 Linux Users..................................................................................................................10 Quick Tour of Inforama Studio.........................................................................................11 Creating a new Inforama Project.....................................................................................13 Chapter 3 Data Sources and Datasets.............................................................................15 Creating a new JDBC Connection data source............................................................15 Creating Parameters........................................................................................................17 Creating a new JDBC Connection data set..................................................................18 Using datasources and datasets.....................................................................................19 Creating a new Spreadsheet data source.....................................................................22 Creating a new Spreadsheet data set...........................................................................23 Creating custom datasources and datasets....................................................................24 Chapter 4 OpenOffice Letters and Letter Fragments.......................................................26 Creating OpenOffice Letters............................................................................................26 Adding Parameters to Letters..........................................................................................27 Adding Data Fields to Letters..........................................................................................29 Creating Letter Fragments...............................................................................................31 Chapter 5 Working with Acrobat Forms............................................................................34 Creating and binding Acrobat Fields...............................................................................34 Creating new Acrobat Fields within the Studio................................................................36 Acrobat Field binding types.............................................................................................36 Text field binding.........................................................................................................36 Image binding .............................................................................................................37 Barcode binding...........................................................................................................39 Checkbox binding .......................................................................................................40 Chapter 6 Acrobat forms from OpenOffice Documents....................................................42 Creating an Acrobat Form from OpenOffice....................................................................42 Switching to the Acrobat Form View................................................................................45 Binding to the Acrobat Fields...........................................................................................46 Previewing the Document................................................................................................47 Chapter 7 Editing Emails..................................................................................................49 Creating an Email Document from OpenOffice...............................................................49 Previewing Emails...........................................................................................................50 Chapter 8 Iterating Datasets.............................................................................................52
4
Accessing database data (DataSources and DataSets).................................................52 Data Set Iteration.............................................................................................................52 Nested Data Set Iteration................................................................................................54 Table Row Iteration..........................................................................................................55 Table Cell Iteration...........................................................................................................57 Chapter 9 Data Formatting...............................................................................................59 Basic Formatters..............................................................................................................59 Creating a custom data formatter ...................................................................................60 Using a Custom Formatter...............................................................................................62 Chapter 10 Managing Documents and Packs..................................................................63 Managing Documents......................................................................................................63 Creating a Single Document............................................................................................63 Creating Compound Documents from Letter Fragments................................................64 Working with the Preview Dialog.....................................................................................65 Associating Emails with Documents................................................................................66 Setting the Background Document..................................................................................66 Applying Display Conditions............................................................................................67 Chapter 11 Printing...........................................................................................................68 Acrobat Command...........................................................................................................68 Foxit Command................................................................................................................68 JPedal Printer..................................................................................................................69 PDF Supporting Printer....................................................................................................69 Creating a Custom Printer Class.....................................................................................69 Chapter 12 Document Generation Wizard........................................................................70 Generating Documents and Packs..................................................................................70 Generating Mailshots.......................................................................................................73 Chapter 13 Table Formatting............................................................................................76 Introduction......................................................................................................................76 Getting started with Table Formatters.............................................................................76 Sub Tables.......................................................................................................................77 Using Table Templates....................................................................................................78 Applying header templates..............................................................................................80 Including Sub Table Templates.......................................................................................81 Manipulating tables from custom Java classes...............................................................82
Chapter 1 Introduction
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 Generation
Mail 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.
Chapter 1 Introduction
Other Features
With 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 Features
More 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 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.
Chapter 1 Introduction
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.
Related Technologies
The following Open Source projects are used by Inforama and knowledge of them may provide developers with the ability to enhance and extend Inforama. Technology OpenOffice Writer iText Apache FOP License LGPL Website Description
http://www.openoffice WRITER has everything you would expect from a .org modern, fully equipped word processor or desktop publisher.
MPL & LGPL http://www.lowagie.co iText is a library that allows you to generate PDF files m/iText on the fly. Apache http://xmlgraphics.apa Apache FOP (Formatting Objects Processor) is a License, 2.0 che.org/fop 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. GPL http://www.sf.net/proj ects/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.
Office2fO
Groovy * Spring
Apache http://groovy.codehau An agile and dynamic language for the Java Virtual License, 2.0 s.org Machine. Apache http://www.springfram Spring is an Open Source framework which was License, 2.0 ework.org 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.
Chapter 1 Introduction
License Information
Inforama 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 info@in4ama.org
More information
Anyone can get involved in the development and activities surrounding Inforama by visiting http://www.in4ama.org or http://www.sourceforge.net/projects/inforama
Chapter 1 Introduction
Windows Users
For 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 Users
For 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
11
Description Shortcut toolbar for quick access to application functions. 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. 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 12 Datasets defined within the Inforama project are listed here and can be
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. 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.
7 Properties Frame
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 13 Chapter 2 Getting Started
14
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
Figure 6: Dataconnections dialog 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.
16
Figure 8: JDBC Configuration Settings 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.
17
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.
Figure 11: The Add Parameter Dialog 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.
18
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.
Figure 12: Binding Data Within Inforama Studio 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.
19
Figure 13: The Datasets Menu 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.
Figure 15: Parameters Specification Dialog 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.
20
Figure 17: Tables Icon 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.
Figure 18: Data List with Table Prefix Now whenever a field is inserted into a document it will be be inserted in the format F{[dataSet].[dataTable]. [dataField]} 21 Chapter 3 Data Sources and Datasets
Figure 19: Spreadsheet to be used as a datasource 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.
22
Figure 20: Spreadsheet configuration page Click the save button and the new spreadsheet datasource will appear in the dialog listing project datasources as shown in figure 12.
23
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.
24
/** * 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); } [...] }
25
Figure 22: New Document Dialog 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
Double-click the document's name on the list to open an embed OpenOffice editor.
Frame. Click the add parameter button and enter the name
Figure 24: The Parameters Frame 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.
27
Figure 26: The Letter Manager Dialog 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.
Figure 27: The Parameters List in the PDF Preview Dialog 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.
28
29
Figure 29: The Data Frame 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.
Figure 30: Inserting Data Placeholders in Letters Again the modified document can be previewed using the Letter Manager dialog. The generated document is displayed in Figure 31.
30
31
Figure 32: Creating a new Letter Fragment with the New Document Dialog 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.
Figure 33: The new letter fragment in the document tree 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.
32
33
Figure 35: The import document dialog 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
Figure 36: Editing Acrobat forms 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.
35
36
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'
37
Figure 40: Binding an image field to a file 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.
38
Figure 41: Different images depending on parameter 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 binding
Displaying 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.
39
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.
40
41
Figure 44: New Document Dialog 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
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.
43
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.
44
Figure 50: Formatting Text Boxes The inserted Text Boxes can be formatted by double-clicking them. The properties dialog for the selected component will appear as in Figure 50.
Figure 51: The PDF Button on the OpenOffice Editor 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.
45
Figure 52: The Exported Acrobat Form 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.
46
Figure 54: The Document Manager Dialog Select the document from the main list of documents in the center of the dialog and click the right arrow to
47
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.
48
Figure 56: Create the Email with the New Document Dialog
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
Previewing Emails
You 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.
Figure 58: The Project Properties Toolbar Button 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...
50
Setting SMTP Server SMTP User SMTP Password From address Reply to address
Description The server through which emails will be sent The user name required for authentication by the SMTP server The password for the user authenticating against the SMTP server The address which will appear in emails sent via Inforama for this project 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.
51
52
For a two rows Users table the generated document will appear as in Figure 63 below.
54
55
Figure 65: Iterating Tables in OpenOffice Documents 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.
56
57
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.
58
Basic Formatters
There 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.
Figure 69: The Data Formatter Button in the Data Frame 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
$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
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" />
61
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.
62
Managing Documents
To 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.
sufficient to generate a single document. Now click the Preview button and the generated document will appear in the document preview dialog.
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.
64
Figure 77: Document Parameters 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 Refresh Description Regenerate the displayed document.
Save
Save the generated document. The user will be asked to specify the location to which the PDF file should be saved 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.
Display in Acrobat
65
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.
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.
66
Fragments 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.
67
Chapter 11 Printing
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 Command
This 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 Command
This 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
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 Printer
JPedal 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.
There are two parameters to this method Parameter printJobs printServiceName Description An array of print instructions which are required to be carried out. 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
Figure 82: Document Generator Wizard Dialog 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 Email Options 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. Chapter 12 Document Generation Wizard
70
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. Clicking this checkbox will return the generated document to the client application where it can be saved, viewed and manipulated.
Return
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.
71
Figure 84: Specifying the Parameters Click the next button and the screen shown in Figure 85 will be displayed.
Figure 85: Final Wizard Page Click the Show Document button and the preview dialog will be displayed as in Figure 86.
72
Generating Mailshots
Open 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.
73
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.
Figure 88: Specifying the recipient address 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 74 Chapter 12 Document Generation Wizard
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.
Figure 89: Specifying mailshot parameters Click the next button to finish the wizard and send the mailshots.
75
Introduction
In 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.
Figure 90: Creating the basic table template Figure 90 shows how the table is created and figure 91 shows a screenshot of the document when it is generated in the previewer.
Figure 91: Preview of the basic table 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
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 Tables
There 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.
Figure 93: Sub table definition within a document 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 =
77
'$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.
78
Figure 96: Table template listed in the project frame 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.
79
80
Figure 100: Sub table template 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
81
$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}';}}
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; }
82
/** 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();
83
// 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.
84
Figure 101: The classpath dialog Now in order to use the class within a document create a document with a table command as shown in figure 102 below.
Figure 102: Defining the custom table in a document When generated this table will then appear in the previewer as shown in figure 92.
85