Create a PDF Template
Form-based reporting provides a powerful method for making data available in popular formats. This topic describes how to use Logi Info to generate and fill-in Adobe PDFForm Templates.
Template definitions are only available in Logi Report v10.1.59+.
Filling PDF forms with data starts with the creation of the PDF form template. Once the PDF form has been designed and created, four more steps are required:
- Add the PDF form template to your Logi app project
- Create a template definition
- Retrieve the correct data
- Map that data to the form fields
The rest of this topic assumes that you've already created your PDF form template.
Note that, in recent versions, the Firefox browser includes its own built-in PDF viewer which may not properly display all values, such as checkbox marks, in a filled template. If in doubt, use the real Adobe Acrobat browser plug-in to view filled templates.
Add the PDF Form Template to Your Project
The term "template" is used frequently in this discussion, and to avoid confusion, let's clarify it:
- A PDF form template is a .PDF file created with a PDF editor such as Adobe Acrobat Professional. It looks like the finished output without any data and has form fields indicating where the data will go. This is the target template.
- A Logi reporting tools template definition is an .LGX file, similar to a report or process definition, created with Logi Studio. It's a set of instructions to the Logi server engine to retrieve data and map it to the form fields in the target template.
PDF form template files are managed within your Logi application as support files.
- In Logi Studio's Application Panel, select and right-click the Support Files folder.
- In the popup menus that appear, select the Add and Existing File... items.
- Browse to your PDF form template (.PDF) file and select it. Click OK to add it to the project. The file will be copied to the _SupportFiles folder in your application project folder.
The next step is to create a new template definition that maps the data to the PDF form template fields:
- In the Application Panel, select and right-click the Templates folder.
- In the popup menus that appear, select the Add and New Definition items.
- A new definition named "newTemplate" will appear beneath the Templates folder, ready to be renamed, and will open in the Workspace Panel for editing. The actual file will be created in the _Definitions/_Templates folder in your application project folder.
- In the Workspace editor, add a PDF Form element to the new definition, as shown above.
- Set its Form Template File attribute to the name of the PDF form template file you added as a Support File (it should be available in the attribute's drop-down list of options).
- Finally, add a datalayer element to the definition and configure it to retrieve your report data (see the next section).
Template definitions cannot utilize more than one PDF Form element.
The Flatten Fields attribute is optional but, when used, it applies to all fields within the form template file. Setting this attribute to True makes all fields in the output PDF document read-only. Its default value is False.
It's important to understand exactly what data you will need. Consider the following:
PDF form template files can contain two types of form fields:
- Developer-generated fields - manually created by the developer when designing the PDF form template.
- Acrobat-generatedfields - automatically generated by the PDF editor when the developer copiesandpastes a field or group of fields multiple times. Acrobat-generated fields are often found in invoice-style form templates.
In order to correctly configure the datalayer element(s) in your Template definition, you need to understand how the Logi report server processes the data (which is handled as XML data rows). You should ask these two questions:
- Does the PDF Form template contain any Acrobat-generated fields? If so, is this form an "invoice-style" report?
- Should the Template definition create a PDF document containing a single PDF Form ("One Form" output mode), or a PDF document with multiple PDF Forms merged into it ("One Form Per Data Row" output mode)?
Now you need to configure the proper output mode.
Using One Form Output Mode
When filling a document with a single PDF form template,
in your template definition set the PDF Form element's Form Output Mode attribute to OneForm, as shown above.
If the PDF form template has no Acrobat-generated fields, then only one row of data is needed to fill the form. The following example shows a SQL query and the resulting XML data needed to fill this kind of PDF form template:
SELECT FirstName, LastName, Title, SSN, DOB FROM Employee WHERE SSN = '111-22-3333'
But, if the PDF form template includes Acrobat-generated fields, then multiple rows of data are needed to fill the form. The following example shows a SQL query and the resulting XML data needed to fill this "invoice-style" PDF form template:
SELECT FName, LName, ProductID, Category, Product FROM EmployeeOrders WHERE SSN = '111-22-3333'
The unique values in the last three fields of the XML data above are used to fill-in the Acrobat-generated fields in the PDF form template.
Using One Form Per Data Row Output Mode
When filling a document with a multiple PDF form templates,
in your template definition set the PDF Form element's Form Output Mode attribute to OneFormPerDataRow, as shown above.
If the PDF form template has no Acrobat-generated fields, the one row of data is needed to fill each output form. The Logi server engine will merge each filled PDF form into a single document. The following example shows a SQL query and the resulting XML data needed to fill multiple PDF Forms of this type:
SELECT FirstName, LastName, Title, SSN, DOB FROM Employee
But, if this kind of PDF Form template includes Acrobat-generated fields, a hierarchical XML dataset is required to fill it. For example, a company might have 3 customers that place 3 orders each. In this case, an XML data row and all its child rows are necessary to fill-in a single form.
The XML data must be hierarchically shaped to produce multiple, invoice-style PDF documents from a single PDF form template. This could be done in a variety of ways, for example by using SQL query GROUP BY statements or grouping elements.
The template definition models the PDF form by utilizing a PDF Form Field element for each field or group of fields in the PDF form template file.
To speed the process, developers can use a Logi Studio wizard, shown above, to generate the PDF Form Field elements required to fill the PDF template. The wizard will add one PDF Form Field element to the Template definition for each user-generated field, and it will also add one (but only one) PDF Form Field element for each group of Acrobat-generated fields.
So, for the example form shown above, the wizard will add the following PDF Form Field elements in the definition:
The ff_ID, ff_Category and ff_Product elements each represent a group of Acrobat-generated fields. When the Logi server engine fills-in the data, it does so row-by-row to provide data for all the fields in each group.
To manually add a form field to the definition:
Developers who don't want to use the wizard can add PDF Form Field elements to the definition manually, as follows:
- In the Workspace editor, add a PDF Form Field element below the PDF Form element, as shown above.
- In its Field Name attribute, enter the exact field name from the PDF Form Template. This is case-sensitive.
- Assign a value for the Value attribute. The value can be a token, a static value, a VBScript formula, or any combination of them.
- Make the field read-only by setting the Flatten attribute to True. (This will be overridden, however, by the Flatten Fields attribute of the PDF Form element, if it's been configured).
- (Optional) Select a format for the Format attribute.
Repeat for each field and group of fields in the PDF Form Template file.
Do not add an element for each field within an Acrobat-generated group fields.
The PDF form template and the Logi template definition are now complete and you're ready to begin producing filled PDF documents.