HTML based custom reports

To adjust PDF-reports easily, HTML-based custom reports can be used. 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 XML-report.

A predefined HTML-template is contained in all installer packages for Desktop and Server/CLI.

 

This predefined template can be found in:

  • Server/CLI: ../cli/var/Reports/Templates
  • Desktop/PlugIn: User Preferences/callas software/[pdfToolbox or pdfaPilot] version/Reports/Templates (using Desktop/PlugIn, a HTML-based report must have been generated at least once, in order to have these these files created)

The predefined template contains several folders and files

  • index.html the template in HTML format
  • manifest.xml a XML file which defines information needed as content for the report, to be delievered by the engine
  • /css contains a style sheet
  • /fonts contains used fonts
  • /img contains used images
  • /scripts contains used JavaScripts


Note:
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 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 are provided by default. Other parts like a preview image, comparision images or an XML report can be also requested here. Even a XML report can be ordered to enable picking up additional information about the PDF or executed fixups or checks using JavaScript. The display name in the user interface is defined here as well. For developing purposes, the internally generated, filled HTML represen-­tation of the report can be maintained to review changes in the template files also in a browser.

Note: The HTML converter is using WebKit, so it is recommended to use Safari (or Chrome, which is based on a spin-off of WebKit) as a browser.

Request basic informations about PDF 

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

Purpose

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

Preview images of pages 

<x:results>
   <x:preview resolution="150" page="1"/>
</x:results>

Purpose

Rendering of images of one or more pages for visual represenation of the PDF in the report.
Images are exported into the file system as png files. The folder in the intermediate HTML is:

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

More than one page preview can be exported (starting with pdfToolbox 10/pdfaPilot 8, until then only 1 image could be exported) when the manifest.xml has the following entry:

<x:results>
   <x:preview resolution="100" firstPage="1" lastPage="30"/>
</x:results>

To create previews of all pages, the "lastPage" parameter can be set to "-1".
The links to the pages are also listed in cals_params.js.

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>

Purpose:

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

Parameters

resolution resolution used in ppi for rendering the comparision

Keep the temporarily generated files 

<x:settings>
   <x:keeptemp>true</x:keeptemp>
</x:settings>

Purpose

Temporarily generated files like the filled index.html, CSS-files, images, XML-reports and used JavaScripts will not become deleted after finnishing the PDF report.

Parameters

false files become deleted (default)

true files will not become deleted

Creating a XML report for additional content 

<x:results>
   <x:xmlreport path=xml/report.xml inkcovres=72 inkcovbox=TrimBox/> </x:results>

Purpose

Requests a XML report of the performed profile to extract additional infor-­mation using JavaScript which can be used in the report. Determining the ink coverage will only take place if one of the respective parameters exists.

Parameters

inkcovres resolution in ppi, used for determining the effective ink coverage of each page in the PDF (optional, default: 300)

inkcovbox page geometry box of which the effective ink coverage will be determined (optional, default: CropBox)

The HTML template

 

The HTML template can easily be modified using an appropriate code-editor or enhanced text-editor.

The index.html of the default overview template references a stylesheet, two JavaScripts as well as a number of images.

The provided HTML-template already contains some dummy data, which is automatically replaced by actual content when a new report is gener-­ated. So, when doing adjustments to the template with custom profiles and PDF files, it is recommended to keep the temporarily generated files for debugging, as a basis for modifications and their review in a browser.

  • Note: It is possible to use image formats (like JPEG or PNG) as well as PDFs for positioning visual content like logos. If you want to debug your HTML in an HTML Browser you may want to display an image instead of the PDF reference. You can do this by putting identically named files for images and PDF next to each other. The PDF file must be referenced in the img tag in the HTML-template. The usage of PDF files allows for higher quality of logos in the resulting PDF report.

How the HTML-template works

The provided HTML-template contains already all document and process-­ing information which can be supplied directly from the application.

You will find cals_params.js and cals_overview.js which are used by the engine to create and render the HTML. Please do not modify these files. For adding more functionality it is recommended to do this in new, own JavaScript files, which have to be linked in the index.html of course.

Examples for template modification

callas software is providing a number of sample templates, which can be downloaded as tewo ZIP archives from the links below.

These two ZIP archives contain samples in the form of complete template folders including comments in the HTML-, CSS- or JavaScript-files and the result as a PDF.

callas_Tutorial_HTML-reports_-_Adjusting_layout_and_appearance.zip
callas_Tutorial_HTML-reports_-_Adding_content_from_XML_report_files.zip

Extended functionality starting with pdfToolbox 10/pdfaPilot 8

Please see the article "Template based reports" for new possibilities invented with pdfToolbox 10/pdfaPilot 8.

0 Comments

Send Your Comment

E-Mail me when someone replies to this comment