Difference between revisions of "Print Templates"

Latest revision as of 02:32, 11 September 2013

Designer > Print Templates

Print templates let you generate PDF documents for selected records.

About Print Templates

Using Print Templates, you merge record data into a formatted document to create a PDF with rich formatting. You can use such templates to create prefilled forms, invoices, contracts, and other types of documents using data stored in your application.

A Print Template can be based on an HTML file, a Word document, a PowerPoint presentation, or a JSP Page stored in the platform. You can use them to print individual records, or to print multiple records displayed in a View.

Note: HTML, Word, and PowerPoint files are created outside of the platform, and then uploaded for use. Once created, they can be downloaded, edited, and uploaded again. JSP Pages are created and edited either in the platform, or using the Eclipse Plug-in.

Examples

Create an Expense Report to be used in expense management application
Print an Employee Benefit Form
Print Invoices for a collection of records selected in a View

Learn more: Sample Print Templates you can customize and use.

Print Template Formats

Print Templates can be created in a variety of formats including:

JSP Pages
HTML pages
Ms Word Documents
PowerPoint Presentations
Compound Templates that are a composite of multiple parts

How Print Templates Work

At bottom, Print templates are formatted documents with variables you create by inserting specific codes. When you generate a PDF, the codes are replaced by record data, images, and charts, to create a customized version of the template.

For even more dynamic documents, the platform uses the Apache Velocity templating engine, which allows you to vary the content of the document based on record data, and to create repeating parts for related records, like the OrderItems in an Order.

Learn more: http://velocity.apache.org/engine/releases/velocity-1.5/user-guide.html

In outline, the process for creating a Print Template looks like this:

You create a document (on your local file system) or a JSP Page in the platform that includes all of the fixed text and images you want to include in your template.
Learn more: HTML Resources
While creating the document, you make note of the platform data you want to add:
- Record fields
- Record images
- Charts created from Reports
- User fields
- Company fields
- Fields from Related Records
You use the Template Variable Tool to get the field names you need to customize the HTML file with fields and images taken from data records.
You use the Reports tool to get the identifiers for charts you want to add.
You use the Velocity scripting language to build logic into the template, changing the content based on data parameters.

Considerations

CSS styles can be embedded into HTML files. External CSS files can also be referenced in the template, if they are first uploaded as Static Resources.
Fixed images can be inserted into Word and PowerPoint files directly.
Fixed images in an HTML file need to be stored on the platform either as Static Resources, or as Public Documents.

Note: A Static Resource is available only to a logged-in user. A Public Document is visible to anyone who has the link. From the standpoint of a Print Template, the difference is immaterial, since a user has to be logged in to print a record.

Working with Print Templates

Add a Print Template

A Print Template can be added to any object, except for the built-in Documents and Users objects. It can use a Page stored in the platform, or it can be created using an external HTML, Word, or PowerPoint file. This section outlines the process.

To add a Print Template to an Object:

Click Designer > Objects > {object} > Print Templates
Click the [New Template] button.
The New Template page appears.
Use the Template Variable Tool to get the names of variables you can use in the template:

Note:
Template variables can be used in HTML, Word, and PowerPoint files. (In Pages stored in the platform, you use standard JSP programming techniques to access platform information, rather than template variables.)
If it does not already exist, create the template:
Provide the information in the Template Information section:
Template Title

The template name

Description

Describe the purpose of the template or other information about it.

Ready to Use

The default setting for the template is Yes.

Type
HTML - To upload an HTML, Word, or PowerPoint file stored on your local system.
The [Browse] button appears.

Click it to locate the file to upload.
Page - To use a JSP/HTML Page stored in the platform.
A list of platform Pages is displayed.

(The list does not include pages that have the Include Headers option.)

Choose one of the listed pages.
Click [Save]

Edit a Print Template based on a Platform JSP/HTML Page

Click Designer > Pages > {page}
Edit the page.
Learn more: Pages
If you need the names of additional variables:
a. Click Designer > Objects > {object} > Print Templates

