PDF Generation in Unify

From VYRE

(Redirected from PDF Templates)
Jump to: navigation, search

Contents

Pre-Requisites

Understading of Data/File Stores in Unify

Item-Search Results Portlet

Item-Display Portlet

XSLT

XSL-FO

Licence key for PDF Tempaltes feature. if you do not have a licence key, you can request one through JIRA.

Introduction

There are two main types of stores in Unify, Data –Stores (that allow user to save textual data) and File-Stores (that allow users to save binary files for e.g. Images, Videos, PDF docs etc.). The textual data saved in Data-Stores can also be converted to PDF document so it can be printed, downloaded etc. The user has full control over the format and display of the pdf document through the use of XSL-FO. The users need to be XSL-FO savvy in order to generate PDF documents out of Data-Store items. This document will explain the steps involved in the process with examples.

How it works

There are mainly 4 different steps involved in pdf generation.

  • We need to write XSL that will generate data we need to display on the generated PDF
  • We need to write XSL-FO document that will produce a PDF from the above data.
  • Create a PDF Template in Unify that will use the components generated in above two steps and bind them together.
  • Put a link on the required page whom user will click to generate a PDF

Step 1: Writing XSL that will generate custom data we need in the PDF

This is the most important step in the process as before anything we need to have data that we want to display in the generated PDF. Let’s say we have an item display page that contains an “Item-Display Portlet” and is displaying the name and description of the any item.


Image:ItemDisplayPage.png


In the above page, we want to put a link that will allow users to download this data as PDF. The Item-Display portlet (or if you are using Item-Search Results Portlet) generates a lot of XML that we probably don’t need for our PDF. Please note that the content in XML will change depending on each item but the format would be same. By format we mean that every Item-Display portlet would have <result> as its root element followed by <data-item> if you are viewing an item from datastore and <file-item> if item being viewed is from filestore. In our case we are only displaying Name and Description on a page and that’s what we want in PDF.

So we need to separate the required data (in our case name and description) from the returned XML. We will achieve this by writing a XSL that reads XML (generated by the portlet we are using to display item) and returns limited information. This XSL must be created under Item-Detail folder in XSL otherwise it would not be accessible later on. This XSL is called pre-processing XSL.


Image:ItemDetailFolder.png


Let’s call this XSL that we are creating “Pre-processor XSL”. Copy the following code in Pre-processor XSL. (This XSL will only work for any item from Datastores)

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE xsl:stylesheet [
	<!ENTITY nbsp   "&#160;">
	<!ENTITY copy   "&#169;">
	<!ENTITY reg    "&#174;">
	<!ENTITY trade  "&#8482;">
	<!ENTITY mdash  "&#8212;">
	<!ENTITY ldquo  "&#8220;">
	<!ENTITY rdquo  "&#8221;"> 
	<!ENTITY pound  "&#163;">
	<!ENTITY yen    "&#165;">
	<!ENTITY euro   "&#8364;">
]>
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">  
 
	<xsl:output method="xml" version="1.0" omit-xml-declaration="no" indent="yes" encoding="ISO-8859-1"/>
 
	<xsl:template match="data-item">
		<document>
			<h1><xsl:value-of select="name" disable-output-escaping="yes" /></h1>
			<p><xsl:value-of select="description" disable-output-escaping="yes" /></p>
		</document>
	</xsl:template>
 
</xsl:stylesheet>

In the above XSL we have put h1 tags around name and p tags around the description and enclosed both in document tags. This is because we will use these tags in our XSL-FO later to style how we want name as description to appear on PDF document.

Step 2: Creating XSL-FO that will generate PDF

In the previous step we wrote a XSL that only returns data we need to display in our PDF. In this step we will write an XSL-FO (XSL Formatting Object) to generate PDF with this data. The new XSL-FO must be created in Publishing->XSL->Item detail or in its sub-folders otherwise it will not be accessible by the system. Create a new XSL and copy the following code in it:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE xsl:stylesheet  [
	<!ENTITY nbsp   "&#160;">
	<!ENTITY copy   "&#169;">
	<!ENTITY reg    "&#174;">
	<!ENTITY trade  "&#8482;">
	<!ENTITY mdash  "&#8212;">
	<!ENTITY ldquo  "&#8220;">
	<!ENTITY rdquo  "&#8221;"> 
	<!ENTITY pound  "&#163;">
	<!ENTITY yen    "&#165;">
	<!ENTITY euro   "&#8364;">
]>
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:fo="http://www.w3.org/1999/XSL/Format" exclude-result-prefixes="fo">
	<xsl:output method="xml" version="1.0" omit-xml-declaration="no" indent="yes"/>
 
	<xsl:template match="/">
 
		<fo:root xmlns:fo="http://www.w3.org/1999/XSL/Format">
 
			<fo:layout-master-set>
				<!-- layout for all pages -->
				<fo:simple-page-master master-name="all" page-height="29.7cm" page-width="31cm" margin-top="1cm" margin-bottom="2cm" margin-left="2.5cm" margin-right="2.5cm">
					<fo:region-body margin-top="3cm" margin-bottom="2cm" column-count="2" column-gap="0.25in"/>
					<fo:region-before extent="3cm"/>
					<fo:region-after extent="2cm"/>
				</fo:simple-page-master>
			</fo:layout-master-set>
 
			<fo:page-sequence master-reference="all">
				<fo:static-content flow-name="xsl-region-after">
					<fo:block font-size="10pt" text-align="start" space-before.optimum="6pt">
						Vyre demonstration document. All rights reserved. 2006
					</fo:block>
				</fo:static-content>
				<fo:flow flow-name="xsl-region-body">
					<fo:block font-size="14pt" font-family="sans-serif" line-height="18pt" space-after.optimum="15pt">
						<xsl:apply-templates select="document/*" disable-output-escaping="yes" />
					</fo:block>
				</fo:flow>
			</fo:page-sequence>
 
		</fo:root>
 
	</xsl:template>
 
	<!--
		Heading 1: the code below syles any data in <h1> tags
	-->
	<xsl:template match="h1">
		<fo:block text-align="left" white-space-collapse="false" linefeed-treatment="preserve" line-height="14pt" color="#0E5596" font-size="24pt" font-family="Helvetica" space-before="10pt" space-after="20pt">
			<xsl:value-of select="current()" />
		</fo:block>
	</xsl:template>
 
	<!--
		Paragraph: the code below styles any data in <p> tags
	-->
	<xsl:template match="p/text()">
		<xsl:if test="ancestor::p">
			<fo:block font-size="8.0pt">
				<xsl:value-of select="."/>
			</fo:block>
		</xsl:if>
	</xsl:template>
 
