Inhaltsverzeichnis

  1. Einleitung
  2. Einsatzbereiche
    1. PDF-Dokument-Ansicht
    2. PDF-Anhang
  3. Gestaltung
    1. Page headers & footers
      1. Definition
      2. Integration
        1. HTML
        2. CSS
    2. Page numbering
    3. Page margins
      1. Examples
      2. References
    4. Page breaks
      1. References
    5. Page size & orientation
      1. Examples
      2. Reset page size
      3. References
    6. Double-sided documents
      1. Margins
      2. Headers & Footers
    7. Fonts
    8. Table of Contents
      1. References
    9. High quality printing
      1. Example
      2. References

Einleitung

Cloudrexx ermöglicht die Erzeugung dynamischer PDF-Dokumente aus erfasstem Inhalt, wie z.B.:

  • Dokument einer Inhaltsseite
  • PDF-Rechnung einer Shop-Bestellung (Achtung: ohne Einzahlungsschein)
  • Produktkatalog aus der Shop Anwendung
  • Factsheet eines Eintrages aus dem Medienverzeichnis
  • uvm.


Einsatzbereiche

PDF-Dokumente können entweder von einer Webseite (PDF-Dokument-Ansicht) oder einer Vorlage (als Anhang einer E-Mail-Benachrichtigung) erzeugt werden.


PDF-Dokument-Ansicht

Mit der PDF-Dokument-Ansicht kann von jeder Webseite (beliebige URL der Cloudrexx-Website) ein PDF-Dokument erzeugt werden. Auf die PDF-Dokument-Ansicht der aktuellen Seite kann mit dem Widget [[PDF_URL]] verlinkt werden.

Manuell kann die PDF-Dokument-Ansicht geladen werden, in dem zur URL der aktuellen Seite das URL-Argument pdfview=1 angehängt wird. Beispiel:

https://www.example.com/de/?pdfview=1

Die Gestaltung der PDF-Dokument-Ansicht erfolgt über ein separat definiertes Webdesign Template (unter Administration > Layout):


Dabei stehen zur Gestaltung alle Platzhalter (und Blöcke) zur Verfügung, welche für die normale Website-Ansicht zur Verfügung stehen.


PDF-Anhang zu E-Mail Vorlage

Bei den folgenden Anwendungen können die E-Mail Vorlagen (E-Mail-Benachrichtigungen) um einen dynamisch erzeugten PDF-Anhang ergänzt werden:

  • Digital Asset Management
  • E-Commerce Shop
  • E-Mail-Marketing
  • CRM


In der Bearbeitungsmaske einer E-Mail Vorlage kann dazu die Option Dynamisches PDF-Dokument anhängen aktiviert werden, um dann die gewünschte PDF Vorlage auszuwählen, aus welcher beim Versand der jeweiligen E-Mail-Benachrichtigung dynamisch ein PDF-Dokument erzeugt und am E-Mail angehängt werden soll.


Die PDF Vorlagen werden im Bereich Administration > Grundeinstellungen > PDF Vorlagen verwaltet. Für die Gestaltung der PDF Vorlagen stehen jeweils die gleichen Platzhalter (und Blöcke) zur Verfügung, wie sie für die Gestaltung der entsprechenden E-Mail Vorlagen zur Verfügung stehen.


Gestaltung

Dieser Teil der Dokumentation ist aktuell nur in Englisch verfügbar.


This section provides a short introduction to commonly used features when generating PDF documents. Note that this section does not cover the extensive feature-set of the underlying mPDF library. Please refer to the offical mPDF documentation for making use of its powerful features. When going through the offical mPDF documentation do keep in mind that when setting up a PDF template in Cloudrexx, you'll be limited to the use of HTML control tags (as well as the special CSS properties) of mPDF. All documentation regarding mPDF functions does not apply when setting up a PDF template in Cloudrexx. However the latter does apply when using the PDF component in the context of developing your own Cloudrexx App.


Page headers & footers

Page headers and footers can be integrated as follows:.

  1. First, the headers & footers must be defined (using <htmlpageheader> and <htmlpagefooter>)
  2. Then the defined headers & footers can be included in the PDF document either using CSS (@page {header: ... / footer: ...}) or HTML (<sethtmlpageheader> and <sethtmlpagefooter>)