b. View the template to access the Template Variable Tool:

Edit a File-Based Print Template

Click Designer > Objects > {object} > Print Templates
Click the Download link on the template you want to copy to your local system.
Make changes to the template.
If you need the names of additional variables, click the [New Template] button to access the Template Variable Tool:
If the New Template window is open, click [Cancel] to close it and go back to the Templates (record list) view.
Click the Replace link on the template to upload the modified template.

Warning: Be sure to click the right link. The existing template page will be replaced by the new one.

Use a Template to Print a Record

Open an object record.
Click the [Print] button.
Select Template based to create an HTML page using the Print Template.
Select the Template
Optionally, select PDF format to generate a PDF. (Default is HTML.)
Click [Print].
A new window opens to display the results.
Copy content from the resulting HTML page, print it, or save the page to your local system.

Use a Template to Print a List of Records

Visit Workspace > {object}
Select a view
Do a search or add criteria to modify the view
Select the records to print.
(Click All to select all displayed records.)
Select More Actions > Print
Use the current view, choose a new one, or select records manually.
For Print Layout, choose Use a Print Template
Select the template to use
Set the page orientation
Click [Print]

Insert Images and Template Variables

See the instructions for the kind of template you are creating:

Create a Compound Print Template

It is also possible to create a print template that is a composite of multiple parts.

Learn more: Create a Compound Print Template

Processing Related Records in HTML

About Related Record Variables

In a Custom Object, fields from related records can be added to a Document Template. (That is, records from an Object that has a Lookup to the current object.)

For example, OrderItems has a lookup to Orders, so in a Document Template for Orders, related OrderItems records can be accessed. (In an object Form, related records are typically displayed in a Subform, although they need not be.)

When formatting a record in the current object for printing, those related records and the fields they contain can be processed in a loop.

Finding and Using Related Record Variables

Finding Related-Record Variables

Related Object variables are found using the Template Variable Tool.

Here, in the Email Template for Claims, the related ClaimItems object is being chosen from the category list:

Within that group, the Item Name field is listed, along with other fields in the ClaimITems object. Once selected, the variable name appears in the Variable area, along with the loop it needs to be surrounded by for processing:

#foreach( $ClaimItems_record in $ClaimItems ) $ClaimItems_record.item_name #end

If a loop already exists, you would use only the variable name part:

$ClaimItems_record.item_name

Note:
For a many-to-many relationship like one between Claims and Tags, the variable looks like this:

$Claims_Tags_record.related_to_Tags.tag_name

where:

$Claims_Tags is the Junction Object that produces the many-to-many relationship
related_to_Tags is the name of the Lookup field in the Junction Object that references a Tags record
tag_name is the field to display
The "dot" separator (.) joins each of the segments in the variable name

Processing Related Records in a Loop

Typically, you'll create a table for the related records, define its headings, and then create a row for a single record, putting the related-record variables into the cells of the row. You then enclose that row in a loop, using the #foreach instruction defined by the Velocity templating engine.

Related records are returned in an array, so the loop creates a new table row for each record in the array.

Here is an example that processes OrderItems for an Order (with formatting attributes removed for simplicity):

<table>
<tbody>
<tr>
    <th>Quantity</th>
    <th>Product </th>               
    <th>Unit Price</th>
    <th>Amount</th>
</tr>
</tbody>

#foreach( $OrderItems_record in $OrderItems )
<tr>        
    <td>$OrderItems_record.item_quantity</td>
    <td>$OrderItems_record.related_to_ProductInventory.product_name</td>
    <td>$OrderItems_record.item_price</td>
    <td>$OrderItems_record.total</td>
</tr>
#end

...
</table>

where:

The <tbody> element is required around the header row.

The Velocity #foreach directive does the looping.

Learn more: http://velocity.apache.org/engine/releases/velocity-1.5/user-guide.html

The looping construct defines $OrderItems_record as a loop variable.
The loop variable iterates over the $OrderItems array.
The $OrderItems array is automatically available in the template, because OrderItems is a Related Object. (All related objects are available. Each is an array.)

