Configuring and Customizing JIRA PDF View

Table of Contents

Customizing the PDF Content and Layout

Both the PDF document content and look is defined by a single template file, which is located here: JIRA_HOME/atlassian-jira/WEB-INF/classes/templates/plugins/pdfview/issue-fo.vm.
This is a Velocity / FO template, so you need to be aware with both the Velocity template language syntax and the FO syntax to customize it. Don't worry, the basics are simple. Here is a couple of good starting points though:

1. You can probably understand almost everything just by looking at the sample template files shipped in the classes/templates/plugins/pdfview directory of the plugin distribution package.
2. Velocity has a simple, but powerful template language. The best documentation available on this is the Velocity User Guide, that illustrates everything with examples.
3. Various XSL-FO tutorials are available on the web (search for "xsl fo tutorial" with Google), but it might be a good idea to start with reading this tutorial if you want to pick up the FO basics quickly.

Issue → PDF Rendering Process

In case you are interested in the lower level details, the two stage PDF rendering process works like this:

1. First, issue-fo.vm is rendered through Apache Velocity: it replaces the variable references (like $issue.description or $issue.resolutionObject.name) by their actual values.
2. Then, the resulted FO document is transformed into PDF by Apache FOP.

Reading Templates without Caching for More Productive Template Development

By-default your fo.vm files are cached: they are not re-read for each rendering, but read only once. That means better performance for production use, but slower development (you actually need to restart your container after every little change in the templates).

This kills development productivity, but there is a neat solution: see the 2nd question in our FAQ.

Domain Objects and Velocity Tools Available in the Templates

During the first stage, you can access the following beans from the Velocity context.

Note that the story doesn't come to an end here. You can access many other interesting information starting from these points of the object graph. For example, retrieving the project related and its latest version:

#if($issues.size() != 0)
	#set($project = $issues.get(0).projectObject)
	#if($project.versions.size() != 0)
		#set($lastVersionIndex = $project.versions.size() - 1)
		#set($version = $project.versions.get($lastVersionIndex))
	#end
#end

Again, best advice is: take a look at the sample templates shipped in the distribution.

Encoding Problems with International Templates

You are writing your template text directly to the fo.vm files which are actually plain text documents stored in the file system. You might encounter hard to track encoding problems, because your text editor and your file system must encode the text files properly.
To prevent these potential problems, there is an easy trick: since the fo.vm files are XML files, you can encode your template text characters into NCRs. With this, encoding doesn't matter anymore!
Using this web based converter tool you can:

1. paste your template text to the Characters: box
2. click Convert above Characters:
3. copy the converted string from the Hexadecimal NCRs: box to your text editor. (These are just hex characters, so there will be no problem.)

Configuring PDF Output

Note that modifications in fop-config.xml will require JIRA to restart, otherwise your changes will not be picked up.

Configuring Paper Size, DPI and Such

The FO → PDF conversion settings (like paper size, DPI, font paths and base URLs for relative URLs, etc.) can be configured in JIRA_HOME/WEB-INF/classes/fop-config.xml. See more information about the options in the original FOP "Configuration" page.

Another option is to configure paper size and such directly in fo.vm templates:

<fo:layout-master-set>
	<fo:simple-page-master master-name="A6-landscape" page-height="10.5cm" page-width="14.8cm" margin=".6cm">
		<fo:region-body region-name="page-body" />
	</fo:simple-page-master>
</fo:layout-master-set>

Configuring a Custom Character Set

Using custom fonts is a very common problem, especially if you need special glyphs like in case of Asian languages.

Follow these steps to add a custom font:

1. Get the font file (PFM, TTF, etc.), for example trebuchet.ttf.
2. Generate the metrics file msmincho.xml as written here. (You will, unfortunately, need to download FOP 0.93 for this.)
3. Copy the font file msmincho.ttc and the metrics file msmincho.xml to a directory that is accessible by JIRA, like /myfonts.
4. Register the fonts for FOP by editing JIRA_HOME/WEB-INF/classes/fop-config.xml. First, you need to set the base URL for resolving fonts:

   <!-- Font Base URL for resolving relative font URLs -->
   <font-base>file:///myfonts/</font-base>

   Then register the font by adding the following lines to the <fonts> section:

   <font metrics-url="trebuchet.xml" kerning="yes" embed-url="trebuchet.ttf">
   	<font-triplet name="trebuchet" style="normal" weight="normal"/>
   	<font-triplet name="trebuchet" style="normal" weight="bold"/>
   	<font-triplet name="trebuchet" style="italic" weight="normal"/>
   	<font-triplet name="trebuchet" style="italic" weight="bold"/>
   </font>

5. Use those fonts by referencing their names in your templates. You can apply a font on any level: page sequence, paragraph or span.

   <fo:page-sequence master-reference="A4" font-family="trebuchet">

6. Restart JIRA.

See more information about registering custom fonts in the original FOP "Fonts" page.

Configuring Multiple PDF Views with Different Templates

Say, you want to have a multiple PDF views with a different templates: one for issue details export and another for release notes documents.

This is possible: you can have any number of views, but this must be configured by modifying the atlassian-plugin.xml that is inside the plugin JAR jira-pdfview-plugin-xxx.jar.
Follow these steps:

1. 'cd' to the JIRA_HOME/WEB-INF/lib directory.
2. Extract the XML file via "unzip jira-pdfview-plugin-0.9.jar atlassian-plugin.xml".
3. Edit atlassian-plugin.xml (via "vi atlassian-plugin.xml", for example) and uncomment these lines:

   <!-- uncomment this to have a 2nd view
   <single-issue-view key="issue-pdf-relnotes" name="PDF (Relnotes)" class="com.atlassian.jira.plugin.ext.pdfview.view.PdfIssueView" state="enabled" fileExtension="pdf" contentType="application/pdf">
   	<order>1001</order>
   	<resource type="velocity" name="fo" location="templates/plugins/pdfview/releasenotes-fo.vm" />
   </single-issue-view>
   -->

   Adding a third or fourth view is the same, you just have add this section again and again. Please make sure that it has a unique key and the "fo" resource definition points to the right template.

4. Put the XML file back in the jar via "zip jira-pdfview-plugin-0.9.jar atlassian-plugin.xml".
5. Delete the extracted file via "rm atlassian-plugin.xml". If you leave the extracted file there (don't do step #5), then you can just do steps #3 and #4 whenever you want to make another change to the file.
6. Restart JIRA.

_{Thanks goes to Steve Johnsonten for this guide.}