Definition

Headers and footers are defined using the special HTML-tags <htmlpageheader> and <htmlpagefooter>. Each header/footer is identified by its name attribute. The layout & content of a header/footer is defined by the content of the <htmlpageheader> / <htmlpagefooter> tag. You can define as many headers/footers as you need. Meaning that you can define a different header/footer for the first page or for different headers/footers for odd and even pages (see Double-sided documents). Further, headers/footers can be changed on every page. Additionally you can even define a custom footer/header for the table of contents page (refer to <tocpagebreak>).

<htmlpageheader name="NAME">
    CONTENT
</htmlpageheader>
<htmlpagefooter name="NAME">
    CONTENT
</htmlpagefooter>

Use as follows:

  • Replace NAME by a text string used to identify the header/footer.

    Note: Do not name any header or footer starting with html_. This prefix is reserved to identify an HTML header/footer when passing its name in a reference.

  • Replace CONTENT by the HTML-content to be used as header/footer.


Example

The following header will display the current page number (taken from {PAGENO}) and is identified by the name myHeader.

Note that the following code does not yet output a header. It's just a header-definition that can later be included using HTML (<sethtmlpageheader>) or CSS (@page {header: myHeader}).

<htmlpageheader name="myHeader">
    <div>{PAGENO}</div>
</htmlpageheader>


Integration

Defined headers/footers (using <htmlpageheader> / <htmlpagefooter>) can be integrated on a page either using HTML or CSS. Please refer to the offical documentation of <htmlpageheader> and <htmlpagefooter> for advaned usages.


HTML

The special HTML-tags <sethtmlpageheader> and <sethtmlpagefooter> can be used to integrate defined headers/footers on a page by referencing to them through the name attribute:

<sethtmlpageheader name="NAME" page="PAGE" value="VALUE" show-this-page="SHOW-THIS-PAGE" />
<sethtmlpagefooter name="NAME" page="PAGE" value="VALUE" show-this-page="SHOW-THIS-PAGE" />

Use as follows:

  • Replace NAME by the header/footer to be integrated
  • Replace PAGE by one of ODD, EVEN or ALL to use it only on odd or even pages, or on all pages (see Double-sided documents)
  • Replace VALUE by either ON or OFF to active or deactivate the header/footer
  • Replace SHOW-THIS-PAGE by 1 to force the header/footer to be displayed on the current page too (and not only after the next page-break)

Please refer to the official documentation of <sethtmlpageheader> and <sethtmlpagefooter> for a full understanding of those attributes.


Example

Use the defined header myHeader on every page of our PDF document:

<sethtmlpageheader name="myHeader" value="on" show-this-page="1" />

The attribute value="on" will turn on the header on all pages after the next page-break. The attribute show-this-page="1" forces the system to include the header also on the current page (which might be the first page of the PDF document to be rendered).


CSS

The properties header and footer can be used to configure the integration of the defined headers & footers in the context of a @page rule.

Do so by setting the value of header / footer to the name of a previously defined header/footer (using <htmlpageheader> / <htmlpagefooter>) prefixed by _html.

Note: Set the value to _blank (or any name that hasn’t been defined) to turn of off headers/footers.


Example

Use the defined header myHeader on every page of our PDF document:

@page {
    header: html_myHeader;
}

Note that the name of the header has to be prefixed by _html.

Please refer to the documentation of the @page rule for further information on its usage.


Page numbering

The following placeholders related to page numbering can be using within headers & footers:


PlaceholderDescription
{PAGENO}
Total number of pages
{nb}

Total number of pages

{nbpg}
Number of pages of the current group in case it has been reset using
<pagebreak resetpagenum="1">


Please refer to the offical documentation for further information:


Page margins

Page margins can be set using CSS with the margin property within the context of a @page rule.

Additionally, when using headers & footers, the properties margin-header and margin-footer are used to set the margin between the top of a page and the start of a header, resp. the bottom of a page and the bottom of a footer.


Examples

Set a margin of 1cm:

@page {
    margin: 1cm;
}

Set individual margins:

@page {
    margin-top: 3cm;
    margin-bottom: 1cm;
    margin-left: 2cm;
    margin-right: 1cm;
}