Special Considerations for Subform Variables

Totals and additional computation fields defined for a Subform are also available in the Template Variable Tool. To find them, you access the main object (not the object displayed in the Subform), because those fields are added to the object that contains the Subform.

For example, the Subform for OrderItems totals the $Amount column, and then does additional computations on it to add a surcharge. Those values are shown in the $Orders Fields category as Total $Amount and Shipping for $Amount, respectively. (The final total is shown as Net Total $Amount.)

Sample Template for an Order Invoice

This sample:

Creates an invoice for an order, showing all items in it
Gets the name and price of order items from the ProductInventory object
Uses Velocity #foreach processing to process OrderItems records for an Order
Uses Velocity #if conditionals to display surcharge and discount rows only if those values are present

<html><head>
<title></title>
<style>
 div {  
      padding-top: 5px;  
      padding-bottom: 5px;  
      padding-right: 5px;  
      padding-left: 30px;  
      border: 3px;  
	  margin-top: 5%;
	  margin-right: 40%;
	  margin-bottom: 5%;
	  margin-left: 5%;
    }
</style>

</head><body bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">

<div style="width:100%">

<img  width="100" height="100"  src="http://justanothermobilemonday.com/Wordpress/wp-content/uploads/2009/10/android-robot-logo2.jpg" alt="Company logo" />&nbsp;&nbsp;&nbsp; <---- Company Logo Here<br/>
<font size="5"><b>$company.name</b></font><b><br />
<br/>
$company.street&nbsp;&nbsp;<br>
$company.city, $company.state, <br>
$company.country - $company.zip
 
&nbsp;<br>
&nbsp;(Phone): $user.phone
<hr width="100%" size="1" />
<br />

<h2 align="center">Order<b> Invoice</b></h2>
<p></p>
<p align="center"><b>Invoice Date:</b> $Orders.date_created </p>

<br/><br/>
<b><u>Bill To: </u></b><br />
<font size="2">$Orders.account.name - $Orders.account.number</font></b>
<br />$Orders.account.street<br />
$Orders.account.city,&nbsp;$Orders.account.state, <br>
$Orders.account.country - $Orders.account.zip<br /> 

(Phone): $Orders.account.phone <br />
<br />
<br />
<b>Invoice #: $Orders.order_number <br />
</b>&nbsp;
</p>

<table border="1" cellpadding="5" cellspacing="0" width="600">

<!-- HEADER -->
<tbody>
<tr>
    <th>Quantity</th>
    <th>Product </th>               
    <th>Unit Price</th>
    <th>Amount</th>
</tr>
</tbody>

#foreach( $OrderItems_record in $OrderItems )
<tr>
<td width="350">$OrderItems_record.item_quantity</td>
<td width="100" align="CENTER">$OrderItems_record.related_to_ProductInventory.product_name</td>
<td width="100" align="CENTER"> $OrderItems_record.item_price</td>
<td width="100" align="CENTER"> $OrderItems_record.total    </td>
</tr>
#end

<tr>
<td colspan="2">&nbsp;</td>
<td style="border: solid 1px #000000;" align="Right">Sub Total</td>
<td style="border: solid 1px #000000;" align="center">$Order.grid_comptn_f5631e34b39f4ba39a98559c7215a3b4</td>
</tr>

#if( $Orders.grid_surcharge_031f67dd4b3946949df2da276e5c82a6 > 0 )
<tr>
<td colspan="2">&nbsp;</td>
<td style="border: solid 1px #000000;" align="Right">Surcharge</td>
<td style="border: solid 1px #000000;" align="center">$Orders.grid_surcharge_f5631e34b39f4ba39a98559c7215a3b4</td>
</tr>
#end 

