Creating custom PDF - document templates – Upsales Help Center

This article will explain how to create a custom document template and help you familiarize yourself with the template editor. You need some knowledge about HTML and CSS.

This article will cover;

The editor
Structuring your template
Styling your PDF
Working with sample data
Adding languages
Working with Handlebars
Available helpers
Using standard templates

The editor

The editor located on your left-hand of the screen consists of four elements.

An HTML body to structure your PDF’s content.
A CSS file to style your PDF and bring it to life.
A JSON payload to provide sample data while you develop your PDF document.
And a language file to provide multiple languages in one single PDF document.

Change any of these elements and click Save and reload and see the changes reflected in the preview pane located on the right-hand side of the screen.

Structuring your template

The core of the template is HTML. You can use any valid HTML tag that you can use on any web page. For example; Use <h1 /> tags to define headlines or <p /> to define paragraphs as well as <div /> or <span /> to create containers.

Use Handlebars to fetch data from the sample data file.

Styling your PDF

Bring your PDF to life by using CSS. The same thing applies here, you can use any CSS you would on a normal web page. The one caveat is of course that animations and transitions will not work since the end result of the template is a PDF file.

To specify hex-colors e.g #000000 you need to use the bgconverter helper. Like so; background-color: {{bgconverter '#000000'}};

Working with sample data

While you develop your PDF document, we provide a JSON payload with sample data you can use. The sample data contain the normal objects you will find opportunities or orders such as products, list prices, discounts, contact, user, etc.

Here is an example of the sample data file;

{
   "order": {
      "id": 1394,
      "description": "10 Licenses",
      "date": "2019-12-12T00:00:00.000Z",
      "notes": null,
      "regDate": "2019-12-12T09:48:24+00:00",
      "closeDate": "2019-12-12T00:00:00.000Z",
      "probability": 100,
      "modDate": "2019-12-12T09:48:24+00:00",
      "currency": "SEK",

      ...
   
   }
}

And here is how you would fetch for example the order ID to your HTML;

<p>{{order.id}}</p>

In addition, the JSON payload also fetches your companies colors, logo, and fonts from your companies company profile. Use these to build PDF templates that match your companies profile.

Here is an example of profile data you will find in the sample data set.

"accountProfile": {
   "logo": "https://img.upsales.com/MklwK40UeZic8Rs+mm6cMw==/images/demobolaget_white.png",
   "darkLogo": "https://img.upsales.com/RfYkyVcwMfeI1jeLapbY6w==/images/demobolaget_grey.png",
   "btnBorderRadius": 3,
   "colors": {
      "mainBg": "#916180",
      "mainText": "#333333",
      "bodyBg": "#ededed",
      "contentBg": "#ffffff"
   }
   ...
}

In your CSS file, you can then use the sample data to style your PDF document.

.class-name {
   background-color: {{bgconverter accountProfile.colors.mainBg}};
}

Adding languages

If you have customers in several countries, you can use the language file to translate your PDF document. This is helpful so you don't have to develop multiple templates for multiple languages. You can add as many languages as you like by specifying the language by its Language code (ISO 639-1). Pair the language code with a text key that contains your translation.

Example of a language file.

{
   "en": {
      "myTextKey1": "Hello!",
      "myTextKey2": "This text is translated"
   },
   "sv": {
      "myTextKey1": "Hej!",
      "myTextKey2": "Den här texten är översatt"
   },
   "de": {
      "myTextKey1": "Hallo!",
      "myTextKey2": "Dieser Text wird übersetzt"
   }
}

Or in another way

{
   "languagecode": {
      "textkey": "translation"
   }
}

Note that the textkey name must be the same on all language pairs.

Once you have added your language file to your PDF document, you can then fetch the translations using the translate helper. It looks like this;

<h1>{{translate 'myTextKey1'}}</h1>
<p>{{translate 'myTextKey2'}}</p>

Once the PDF template is saved it will render like this

<h1>Hello!</h1>
<p>This text is translated</p>

By now you are maybe wondering how the preview picks the language to display? That is done by adding "translateTo": "country code in language file" to your sample data JSON.

Working with Handlebars

Handlebars is a simple templating language.

It uses a template and an input object to generate HTML or other text formats. Handlebars templates look like regular text with embedded Handlebars expressions.

Learn more about Handlebars here.

Available helpers

We have developed a couple of helpers that simplifies the creation of your PDF templates. Use them in your HTML. Here is a list of available helpers.

Math
Use Math to do simple calculations. Operators "+, -, * and /" should be placed in quotation marks.

{{math 'value' '-' 'value'}}

Math can be combined with the currencyFormatter

{{currenyFormatter (math 'value' '/' 'value')}}

currencyFormatter
The currencyFormatter formats numbers to the correct thousand separators based on the language your end-user select when creating the PDF document.

{{currencyFormatter this.listPrice}}

dateFormater
The dateFormater formats date objects to correct date stamps based on the language the end-user selects when creating the PDF document.

{{dateFormater order.date}}

translate
The translate helper fetches text keys and displays then based on "translateTo" in the sample data JSON or the language the end-user selects when creating the PDF document.

{{translate 'text-key-name'}}

bgConverter
Since hashtags are occupied already by Handlebars, the background converter lets you use them in your CSS.

{{bgConverter '#HEXCODE'}}

customTag
Adds data from custom fields to the PDF document.

{{customTag 'order' 'custom.client.10'}

setGoogleFonts
Add a custom Google font to your PDF document.

https://fonts.googleapis.com/css?family={{#setVar}}{{accountProfile.typographyLandingPages.h2.fontFamily}}{{/setVar}}

colorSwitch
If you have multiple brands you can use this helper to switch colors on text so dark backgrounds get light text and vice versa. Or switch from a dark logo to a light one based on your company profiles.

<div class="{{colorSwitch accountProfile 'class'}}"></div>
<img src="{{{colorSwitch accountProfile 'logo'}}}" />

Using standard templates

Standard templates are created and ready to be used. These are available if an Admin user activates them in Settings -> CRM -> Document templates.

You can also create your own custom template using the standard templates. Click 'New custom template' to create a new one and use the 'Create from..' and choose a standard template.

All the HTML, CSS, Sample and Language data is available to be modified. Remember to rename the template and activate it when it is ready!