Note: The top and bottom margin (using margin-top and margin-bottom) can be set differently for odd and even pages (see Double-sided documents) and can also be reset within the document. On the other hand, the left and right margin (using margin-left and margin-right) can only be set once (for the entire document). On double-sided documents they are mirrored on even pages.


References

Please refer to the official documentation for a full understanding of page margins:


Page breaks

Page breaks can be added using the special HTML-tags <pagebreak> and <formfeed> or by using the CSS properties page-break-before and page-break-after.


References

Please refer to the offical documentation for a full understanding on how to use page breaks:


Page size & orientation

The initial page size can be set using the size property within the context of a @page rule.


Examples

Set page size to A4 portrait:

@page {
    size: 210mm 297mm;
}

Set page size to A4 landscape:

@page {
    size: 297mm 210mm;
}


Reset page size

The page size can be reset within the document either again using the size property within the context of a @page rule or by using any of the special HTML-tags that handle page breaks (<pagebreak> / <tocpagebreak>).


References

Please refer to the offical documentation on how to reset the page size within the document:


Double-sided documents

Double-sided documents can be generated. This allows for individual layouting (header/footer/margins) for odd and even pages.

By default the generated PDF document is a single-sided document. To generate a double-sided document, simply register the :left and :right selectors to the @page rule:

@page :left, @page :right {}

Note: The context of the @page rule can be left empty.

The first page in the generated PDF-document is considered to be an odd page and will appear as a right page in a LTR document (or as a left page in a RTL document).


Margins

On double-sided documents, the left and right margins are mirrored on even pages. Meaning that the left margin (margin-left) on a right (odd) page translates to the right margin on a left page and vice versa for the right margin (margin-right).


Headers & Footers

Different headers & footers can be defined for odd and even pages.

In CSS, this is achieved with the properties odd-header-name, even-header-name, odd-footer-name and even-footer-name in the context of a @page rule.

In HTML, this is done using the PAGE attribute of the <sethtmlpageheader> and <sethtmlpagefooter> tags (see Page headers & footers).


Fonts

The default font being used when generating a PDF document is DejaVu (DejaVuSerifCondensed). Aside from that several variations are available (DejaVuSans / DejaVuSansCondensed / DejaVuSerif / DejaVuSansMono), as well as another generic font, the GNU FreeFont (FreeSans / FreeSerif / FreeMono). Further, several non-latin fonts are available for use too. The full list of available fonts can be found in the official documentation.

Custom fonts are also supported and can be included as follows:

  1. Place your custom TrueType[1] font files in the directory /media/Pdf/ttfonts/
  2. The font mustbe named as follows to be recognized as such:
    1. MyFont-Regular.ttf
    2. MyFont-Bold.ttf
    3. MyFont-Italic.ttf
    4. MyFont-BoldItalic.ttf
  3. Include your custom font as follows:
    HTML:
    <p style="font-family: MyFont;">Text in MyFont</p>
    CSS:
    font-family: MyFont;


1. Hinweis: Kashida and OTF are not supported yet.


Tip: Unlike with HTML, boxes in mPDF scale text rather than cutting the overflowing part. If a change to font-size has no effect this could mean that the box containing the text is too small for the selected font-size. 


Table of Contents

An automatic generated table of contents can be included using the special HTML-tag <tocpagebreak>. The table of contents supports custom headers/footers using the attributes toc-odd-header-name, toc-even-header-name, toc-odd-footer-name and toc-even-footer-name. Further, it supports a custom page size and orientation by using the attributes toc-sheet-size and toc-orientation.

Entries for the table of contents can be added by using the special HTML-tag <tocentry>.


References

Please refer to the official documentation for a full understanding of the possibilities and its usage:


High quality printing

Cross and/or crop marks can be added using the marks property within the context of a CSS @page rule. When using marks, do use the property size to define the size of the page box and the property sheet-size to define the size of the sheet.


Example

Add cross and crop marks to a A4 landscape document to be printed on A3 landscape sheets:

@page {
    marks: crop || cross;
    size: 297mm 210mm;
    sheet-size: A3-L;
}


References

Please refer to the official documentation the use of the properties marks, size and sheet-size: