Quick Start: HTML Templates for Velocity PDF Reports

By Robin posted 07-13-2020 07:50

  

The Velocity PDF report output allows report writers to upload HTML templates with full Velocity script support.  including header and footer customization, and control of page size, margin, style, and layout.

This document explains the basics of writing HTML templates for Velocity PDFs.

Note
: Jama Software uses a third-party library called Aspose to create PDFs. Aspose supports CSS styles when creating a PDF, but there might be some variations in the output.

Basic HTML Template

The most basic template is plain HTML with a <body> section. Opening the HTML file in a browser is the fastest, easiest way to check the look and layout. If included, embedded Velocity code won’t render, which means there are no page breaks and headers or footers won’t render. To see all PDF features, the report must be uploaded and run in Jama Connect. When the HTML templates are uploaded to Jama Connect, they must have a .VM file extension. 

Here’s a simple template for reporting on all the item names in the current project: 

<html>
<head>
<title>All Item Names</title>
</head>

<body>
Project: $project.name
<ul>
#foreach( $itemId in $documentSource.getActiveDocumentIdsInProject($project.id) )
#set ($item = $documentSource.getDocument($itemId))
<li>$item.name</li>
#end
</ul>
</body>
</html>

HTML Template with Style

Here is the basic template with styles applied:

<html>
<style>
.item-list {
margin: 0;
padding-left: 1.2rem;
}

.item-list li {
position: relative;
list-style-type: none;
padding-left: 2.5rem;
margin-bottom: 0.5rem;
}

.item-list li:before {
content: '';
display: block;
position: absolute;
left: 0; top: -2px;
width: 5px; height: 11px;
border-width: 0 2px 2px 0;
border-style: solid;
border-color: #00a8a8;
transform-origin: bottom left;
transform: rotate(45deg);
}

/* Boilerplate stuff */

*,
*:before,
*:after {
box-sizing: border-box;
}

html {
-webkit-font-smoothing: antialiased;
font-family: "Helvetica Neue", sans-serif;
font-size: 62.5%;
}

body {
width: 790px;
font-size: 1.6rem; /* 18px */
background-color: #efefef;
color: #324047
}

html,
body,
section {
height: 100%;
}

section {
max-width: 400px;
margin-left: auto;
margin-right: 10px;
display: flex;
align-items: center;
}

div {
margin: auto;
}

</style>

<head>
<title>All Item Names</title>
</head>

<body>
<section>
<div>
<h2>Items for Project $project.name</h2>
<ul class="item-list">
#foreach( $itemId in
$documentSource.getActiveDocumentIdsInProject($project.id)
)
#set ($item =
$documentSource.getDocument($itemId))
<li>$item.name</li>
#end
</ul>
</div>
</section>
</body>
</html>

Applying Headers and Footers

If you want to include headers and footers on each page of your report, you must use the custom Jama Connect tags <jamaheader> and <jamafooter>. There are optional tags, so you can include one, both, or neither, however you design your report.

Although the header and footer tags appear within the body of the HTML document, Jama Connect treats them as separate HTML snippets. This means they can have their own style that’s defined within the opening and closing tags.

Velocity code can be applied to headers and footers just like anywhere else in the HTML file. For example, you can define whether to include a page number and its form.

Within header and footer tags, you can use two special field names to include the page number:

  • $$PAGE$$ — Replaced by the current page number in the PDF
  • $$PAGEOF$$ — Replaced by "Page x of y" in the PDF

The vertical space reserved for headers and footers is about 70 points each and can’t be changed. Footers align at the top of this reserved space, leaving a gap at the bottom of the page if the footer is narrow. 

Here’s an example of a footer tag with styling applied, using the PAGEOF field, and how it renders in the PDF: 

<jamafooter>
<style type="text/css">
table.innertable td {

border: none;
padding-left: 10px;
padding-right: 10px;
}

table {
font-size: x-small;
border-collapse: collapse;
width: 90%;
margin-left: 5%;
margin-right: 5%;
}

table, th, td {
border: 1px solid #ddd;
padding-left: 10px;
padding-right: 10px;
color: lightslategray;
}

.legalese {
text-align: center;
color: lightslategray;
font-size: xx-small;
}

</style>

<table>
<tr>
<td align="left" valign="center"><img src="/Users/krichards/Downloads/Jama-logo.png" style="vertical-align:middle">    <span style="font-size: larger" >Jama Software</span></td>
<td>Size: <b>Letter</b></td>
<td> </td>
<td>Scale: <b>NONE</b></td>
<td align="right">Page $$PAGEOF$$</td>
</tr>
</table>
<table class="innertable">
<tr>
<td>Title: <b>All Item Details</b></td>
<td>Doc Number: <b>099-2124307</b></td>
<td>Rev <b>E</b></td>
</tr>
</table>
<p>
<div class="legalese">THE INFORMATION CONTAINED HEREIN IS THE PROPERTY OF JAMA SOFTWARE. THE POSSESSOR AGREES TO THE
FOLLOWING:
</div>
<div class="legalese">TO MAINTAIN THIS DOCUMENT IN CONFIDENCE | NOT TO REPRODUCE OR COPY IT | NOT TO REVEAL OR
PUBLISH IT IN WHOLE OR IN PART
</div>
</p>
</jamafooter>

Images
Images in Velocity PDFs come from two sources:
  • Images that are part of an item that is stored in Jama Connect, such as WIRIS equations or images uploaded in rich text.
  • External images. 

External images are included using the <img> tag. The src property must refer to a web server or file system that is accessible by Jama Connect when the report is rendered.

NOTE: Due to an issue in Aspose, SVG images are automatically converted to the PNG file format.


Controlling Page Size and Margins

Jama Connect sets the page size for PDFs to letter size: 8.5 x 11 inches (612 x 792 points). The width must be set in the HTML template or content runs off the page. The vertical constraint doesn’t need to be included.

For edge-to-edge layout, use a maximum width of 790px width on <body> tags. By default, any component that wants to expand to fill the width of the browser window must be constrained to this width.

Margins on other components are set as usual with styles.

Here’s an example of the page width set in the body tag and two different margins for different content classes:

<style type="text/css">
html, body {
font-family: arial, tahoma, helvetica, sans-serif;                     
font-size: 10pt;            
max-width: 700px;
  }

  .textcontainer {            
margin-left: 80px;            
margin-right: 20px;            
column-count: 1;
}

.convo {             
margin-left: 80px;             
margin-right: 200px;
  }
</style>

Embedding Fonts

If you use fonts other than the default Jama Connect system fonts, you can embed them in the HTML template.

This is an example of the code to embed and use a font in the <style> section of the HTML template. The URL for the font must point to a location that is accessible by Jama Connect when the report is run.

<style type="text/css">  
@font-face {            
font-family: 'rakkasregular';            
src: url('/Users/krichards/Desktop/webfontkit-rakkas/rakkas-regular-webfont.woff2') format('woff2'),       
url('/Users/krichards/Desktop/webfontkit-rakkas/rakkas-regular-webfont.woff') format('woff');         
font-weight: normal                     
font-style: normal;      
  }

html, body {    
font-family: 'rakkasregular';    
font-size: 10pt;  

       

0 comments
33 views