#if( $Orders.grid_discount_031f67dd4b3946949df2da276e5c82a6 > 0 )
<tr>
<td colspan="2">&nbsp;</td>
<td style="border: solid 1px #000000;" align="Right">Discount</td>
<td style="border: solid 1px #000000;" align="center">$Orders.grid_discount_f5631e34b39f4ba39a98559c7215a3b4</td>
</tr>
#end 

<tr>
<td colspan="2">&nbsp;</td>
<td style="border: solid 1px #000000;" align="Right">Tax</td>
<td style="border: solid 1px #000000;" align="center">$Orders.grid_tax_f5631e34b39f4ba39a98559c7215a3b4</td>
</tr>

<tr>
<td colspan="2">&nbsp;</td>
<td style="border: solid 1px #000000;" align="Right">Shipping</td>
<td style="border: solid 1px #000000;" align="center">$Orders.grid_shipping_f5631e34b39f4ba39a98559c7215a3b4</td>
</tr>

<tr>
<td colspan="2">&nbsp;</td>
<td style="border: solid 1px #000000;" align="Right"><b>TOTAL AMOUNT DUE</b></td>
<td style="border: solid 1px #000000;" align="center"><b>$Orders.grid_net_total_f5631e34b39f4ba39a98559c7215a3b4</b></td>
</tr>     
</table>

<br /><br />
Payment Due upon reciept<br />
Thank you for your business!
</div>
       
<p></p>
</body>
</html>

The Subform part of the resulting invoice then looks something like this:

(The Order Invoice template and the Order Invoice sample file are both available in the downloads area.)

Customizing Data Sent to the Template with a Print Template Class

About Print Template Classes

Using a method defined in a Class, you can manipulate the data that a Print Template processes. Here's how it works:

When a Print Template is processed, it gets its data from the TemplateContext

The TemplateContext contains a HashMap for each record sent to the Print Template, indexed by an Object name (a string). The HashMap contains name/value pairs for each field in that record.

To a Print Template, then, a data object is simply a HashMap that is present in the TemplateContext.

That object is passed to a method you define. By manipulating the HashMaps it contains, you change the data that the Print Template processes. You can even add new "objects", by adding additional HashMaps, and new "related objects", by adding ArrayLists of HashMaps.

Coding a Method in a Print Template Class

In a Print Template, a data reference has the form $objectName.fieldname. To access, create, or modify data in your code, you will do one or more of the following operations:

Retrieve an object's HashMap from the TemplateContext

TemplateContext.get("objectName");

Add or update a data HashMap

TemplateContext.put("objectName", HashMap);

Get a field from data HashMap

HashMap.get("fieldName");

Add or update a field in a data HashMap

HashMap.put("fieldName",value);
where value is typically a string or a nested HashMap.

Retrieve an ArrayList of related-object HashMaps from the TemplateContext

TemplateContext.get("RelatedObjectName");

Configuring a Print Template to use a Specified Class and Method

To designate the class and method to use, when creating or editing a Print Template:

Under Custom Data Source, click Enabled.
In Select a Class, choose the class that has the method you want.
In Select Method choose the method that does the processing you want.

The methods available to choose are public methods that have the following signature:

doSomething(TemplateContext context, String objName, String recordId)

where:

com.platform.api.TemplateContext: Is the container that the print template gets its data from.
String (objName): Has the name of the object the print template was invoked on.
String (recordID): Has the ID of the record on which it was invoked.

Considerations

A class can contain multiple processing methods, so you can do all related-work in a single class.
Such methods generally return void, but they don't have to. Any method that takes the appropriate arguments will be listed, regardless of its return value.

Accessing Lookup Target Records

Data from lookup-target records is stored as a nested map. For example, to get data for the template variable $Order.customer.name:

1. HashMap orderMap = TemplateContext.get("Order")

Gets the Order HashMap from the context.

2. HashMap customerMap = orderMap.get("customer")

Gets the lookup-target record for the customer field.

3. String name = customerMap.get("name")

Gets the customer's name.

Accessing Data in Related Records

A Print Template is always invoked on a specific record. Related-object records that look up to that record are contained in an ArrayList of HashMaps, indexed by object name. The code for obtaining and processing that kind of list looks like this:

