This page last changed on Mar 15, 2007 by ganand.

Confluence pages can be output to PDF and some resulting PDF content can be modified. While page content itself is not open to customisation without major source-code modifications, this guide covers the easier task of modifying the plain text contained in page titles, headers and footers.

How To Edit Content

Confluence uses Apache FOP to write Confluence content to XSL-FO format, and uses Velocity macro files to render PDF headers, footers and page titles. For information on more content editing, study the XSL-FO examples.

Always stop Confluence before editing a Velocity macro file. Users who are stuck can obtain technical assistance by posting the modified Velocity file to the Confluence Developer Forum.

List Of PDF-Related Files

Under your Confluence install directory:

.../confluence/WEB-INF/classes/com/atlassian/confluence/importexport/common_header_fop.vm
.../confluence/WEB-INF/classes/com/atlassian/confluence/importexport/common_footer_fop.vm
.../confluence/WEB-INF/classes/com/atlassian/confluence/importexport/common_fop.vm
.../confluence/WEB-INF/classes/com/atlassian/confluence/pages/Page.pdfexport.vm
  • The above example is for Unix-based systems, so Windows users should use back-slashes instead forward-slashes
  • An example Windows install directory is C:\confluence-2.2.9-std
  • An example Linux install directory is /opt/confluence-2.2.9/

Text

Inserting the example XSL-FO tag below into the relevant Velocity macro file will output a new line with This text is printed in plain text.

<fo:block text-align="left" font-family="$generalUtil.getDefaultFontFamily()" color="#0050B2">
    This text is printed
</fo:block>

Images

There are two steps involved in adding images to the header and the footer:

  1. You need to modify common_fop.vm and adjust the margins, and sizes of the two regions (region-before and region-after) to fit in the image.
    <fo:region-before extent="1cm"/>
    <fo:region-after extent="1cm"/>
    

    In the example above, change the "1cm" value to allow yourself as much space as you need for your customization.

  2. Insert the example XSL-FO tag below into the relevant Velocity macro file to embed the local image C:\operahouse.png into the PDF.

    If using windows, please make sure to use forward slashes, instead of backslashes while specifying directory paths.
    Eg: Use "c:\images\operahouse.png" for windows and "c:/images/operahouse.png" for Unix.
<fo:block>
<fo:external-graphic
width="auto" height="auto"
src="c:/images/operahouse.png"  />
</fo:block>

Modify Page Title for Single Page Export

This title appears once on the first page of the PDF. An example title is

Demonstration Space : Timesheets
This page last changed on Nov 02, 2006 by Administrator

To modify the page title, go to your Confluence install directory and modify the Velocity macro file

...\confluence\WEB-INF\classes\com\atlassian\confluence\pages\Page.pdfexport.vm

The file contents are shown below

<fo:block text-align="left" font-family="$generalUtil.getDefaultFontFamily()" font-weight="bold" color="#0050B2">
    $generalUtil.escapeXml($page.space.name) : $rendererBean.nativeToAscii($generalUtil.escapeXml($page.title))
    <fo:leader leader-pattern="rule" leader-length="100%"/>
</fo:block>
<fo:block color="grey" font-size="8pt" space-after.optimum="12pt">
    This page last changed on $generalUtil.format($page.lastModificationDate) by
    <fo:inline color="#0050B2">$!page.lastModifierName</fo:inline>.
</fo:block>

Explanation of the Velocity code from the above example

Velocity Code Prints
$generalUtil.escapeXml($page.space.name) Space Name
$rendererBean.nativeToAscii($generalUtil.escapeXml($page.title)) Page Name

Modify Page Headers for Space Export

By default, no page header is printed with PDF exports. To add one, go to your Confluence install directory and modify the Velocity macro file

...\confluence\WEB-INF\classes\com\atlassian\confluence\importexport\common_header_fop.vm

Example Header Modification

In between the two FO lines, add

<fo:block text-align="left" font-family="$generalUtil.getDefaultFontFamily()" color="#0050B2">
    Custom Header
</fo:block>

Modify Page Footers for Space Export

