Creating custom PDF - document templates – Upsales Help Centre

How to create custom document templates, use the template editor, and edit with HTML and CSS.

This article covers:

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

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:

Creating custom templates

Click the New custom template button:

Click the dropdown next to Create from... and choose a template:

Make your HTML, CSS, Sample and Language data edits.

Update the name (to create a new version), add any role restrictions:

Click Save and reload:

The editor

The editor consists of four elements.

HTML body to structure your PDF’s content
CSS file to style your PDF and bring it to life
JSON payload to provide sample data while you develop your PDF document
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.

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, you get 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.

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",

      ...
   
   }
}

Here is how to fetch, for example the order ID to your HTML:

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

The JSON payload also fetches your company colours, logo, and fonts from your company profile. These can be used to build PDF templates for your company's 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

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 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 colours 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'}}}" />