ICXT - PDF Export templating documentation

1. Abstract

The HCL Conncetions 360 asset provides a module for PDF export functionality of all major HCL Connections content objects (Wikis, Blogs, Activities, Forums). The creation process of this PDF is highly customizable to meet the demands for the countless use-cases of PDF documents, such as marketing, documentation, compliance or archiving.

The PDF generation uses HTML documents to determine what should be rendered, and in what way. Therefore, the PDF content can also be styled and altered as such – just by providing the desired html, css (stylesheets) and javascript code. With this, we also offer the necessary hooks and interfaces to inject your changes into the predefined rendering process. Just define a template with the desired changes and the generation process will take them into account.

In this document, we will provide information on how to define and use templates, and how to customize them to let the PDF outcome match your needs and expectations.

2. Template structure

There can be multiple defined templates for different scenarios. In the generation overview the existing ones will be available via a selection dialoge. The templates have to be saved in a configurable location and have to satisfy the following file-structure:

• header.html – mandatory
  • The definition of how the header should look like in html code. This will be used for the header section on every PDF page. Only the content within the html body tag needs to be provided.
• footer.html – mandatory
  • The definition of how the footer should look like. This will be used for the footer section on every PDF page. Only the content within the html body tag needs to be provided.
• style.css – optional
  • Definition of how the elements should be shown. This follows the usual styling rules based on attribute name, class or id. See section class names for information on how the predefined content can be styled.
• main.js – optional
  • Functions that should be executed before rendering the content. This can be simple scripted tasks that have to be done dynamically, like changing the sequence, adding classes for more refined styling or removing content.
• template.properties – optional
  • This file can contain key-value mappings in the Java Properties format. The mappings can then be used to dynamically replace placeholders that are defined in the header and footer section. See section properties for information on how to use them, and what predefined replacement options are available

Mandatory, as stated for some files above, means that without those files a template will not be valid and therefore will not be included in the template selection dialoge.

3. Using and testing a template

To make a template available to the PDF export, copy a template folder containing the necessary files into the templates directory. This will be the ic360.configpath configuration path defined by your administrators, followed by /pdf-templates. As an example, if your configuration path is /tmp (temporary files directory on unix), your template named ‘Example’ should be in the following path:

/tmp/pdf-templates/Example

Remember that at least the files header.html and footer.html have to be inside your template. After a restart of the service, this template will now be available in the User interface template selection dialoge.

After this, your template will be read in during runtime, which means that changes will always take effect immediately after saving them.

This way you can also test your template. Update it and refresh the website rendering your pdf to find out how certain changes effect the outcome.

4. Header and Footer customization

Websites can show anything you want them to. And they use the same underlying technologies as our PDFs. Therefore, the header and footer can be customized any way you want.

It has to suffice the general rules of HTML. This means, all content has to be put into the appropriate HTML attributes (div for containers, p for paragraph, img for pictures and so on).

Additionally, only the content withing the HTML body tag has to be on the file. The surrounding content will be generated in the process.

An example header could therefore look like this:

<div class="header">
    <div class="app_icon {content.type}"></div>
    <div class="header_content">
        <h5 class="header_title">{content.title}</h5>
        <p class="header_creation_time">{pdf.creationtime}</p>
    </div>
</div>

An example footer could therefore look like this:

<div class="footer">
    <p class="pull-left">Created with {pdf.createdwith}</p>
    <p class="pull-right">Page {pdf.page.current} of {pdf.page.count}</p>
</div>

The {something} attributes are placeholders, that will be replaced during execution. For more information on this, see section properties

Styles (CSS) and Scripts (JavaScript) can also be included inline. However, you can also use the supported templating files described in section styles and section scripts

5. General styling options

The styling for the content can be done in CSS (Cascading Stylesheet) files. As always, style information can be given on an attribute-, class- or id level. There are various predefined rules for the current styling, that can be found in the Appendix at default styles appendix

The rules defined in your template will overwrite them if necessary, so that you can take complete control over how content will be rendered. The comments in the file will give you information about what containers are available and how they can be styled.

Note that with styling the HTML, you are still bound the nature of PDF-appearance, especially regarding the size of content. You will have to suffice DIN-norms and your containers have to be big enough to fit the content defined within. Otherwise, the outcome might not look the way you imaged.

6. Alter the static content dynamically

As with the aforementioned topics, JavaScript (ECMAScript 5) can also be used for PDF generation. This can analyse the created content to modify certain things before the final export happens. JavaScript is the most restricted content altering technique of the mentioned ones. This is because of an obvious reason: Once a PDF is created, it can not be changed.

JavaScript however, mainly is used to dynamically change content based on events and actions. This can not be done for the PDF generation. JavaScript can alter the content but has to have a static result in the end. This can be compared to taking a picture of a website. Even if JavaScript always changes the view dynamically, the things seen on the picture will not.

Things that JavaScript can be used for, are:

• Change the table of contents based on how long the document content is

• Change the sequence of the different content items, or within the content items (e.g. comments before the actual content)

• Highlight specific words or sections, that can’t be highlighted by pure CSS (e.g. because they weren’t annotated with appropriate classes or ids)

• Remove certain content for compliance reasons

Beware, that JavaScript will always increase the processing power necessary to generate the PDF. For Websites the amount of JavaScript executed can usually be very high due to client side processing. In this case, the client (PDF export tool) is on the server too. Therefore, with too many functions executed during PDF creation (and many people possibly simultaneously using it), the creation duration and server load will increase.

7. Leveraging placeholders

The only thing out of the ordinary regarding HTML techniques are placeholders. This basically means, that placeholders in a form of {placeholder_name} can be added within the templates, opposed to static strings. The advantages of this are, that templates can be reused by just changing the properties and often used dynamic attributes such as the content editor, creation time, content name and so forth can be leveraged (without having to use JavaScript functions).

An example usage of placeholders would be to have a department name change within different templates.

For this, define a template (e.g.) header, such as:

<div class="header">
    <h5 class="header_title">{mycompany.department.name}</h5>
</div>

Then create a file template.properties within the template and add following content:

mycompany.department.name=Finance Group

In the rendered version, all occurrences of {mycompany.department.name} have then be exchanged for Finance Group.

For dynamic placeholder, we provide the following ones:

• pdf.page.current
  • the current page of the pdf
• pdf.page.count
  • the number of pages in total
• pdf.creationtime
  • the time of creation, formatted as “Weekday Month Day, Year”
• content.author.name
  • the author of the rendered object, e.g. the wiki author or blog entry author
• content.title
  • the title of the rendered object, e.g. the wiki name or blog entry title
• pdf.template.path
  • the path this template is located on the file system - can be used as a placeholder for template image paths ({pdf.template.path}/logo.png)

Additional requests for dynamic placeholders will be evaluated and implemented, if the placeholder is generic enough to be used in various scenarios.

8. Prerequisites

To be able to use the PDF export functionality, following requirements have to be met.

• The ICXT PDF export function is licensed
• The leveraged open source PDF generation tool must be installed
  • currently only wkhtmltopdf (http://wkhtmltopdf.org/) with patched qt is supported
  • this tool is not installed together with ICXT and has to be provided by your company
• Your account has to be enabled for using the PDF export
  • This will either be done by a per user basis for administrative use, or globally defined for user groups and access rights