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.
Structure of the custom HTML 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:
- When generating a report, click on the "Browse…" button in the settings section.
- A new window into the file system opens where the Template folder is stored.
- The overview folder is the predefined Template folder.
The predefined template contains several folders and files
- 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
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 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
-->. 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
false: temporarily generated files will be deleted (default)
true: temporarily generated files will be saved
Resolution for preview images
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.
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.
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"/>
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.
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.
<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:
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.