</xsl:stylesheet>

If you remember that in step 1, we put p and h1 tags around our data in XSL we created in Step 1. If you read the above XSL-FO you will find that we have defined styles for those tags. Lets say we call this XSL – FO we created PDF Generation XSL-FO.

Step 3: PDF Templates

In the previous two steps we created a XSL that generates data we need to show in our PDF (Step 1) and XSL-FO that will style that generated data (Step2) but we haven’t seen it working yet. We need a PDF template that will combine the two XSL files that we have written and generate PDF files.

Viewing existing PDF templates

By clicking on Files > Code Templates > PDF Templates you can see a list of all the PDF templates that have been created on the Unify instance. To delete a PDF template, simply click on the delete icon next to the template name. To create a new template click on the Create icon in the context menu (see the section below on creating a new PDF template).

Image:WIK-249.jpg

Creating a new PDF template

Follow the following steps in order to create a new PDF template:

  • Click on Publishing Module in Unify
  • Expand Files
  • Click on Code templates and then click PDF templates. (You will only be able to see this option if you have the licence key for this functionality. If you wish to receive a licence key please add it as a request on JIRA.)
  • You will see a list of PDF templates on the right side that have already been created.
  • Click on Create button on the top of the right side screen.
  • You will see a screen where you can configure this new template.
  • Enter an title you wish to in Title text area.
  • From Type dropdown, select XSL transforms to FO option.
  • Under Extensible Stylesheet Language (XSL) File dropdown, select the PDF Generation XSL-FO you created in Step 2 above.
  • Under Preprocessing XSL dropdown, select Pre-processor XSL you created in Step 1 above.
  • Click Save on the top of the screen.

Image:createPDFTemplate.jpg

Now we have created a PDF template that will generate our PDF. Please note the ID of this template as you will need it later. To find out the id of your template


  • Click on Publishing Module in Unify
  • Expand Files
  • Click on PDF templates. (You will only be able to see this option if you have the licence key for this functionality. If you wish to receive a licence key please add it as a request on JIRA.)
  • You will see a list of PDF templates on the right side that have already been created. As you have already created yours, it should be in this list with its ID next to it.

Editing existing PDF Templates

To edit the configuration of a PDF template, in the publishing module click on Files > Code Templates > PDF Templates. Then click on the edit icon next to the name of the PDF Template you wish to edit. In the edit screen it is possible to change the pre-processing or transforming xsl files, rename the template or alter the transform type (the options for transform type are to use an XSL-FO to generate a PDF, or to generate an XHTML document that will be rendered in a PDF).

Image:Wik-263.jpg

Step 4: Putting a link on the required page whom user will click to generate a PDF

Edit your XSL that is displaying item on a page and put the following link in there

<a href="{$context_path}/servlet/pdf/item.pdf?ITEM_ENT_ID={@id}&amp;ITEM_VERSION={version}&amp;PDF_TEMPLATE_ID=1&amp;globalXmlCfgId={@globalXmlCfgId}">Create PDF</a>

Where:

  • ITEM_ENT_ID: should be equal to the id of the item you wish to generate PDF of; this can be dynamically picked up from XML generated by the portlet
  • ITEM_VERSION: should be equal to the version of the item; the latest version can be dynamically picked up from the XML generated by the portlet
  • PDF_TEMPLATE_ID: should be equal to the ID of the PDF template you created in Step 3 above
  • globalXmlCfgId: set this parameter to get fine-granular XML output, according to Global XML configuration defined. This functionality was introduced in Unify 4.6. If you are using a previous version this feature will not be available.


Save the XSL and go back to your Item-Display page and you should see a Create PDF link. Click on it and it should generate a pdf with name and description of the item you were viewing.

Personal tools