Place any content: Positioning content
Using Fixup parameters or HTML size relative to PDF size to place objects
The positioning of HTML elements placed within a document can be influenced in one of two ways:
- By entering details in the “Edit Fixup” dialog
Positioning content using the reference point
PDF and HTML files actually use coordinate systems which differ based on the origin points of the X and Y axes.
Whereas PDF uses a coordinate system with the origin on the left, HTML uses a point at the upper left as the origin. pdfToolbox compensates for this difference.
Important: The effective coordinate system for the PDF page as used in the Fixup is defined by setting the reference point to “relative to”. If you also select “Upper left corner” here, both coordinate systems will use the same origin. Positioning will generally only be “intuitive” if this is done.
In all other cases, it is important to be clear about the basic positioning: pdfToolbox first identifies the positioning point on the page using the details within the Fixup.
The reference point for the corresponding corner of the HTML object will be placed on this point.
Example: If the reference point is set to “relative to” the “upper right corner”, the horizontal offset to -20 mm and the vertical offset to -100 mm, the result will be that the positioning point is 20 mm to the left of and 100 mm below the upper right corner of the PDF page. The upper right corner of the HTML object will then be placed on this point.
The issue becomes more complicated if we rotate the HTML object as part of the fixup by specifying “Rotation (degrees)”. In this case, the HTML object is rotated before placing it. A virtual rectangle with edges parallel to the coordinate system will then be created. For all rotations other than 90°, 180° or 270° (or their negative counterparts), this virtual rectangle will then be larger than the unrotated object itself. This virtual rectangle will be placed based on the rules described above.
In other words, when the HTML object is placed, the source in the HTML coordinate system is not used. Rather, the corner or edge corresponding to the reference point described in the Fixup is used.
The size of the HTML object therefore plays a particularly decisive role when positioning content.
Internal page size: Default DIN A4
It is possible to assign a fixed size to the HTML object within the CSS (in the @page rule). This is also advisable if the reference point is not the upper left corner. If this space is left blank, the default size of DIN A4 will be used.
This means that unless otherwise specified, pdfToolbox will place the generated PDF at DIN A4 size within the PDF file to be fixed.
(This can sometimes lead to irritating but logical results if placing a line of text from index.html within a DIN A4 PDF. Certain placing options (bottom left, middle, etc.) which you may want to access using the pdfToolbox dialog will then appear not to work. This is because it is not just the line of text which is being placed, but rather the text within an automatically generated A4 page format.)
Custom page formats for content to be placed must be specified using CSS.
This also means that unless specific provisions are made, an HTML object’s size will never be defined within its own content. A square placed relative to the bottom-left corner can therefore only be placed exactly on this bottom edge if the position of the edge has been calculated in advance and accounted for either in the HTML or in the Fixup’s positioning settings.
Placing multiple HTML “pages”
Multiple pages can be created when processing the HTML template if the dimensions of the objects exceed the defined or default (A4) format. In this case, pdfToolbox will place the first page of the HTML template on the first page, then the second and so on until all pages of the HTML template have been processed. Processing will then begin again on the first page of the HTML template until all pages of the PDF have been filled.
It is therefore entirely possible to use a single template to attach different content to each page of a PDF.
Alternate approach to positioning
As shown above, specifying the desired position for an object defined in HTML can easily get complicated. In many cases it therefore makes sense to create a page in HTML which matches the dimensions of the PDF page. This example, when placed in the header of an HTML file, will produce a DIN A3 “page” in landscape format:
Objects can then be positioned within this HTML page using HTML and especially CSS. This page will then be placed relative to the upper left corner without any offset.