HTML based custom reports

As mentioned in the previous article, it is possible to generate a custom PDF report using a HTML template. The visual appearance is controlled by a HTML-Template and Custom Style Sheets (CSS), while the reported details are directly requested from the software itself or (optionally) parsed from an internally created JSON or XML report.

A predefined HTML template is always contained in all installer packages for Desktop and Server/CLI. The following screenshot shows how to get to the template folder:

  1. When generating a report, click on the "Browse…" button in the settings section.
  2. A new window into the file system opens where the Template folder is stored. 
  3. The overview folder is the predefined Template folder.

The predefined template contains several folders and files

  • index.html: the template in HTML format that references  a number of stylesheets, JavaScripts as well as a number of images
  • overlay.html: contains the company and product logo that is placed on top of every report page
  • manifest.xml: a XML file which defines information needed as content for the report, to be delivered by the engine
  • /css: contains a style sheet
  • /fonts: contains used fonts
  • /img: contains used images
  • /scripts: contains used JavaScripts

It is highly recommended to create a copy of the original template in a separate folder when starting to adjust a HTML-template based report.

The manifest.xml

The manifest.xml defines the set of information to be provided by the engine. This information will be used to fill up the details in the report based on the HTML-Template. Basic document information as well as all results of the processed profiles and a preview image are provided by default. Other parts like comparision images, a JSON or XML report, or parameters for optional document information can be also requested to enable picking up additional information about the PDF. These parts are commented out in the manifest by default. Here an example of an optional part of the manifest.xml:

As you can see, the hole XML report section is commented out by surrounding the code with  <!--  and -->. Down at the bottom you can find the XML report parameter. If you want to request a XML report, all you have to do is to uncomment the XML report parameter:

Parameters of the manifest.xml

Keep the temporarily generated files

<x:keeptemp>false/x:keeptemp>

If true the temporarily generated files like the filled index.html, CSS-files, images, JSON or XML reports and used JavaScripts will not be deleted after finishing the PDF report. They will be saved in a new folder with the extension .html instead. The folder name is identical to the PDF file. The folder is saved in the same location where the PDF file is located.

Options

  • false: temporarily generated files will be deleted (default)
  • true: temporarily generated files will be saved

Resolution for preview images

<x:defaults resolution="20"/>

This parameter allows you to set the default value for the resolution of all preview images. This value may be overwritten by the individual settings.

Options

  • resolution: resolution used in ppi (default: "20")

Request basic information about PDF

<x:dict>
   <x:overview/>
</x:dict>

If contained, document information and results of the performed profile will be available for using them in the HTML template.

Visual comparision of original and processed file

<x:compare>
   <x:document_a resolution=20/>
   <x:document_b resolution=20/>
   <x:diffresult resolution=20/>
</x:compare>

Include compare tree if comparison resources are used inside index.html.

Attribut

  • resolution: resolution used in ppi for rendering the comparision (dafault: "20")

Create a XML report

<x:xmlreport path="xml/report.xml" inkcovres="10" inkcovbox="CropBox"/>

Requests a XML report of the performed profile to extract additional information using JavaScript which can be used in the report. The ink coverage is determined only if one of the corresponding parameters is present.

Options

  • path: Destination path for XML report  (Default: "xml/report.xml")              
  • inkcovres: Resolution for ink coverage (Default: "10")
  • inkcovbox: Page box for ink coverage (Default: "CropBox")

Create a JSON report

<x:jsonreport path="json/report.json" quickcheck="default" />

Requests a JSON report to extract additional information. This option is available since pdfToolbox 14.

Options

  • path: Destination path for JSON report (Default:" json/report.json")
  • quickcheck: Optional relative path to a custom quickcheck config in the template folder. This quickcheck config will replace the internal default config (quickcheck="none" will disable the default config). More about the default Quick Check configuration file can be found here.

Page previews

<x:preview resolution="20" pageselector="1"/>

If this parameter is present in the manifest.xml, page previews are generated for the selected pages. The preview of the first selected page is added to the overview page of the preflight report for visual representation of the PDF file.
The preview images are exported into the file system as png files. The folder in the intermediate HTML is:

./img/cals_pages/../../cals_src_a.png

Options

  • resolution: Resolution in ppi for ink amount previews (Default: "20")
  • pageselector: Selected pages for previews (Default: "1")

Optional information (since pdfToolbox 14)

<x:inkamountheatmaps … />
<x:inkcoverage … />
<x:spotcolors … />
<x:separations … />
<x:pageinfo … />

Since pdfToolbox 14 there are five new parameters in the results section, that generate optional information about the document. Read more about that in the next article: HTML based custom reports – generate optional information