Page footers appear on the bottom of every page. An example footer is

Document generated by Confluence on Dec 11, 2006 09:35                    Page1

To modify the footer, go to your Confluence install directory and modify the Velocity macro file

...\confluence\WEB-INF\classes\com\atlassian\confluence\importexport\common_footer_fop.vm

Example Footer Modification

To produce this footer

Created on Dec 11, 2006 11:43
Copyright Altassian Software

Locate this line in common_footer_fop.vm

<fo:block>Document generated by Confluence on $generalUtil.formatDateTime($exportDate)</fo:block>

Replace it with the following Velocity code

<fo:block>Created on $generalUtil.formatDateTime($exportDate)</fo:block>
<fo:block>Copyright Altassian Software</fo:block>

Modify PDF Page Size for Space Export

The default PDF page size is A4 (210mm x 297mm or 8.27in x 11.7in). Modify the file under your Confluence install directory:

.../confluence/WEB-INF/classes/com/atlassian/confluence/importexport/common_fop.vm

This file is pretty self-explanatory. Change to the following values:

  • page-width="21.59cm"
  • page-height="27.94cm"

Optionally you can modify the margins. To give the page a half-inch margin all around:

  • margin-right="1.27cm"
  • margin-left="1.27cm"
  • margin-bottom="1.27cm"
  • margin-top="1.27cm"

I am trying to take pdf export of confluence pages. Thus created pdf has autogenerated header (like 'This page last changed.....') and footer (like 'Document generated by Confluence on....' and page no.)

Is it possible to turn this auto generated header/footer without having to going into velocity template changes?

Posted by jay_inbasket@yahoo.com at Feb 15, 2007 12:32

Hi Jay,

Unfortunately at present, the only way to change the header/footer in PDF exports is to modify the velocity templates. There is an existing request for this feature in JIRA.

http://jira.atlassian.com/browse/CONF-2079

Please add yourself as a watcher so that you can keep up to date. Additionally, you can also vote for the issue's popularity.

Regards,
Kevin

Posted by ktran at Feb 21, 2007 19:30

Hi,

I updated and debugged my FO with Apache's FOP but when I piece it back together in the velocity templates, a Confluence PDF export doesn't produce the same results.

A search through the Confluence folder for JAR files yielded this:

confluence/confluence/WEB-INF/lib/fop-0.20.5-atlassian-20060626.jar

...and it appears I was working against version 0.93 of FOP.

Do I interpret this correctly? That Confluence is using an Atlassian-modified version of the previous release of FOP??

Any chance I can upgrade it myself (i.e. is the API still compatible?) or should I log a JIRA case against modernizing the FOP version in Confluence?

Posted by olivier.dagenais@formark.com at Feb 22, 2007 20:11

Hi Olivier,

Yes we are indeed using the 0.20.5-atlassian-20060626 in Confluence 2.3.3 onwards. Unfortunately, the version you are using 0.93 has a fairly different API and is not compatible with 0.20.5. You should be able to use 0.20 release without change but we already have the latest. In other words, you can't just simply drop the newest jar into the web-inf/lib directory.

FYI - we are in a process of trying to upgrade the FOP package again, as there seems to be some bugs in this version.

Please create a support case in http:/support.atlassian.com if you require further help.

Thanks,
Ivan

Posted by ivan@atlassian.com at Mar 06, 2007 18:29

Good to know, thanks!

Any ETA on this upgrade? Or perhaps a JIRA issue number I can subscribe to??

Thanks, Ivan!

Posted by olivier.dagenais@formark.com at Mar 06, 2007 18:51

Yes Olivier, we do have a related bug opened in JIRA already. Please follow the progress there.

In particular, the comment from Charles, is specifically aiming on the update of the FOP library.

We think we've got a solution for this, but it involves upgrading to an unreleased development version of one of our dependent libraries. So fixing the problem is going to require a lot of very careful testing for regressions elsewhere.

Let me know if you need additional information.
Thanks,
Ib

Posted by ivan@atlassian.com at Mar 07, 2007 00:28
Document generated by Confluence on Mar 22, 2007 21:00