PDF rendering - trifork/dpk-docs GitHub Wiki

Templates

Three files are associated with a PDF template:

  • <template_identifier>.pdf
  • <template_identifier>_layout.json
  • <template_identifier>_config.text

The three files must be placed in the templates folder in flux-repository:

image

PDF file

PDF-file where letter/recipient specific text have been removed.

Layout file

The JSON file is structured in accordance with the PdfConfig object found in dpk-pdf-service\service\src\main\java\com\trifork\digitalpostkomponent\pdf\model\PdfConfig.java. It contains a list of all text elements to be printed in the PDF file. The placeholder values indicated by $placeholder key$ must adhere to the list of placeholder values in the template configuration file. image

Configuration file

A txt-file of four lines of text:

  • Line 1: Template identifier
  • Line 2: Letter subject (Digital post)
  • Line 3: Letter type (Strålfors)
  • Line 4: List of placeholder values of the template

image

Templates in database

PDF templates are stored in the database as Base 64 encoded strings.

The template table contains all data associated with a template:

  • identifier: String template identifier (for now; BekraeftelseRegistrering_digital, BekraeftelseRegistrering_fysisk, BekraeftelseFortrydelse_digital, BekraeftelseFortrydelse_fysisk, Paamindelse_digital and Paamindelse_fysisk)
  • version: Version assigned to template when template identifier already exists in database
  • subject: Subject of digital post letter
  • lettertype: Integer representing Strålfors letter type
  • createdat: Timestamp of when template has been added to database
  • parameters: List of placeholder keys to be replaced with recipient/letter specific values from request
  • pdftemplate: Base 64 encoded string representing pdf template
  • attachment: Id of PDF attachment stored as Base64 encoded strings in attachments table
  • layoutconfig: JSON object with configuration of text elements to be printed on table

PDF configuration

A JSON configuration object consist of properties stating the date format to be used in the letters as well as a list of text elements to be added to the letters.

String dateFormat
PdfElement[] elements

Each text element (PdfElement) of the a letter has the following properties to define styling, placement and content:

String key                          // Naming of the text element, e.g. "name", "date", "greeting" 
DetailType type,                    // Enum type of text element: `TEXT`, `DATE` or `LINK`
String text,                        // Text with placeholder values to be printed in the letter, e.g. "Kære $firstName$ $lastName$
String alternativeText,             // Alternative text for hyper links. Only used for text elements of type "Link"
String font,                        // Font name which must exist in iText Font Factory. See section about fonts
float fontSize,                     // Font size
FontColor fontColor,                // RGP font color, e.g. "fontColor":{"red":100,"green":200,"blue":0}
String fontStyle,                   // Font style [NORMAL, BOLD, ITALIC, BOLDITALIC]
String alignment,                   // Text alignment [LEFT, RIGHT, CENTER, JUSTIFIED]
int lineSpacing,                    // Line spacing                  
PdfElementBounds position           // Position of element

The position of a text element is defined by four coordinates in PdfElementBounds of a text column:

int left,              // The x-coordinate of the left edge of the column
int bottom,            // The y-coordinate of the bottom edge of the column
int right,             // The x-coordinate of the right edge of the column
int top                // The y-coordinate of the top edge of the column

An A4 page has a page height of 842 and a page width of 595.

Placeholder values

Placeholder values linked to a template are stored in the template table within the database as a comma-separated list. These placeholder values need to align with the expected values of the request from NSP. Additionally, requesters are responsible for ensuring compliance with the configurations associated with the requested templates.

Placeholder values within a text is indicated using dollar signs, e.g.

"Min adresse er: $RecipientAddress$, $RecipientCity$ $RecipientPostalCode$"
"Min adresse er: Vibevej 46, 8000 Aarhus C"

Placeholders for fixed recipient values identifier, identifier source, first name, last name, address, city and postal code must be written in PascalCase and must have Recipient prefix, e.g. RecipientIdentifier, RecipientIdentifierSource, RecipientFirstName, RecipientLastName, RecipientAddress, RecipientCity and RecipientPostalCode.

Placeholder date holds timestamp of pdf rendering/dispatch date.

Fonts

The iText library, which is employed for rendering PDF files, comes with a predefined set of fonts. The following fonts are included with iText:

  • times-roman, times-italic, times-bold, times-bolditalic
  • helvetica, helvetica-bold, helvetica-boldoblique, helvetica-oblique
  • courier, courier-boldoblique, courier-bold, courier-oblique
  • zapfdingbats
  • symbol

Currently, two additional fonts have been added to support the fonts utilized in the provided templates:

  • calibri
  • corbel

These font are imported runtime. Utilizing fonts not listed above will require additional configuration effort for templates compared to using fonts that are already registered. This will be reflected in the amount of hours spent configuring new templates.

Layout file example

{
  "dateFormat":"d. MMMMM yyyy",
  "elements":[
    {
      "key":"address",
      "type":"TEXT",
      "text":"$RecipientAddress$\n$RecipientCity$ $RecipientPostalCode$",
      "alternativeText":null,
      "fontSize":10,
      "font":"Corbel",
      "fontStyle":"NORMAL",
      "fontColor":{
        "red":0,
        "green":0,
        "blue":0
      },
      "lineSpacing":3,
      "alignment":"LEFT",
      "position":{
        "left":71,
        "bottom":695,
        "right":541,
        "top":200
      }
    },
    {
      "key":"greeting",
      "type":"TEXT",
      "text":"Kære $RecipientFirstName$ $RecipientLastName$",
      "alternativeText":null,
      "fontSize":11,
      "font":"calibri-regular",
      "fontStyle":"NORMAL",
      "fontColor":{
        "red":0,
        "green":0,
        "blue":0
      },
      "lineSpacing":3,
      "alignment":"LEFT",
      "position":{
        "left":71,
        "bottom":568,
        "right":541,
        "top":200
      }
    },
    {
      "key":"date",
      "type":"DATE",
      "text":"$date$",
      "alternativeText":null,
      "fontSize":10,
      "font":"Corbel",
      "fontStyle":"NORMAL",
      "fontColor":{
        "red":0,
        "green":0,
        "blue":0
      },
      "lineSpacing":3,
      "alignment":"LEFT",
      "position":{
        "left":71,
        "bottom":745,
        "right":541,
        "top":200
      }
    },
    {
      "key":"linkTilSundhedDk",
      "type":"LINK",
      "text":"Læs, hvordan du gør, på $linkTilSundhedDk$",
      "alternativeText":"sundhed.dk",
      "fontSize":11,
      "font":"calibri-regular",
      "fontStyle":"NORMAL",
      "fontColor":{
        "red":0,
        "green":0,
        "blue":0
      },
      "lineSpacing":3,
      "alignment":"LEFT",
      "position":{
        "left":71,
        "bottom":317,
        "right":538,
        "top":200
      }
    }
  ]
}