. . .

PDF-Generator Module

Introduction

The PDF generator takes an html template, fills variables inside that template and creates a pdf from the merged html.
Attachments like other pdfs or images may be appended.

Key Capabilities

Capability

Description

PDF generation

Create PDF files from html templates alongside given variables to be filled in the template.
Attachments may be appended in form of other pdf or images files.

Module Setup & Configuration

No configuration necessary.

Example data

Sample HTML template
<!DOCTYPE HTML PUBLIC "-//W3C//DTD XHTML 1.0 Transitional //EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
<head>
<!-- templates may also include css -->
<style>
body {
font-family: 'Arial', sans-serif;
color: #545454;
font-weight: 100;
}
</style>
</head>
 
<body>
 
<table class="root-table">
<tbody>
<!-- Example of an image variable. The module will generate the base64 data from a given image -->
<tr>
<td>Image:</td>
<td><img src="data:image/png;base64,${profilePic}" /></td>
</tr>
 
<!-- Example of a string variable -->
<tr>
<td>First name:</td>
<td>${firstName}</td>
</tr>
</tbody>
</table>
 
<!-- Example of a list of strings variable -->
<div class="additional-info__box">
<h4>Fees</h4>
<#list fees as item>
<p>${item}</p>
</#list>
</div>
</body>
</html>

Your variables might then look like:

StringVariable firstName: key: "firstName", content: "Jens"
StringListVariable fees: key: "fees", content: ["125", "166", "23"]
ImageVariable: profilePic: key: "profilePic", contentURL: "http://www.xxxxxx.com/image.png" (we will not post byte arrays here)

Example

Follow the steps provided below in order to create the desired pdf file.

Frontend Use

  1. Create instances of all string, string list and image variables that may occur in your html template. These variables occur
    in the form of ${attribute_name}. Provide keys as well as contents.

  2. Create your Attachment instances and provide file contents.

  3. Create an instance of PDFTemplate. From here, reference all necessary StringVariables, StringListVariables
    and ImageVariables.

  4. Create a PDFResult object and set references to Attachments and the PDFTemplate.
    Now, the module will create the pdf file. It should be available for download after a moment.

Backend Use

  1. Follow steps 1. - 3. as shown above.

  2. Create a PDFResult object and set references to Attachments and the PDFTemplate.

  3. You need to invoke pdf creation yourself. The package com.apiomat.nativemodule.pdfgenerator contains the
    public class PDFHelper. Instantiate that class using PDFResult and Request. This example illustrates the procedure:

    PDFHelper helper = new PDFHelper( pdfResult, request );
    try
    {
    /* try to generate pdf file. On success, it will be stored in the content attribute of
    * pdfResult.
    * TemplateException: variables in html template are unset */
    helper.generatePdf( );
    }
    catch ( IOException e )
    {
    PDFGenerator.AOM.logError( request.getApplicationName( ), e, false );
     
    e.printStackTrace( );
    }
    catch ( TemplateException e )
    {
    String error = "Missing required variable: ${" + e.getBlamedExpressionString( ) + "}";
    PDFGenerator.AOM.logError( request.getApplicationName( ), error, false );
     
    e.printStackTrace( );
    }

Limitations

If creating the pdf file from your given template information fails, the error should be that variables in the template were not filled by Variables provided.
In that case, doublecheck, if you have any typo for key names or if keys are missing.

PDF creation from attachments alone won't work either. The primary function of this module is the creation from html.

Detailled Module Workflow

Classes

Class name

Attributes

Description

Variable

key: String that refers to the name of a
variable in the raw html template

Super class for distinct Variable types

StringVariable

content: String containing a variable's value

Sub class of Variable. Used for single
String variables in template.

StringListVariable

content: List containing a set of Strings

Sub class of Variable. Used for declarations
of lists of String variables in template.

ImageVariable

content: Image that is to be placed into the
template.
width: desired image display width
height: desired image display height

Sub class of Variable. Used to fill image
variables in template as base64 representations.

PDFTemplate

content: String to place the html template in
stringVariabes: collection of all string variables
to be put into the html
stringListVariables: all string lists to be filled
in the template
imageVariables: all images to be filled into the
template

An object of this class takes an html template and
all variables as key-value-pairs that belong to the
actual template.

PDFResult

content: this place is filled by the resulting pdf
files if it can be successfully created from a
PDFTemplate
template: a reference to a PDFTemplate used to
render the desired pdf
attachments: list of files (either pdfs or images)
that are to be appended to the resulting pdf

An object of this class uses a template to create
a pdf file from html.
Attachments may be added and are appended to
the file.

Attachment

content: File (pdf or any image) that may be
attached to a PDFResult

 

Sequence

After setting a reference from a PDFResult object to a PDFTemplate object (PDFResult's template attribute) or adding references to
Attachment objects, the module calls it's afterPostRef-Method that invokes the creation of the actual pdf file.

In order for this operation to succeed, the template attribute must be not null.

Errors may occur if variables in the html template are not filled out by Variable objects.

* link only available in Enterprise Documentation