public void chgData(TemplateContext context, String obj, String record)
{
    ArrayList<HashMap<String,Object>> listOfRecords =
        (ArrayList)context.get("SomeObject");
    if (listOfRecords == null) { listOfRecords = new ArrayList(); }
    for (HashMap<String,Object> currRecord : listOfRecords )
    {
	// Process the records in this for-each loop
    }		
}

To create an entirely new breed of related "records", create an ArrayList of the appropriate type and add it to the TemplateContext.

Examples

Changing Field Data

This example substitutes the name of the state for its abbreviation, when processing a Customer record:

public void chgData(TemplateContext context, String obj, String record)
{
    HashMap customerMap = (HashMap)context.get("Customer");
    String state = customerMap.get("state").toString();
    if ( "CA".equals(state) ) { 
        customerMap.put("state","California"); 
    }
}

Example: Adding a New Field

This example adds a new "Good Customer" field to the record.

public void addData(TemplateContext context, String obj, String record)
{
    HashMap customerMap = (HashMap)context.get("Customer");
    customerMap.put("rating", "Good Customer"); }
}

After that method has run, the Print Template can use the variable $Customer.rating, just as though that field was defined in the platform object.

Example: Adding a New Object

This code creates a new ProductSupplier "object" (as far as the Print Template is concerned), and adds it to the TenantContext (context).

public void addObj(TemplateContext context, String obj, String record)
{
    HashMap<String, Object> productSupplierMap = 
        new HashMap<String, Object>();
    productSupplierMap.put("supplierName", "Stuff R' Us");
    productSupplierMap.put("phone", "408-555-0987");
    context.put("ProductSupplier", productSupplierMap);
}

After that method has run, the Print Template can use the variable $ProductSupplier.phone, just as though the data had originated in the platform.

Troubleshooting Tips

Velocity syntax errors cause the Velocity process to die.
Not all browsers display an error message when such errors occur. (Firefox does)
If you're seeing what appears to be a "silent failure', try switching browsers.
When the error occurs in a Word or PowerPoint template, it can be difficult to pinpoint the cause of the error.
Converting the template to HTML helps to pinpoint the line that has the problem.
When a Word or PowerPoint template fails, a process instance is left running, with a corrupted document that can't be read. Subsequent attempts to open the document report an error message, and an additional process is left running.
On a PC, the processes can be found and killed from the Task Manager.
Each open process makes a temporary copy of the template, with a name like, "Template.docx (1)".
The existence of those undeletable template copies is a sign that processes have been left running.
When the processes are killed, the template copies disappear.

@@ Line 108: / Line 108: @@
 :''Learn more:'' [[Create a Compound Print Template]]
+==Processing Related Records in HTML ==
 ===About Related Record Variables===
 In a {{type|}}, fields from ''related records'' can be added to a Document Template. (That is, records from an Object that has a [[Lookup]] to the current object.)

Search

where to start

learn more

Tools

Personal tools

Difference between revisions of "Print Templates"

Latest revision as of 02:32, 11 September 2013

Contents

About Print Templates

Examples

Print Template Formats

How Print Templates Work

Working with Print Templates

Add a Print Template

Edit a Print Template based on a Platform JSP/HTML Page

Edit a File-Based Print Template

Use a Template to Print a Record

Use a Template to Print a List of Records

Insert Images and Template Variables

Create a Compound Print Template

Processing Related Records in HTML

About Related Record Variables

Finding and Using Related Record Variables

Finding Related-Record Variables

Processing Related Records in a Loop

Special Considerations for Subform Variables

Sample Template for an Order Invoice

Customizing Data Sent to the Template with a Print Template Class

About Print Template Classes

Coding a Method in a Print Template Class

Configuring a Print Template to use a Specified Class and Method

Accessing Lookup Target Records

Accessing Data in Related Records

Examples

Changing Field Data

Example: Adding a New Field

Example: Adding a New Object

Troubleshooting Tips