Generate PDF from HTML (Html2PDF)

Objective

Generate a PDF document from simple HTML content.

Parameters

Result

Operation status (Error / ErrorMessage) via PDFToolsStatus, plus a warning indication independent of the error status (see "Warning for unresolved fonts" below).

Header and footer

Header and Footer are independent PDFToolsHeaderFooter structures with three plain-text zones (no HTML) — LeftText, CenterText, RightText — aligned respectively to the left, center, and right of the header/footer area, so that, for example, a title can be shown on the left and the page numbering on the right at the same time. Any of the three zones can be used in Header, in Footer, in both, or in neither, independently.

In any of the three zones of Header or Footer, the tokens {page} (current page number) and {pages} (total page count) can be used, for example: RightText = "Page {page} of {pages}".

General note on HTML support

The conversion supports basic HTML (simple tags and styles). Full support for modern HTML/CSS should not be assumed (complex layouts, advanced table-like layout, external stylesheets, etc.); the fidelity level depends on the technology used by each generator (see Known limitations and restrictions).

List of minimum tested HTML tags

The following list of HTML tags is the minimum common tested set. Any unrecognized tag is silently ignored along with its inner opening/closing content, without reporting an error.

Attributes/CSS supported on those tags:

• color
• face / font-family
• size / font-size
• align
• bgcolor
• border
• cellpadding
• indent (<ul>/<ol>)

Box properties such as background, padding or margin via style on <div>/<span> do not have a guaranteed effect.

Equivalences between classic attribute and inline CSS (same result):

• <font face="Verdana"> = style="font-family:Verdana".

• <font size="14pt"> ≡ style="font-size:14pt" (without the pt suffix, the numeric value is interpreted as legacy index 1–7, not points).

• <font color="#1f3864"> ≡ style="color:#1f3864".

• <b> / <strong>, <i> / <em> ≡ style="font-weight:bold" / style="font-style:italic" (combinable, even nesting <span style="...">).

• <u> ≡ style="text-decoration:underline".

• <p align="center"> ≡ <p style="text-align:center">.

Page breaks: forcing a page break via CSS (page-break-before / page-break-after) is not supported; that instruction is silently ignored, without error. If the content exceeds the height of a page it does paginate automatically, and that natural behavior is the recommended way to produce multi-page documents.

Charts: there is no chart/graphics engine; to simulate a simple chart, a table with proportional width and background color (bgcolor / background-color) can be used.

Images: an <img> tag with width/height is embedded as a real image inside the PDF (not as an external reference).

Fonts and the pdfreport.ini file

Matching the behavior of GeneXus's standard PDF reports mechanism, font resolution is configured through the text file PDFReport.ini file format, always located in the folder immediately above the folder where the component resides (so a single pdfreport.ini can be shared by all applications/KBs that use the component from that installation).

File format

• Two loose properties at the beginning of the file (not inside any section):

• FontsLocation: one or more system folders where to look for font (.ttf) files, separated by ;.

• SearchNewFonts: true or false. Enables or disables automatic search for new fonts.

• Fonts Location (MS) section: for each font/style combination (for example Arial, Arial,Bold, Arial,Italic), it indicates the physical path of the resolved .ttf file (or empty if it could not be resolved).

• Embeed Fonts section: for each font/style combination, it indicates true/false according to whether that font must be embedded in the resulting PDF.

Looking up a font by name (both in the HTML and in the keys of these sections) is case-insensitive.

Example of valid pdfreport.ini content:

FontsLocation=C:\Windows\Fonts
SearchNewFonts=true

Fonts Location (MS)
Georgia=C:\Windows\Fonts\georgia.ttf
Georgia,Bold=C:\Windows\Fonts\georgiab.ttf
Georgia,Italic=C:\Windows\Fonts\georgiai.ttf
Georgia,BoldItalic=C:\Windows\Fonts\georgiaz.ttf

Embeed Fonts
Georgia=true
Georgia,Bold=true
Georgia,Italic=true
Georgia,BoldItalic=true

Behavior when the file does not exist

It is automatically created, with FontsLocation=C:\Windows\Fonts and SearchNewFonts=true as default values, and then the font sections are completed according to the behavior described below (equivalent to it "already existing" with those values).

Behavior when the file already exists

The fonts that appear in the HTML to convert are added to the existing sections in an incremental way (a font that already has a resolved physical path is never overwritten, even if a new search could resolve it differently). For each font in the HTML that does not yet have a resolved path (not declared, or declared with an empty path):

• If SearchNewFonts=true: the corresponding .ttf file is searched for in the folders indicated by FontsLocation. If found, its physical path is added in Fonts Location (MS) and true in Embeed Fonts. If not found, it is left (or added) with an empty path and false, and will be retried on the next run as long as it remains unresolved.

• If SearchNewFonts=false: no search is performed; the font is still added to both sections, with an empty path and false (left documented to be completed manually).

• If the file did not have FontsLocation or SearchNewFonts declared (for example, due to manual editing), they are recreated with the same default values as the "file does not exist" case, and the search continues as if SearchNewFonts were true.

• If the file had SearchNewFonts=true declared but not FontsLocation, FontsLocation=C:\Windows\Fonts is added as a default value before continuing.

Warning for unresolved fonts

The document is still generated even if some fonts remain unresolved; the unresolved font is replaced with a standard fallback font (this is not an error that stops the operation). The operation result includes a warning (independent of the error indicator) listing the names of the fonts that could not be resolved, so the pdfreport.ini file can be reviewed and completed manually if desired.

It is possible to use several different fonts within the same document (for example, a title in one font and the body in another), as long as each one is resolved according to the mechanism above.

Usage example

&HTML          = "<h1>Monthly report</h1><p>Content of the <b>report</b> in <font face='Georgia'>Georgia</font>.</p>"
&PDFFileTarget = "C:\Documents\report.pdf"

//Header:
  &PDFToolsHeader.LeftText   = "Monthly report"

//Footer:
  &PDFToolsFooter          = "Page {page} of {pages}"

Error and warning messages