Skip to content

Customizing Templates

The invoice template is the model based on which the PDF copy of an invoice is rendered. It defines its contents and layout. The produced PDF document is intended to be distributed via email or postal service to customers, and it can be exported and archived. JustOn provides a default template, based on which you can define your own templates.

For details about the template fields (its building blocks and the corresponding contents) see Default Template.

Customizing templates according to your needs usually comprises the following tasks:

Depending on your custom requirements, additional tasks can involve:

Template Concepts

Template Structure

The template is composed of a number of pre-defined containers that represent specific areas of the page - the header, footer, the invoice line item table, etc. Each container comprises text blocks that define the actual content displayed in the final document. For example, the header container contains text blocks for including addresses for sender and recipient, a company logo, and other invoice details.

Text blocks can include placeholders. These are symbols for fields of Salesforce or JustOn objects (like address fields or payment data), which are to be replaced with actual values upon PDF rendering.

For details about the template structure, building blocks, etc., see Default Template.

When creating a PDF copy of an invoice, JustOn executes the following internal steps:

  • JustOn produces an intermediate HTML document based on the invoice template and using the data provided by the actual invoice.
  • The HTML document is then converted into a PDF using standard Force.com functionality.

The template defines the structure and layout of the intermediary HTML document. That is, when customizing the template, you actually edit a HTML document.

Template Variation

Usually, you have multiple templates that each serve a specific target. There are, basically, two ways to diversify templates:

  • creating multiple templates for different targets, for example, different locales or specific customer groups
  • using template details to customize specific parts for different purposes, for example, invoice, credit, cancellation.

Info

You can combine the two approaches.

Template details are a means to override specific fields of a template in order to cover specific use cases. By default, JustOn ships template details for credits, cancellations and dunning reminders. These template details overwrite certain fields of the default template depending on the object (Invoice or Dunning) and the object type (Credit or Cancellation in case of invoices).

For information about using template details, see Configuring Template Details.

Note

If there is no specific template detail available for a certain use case, like dunning, for example, JustOn uses the information as defined in the corresponding invoice template, including the defined text blocks, the counter, etc.

Template Assignment

When setting up a Subscription, Opportunity or any other object for billing, you must specify a standard template for that object. This template is then assigned by default to all invoices created from that object. As long as an invoice has the status Draft, you can assign another template to the invoice.

Creating New Template

Info

JustOn recommends to create one or more custom templates and to leave the default template untouched.

To cover multiple targets, like different locales or specific customer groups, you need to create new templates. To do so:

  1. Open the Templates tab.
  2. Click New.
  3. Specify at least the template name and the template language.
    You can edit the other information later as required.
  4. Click Save.
    ▶ This generates the new template, copying the contents of the default template.

Info

Alternatively, you can also clone an existing template.

Populating Required Template Fields

Usually, your organization has defined a layout model for printed documents. When customizing a template, you must provide information to fields (text blocks) that are empty by default in order to comply with your organization's design specifications. Common header and footer fields to be populated with your custom information include

  • Header
  • Sender Address
  • Footer

For an overview of other fields that are to be filled, their placement etc., see Template Structure and Building Blocks.

To edit header and footer:

  1. Open the template to be edited.
  2. In the Header & Footer section, double-click the Header, Sender Address or Footer field and specify the information as required.
    Alternatively, you can click Edit in the detail view and edit all fields at once.
  3. Click Save.

Info

Template text blocks can contain

  • plain text
  • placeholders
  • HTML code for tables, lists, links, etc.

If you use HTML code in template text blocks, make sure to write all code in a single line to avoid line breaks being converted to <br/> tags.

Specifying Counter

Invoices, credits, cancellations and dunnings must have unique numbers to comply with legal regulations. In Draft status, these numbers are temporary and of no legal relevance. When setting them to Open, however, JustOn creates the unique and unalterable numbers for invoices, credits, cancellations and dunnings based on defined counters. For details, see Counters and Number Ranges.

Customizing templates therefore involves specifying the counter to be used. To do so:

  1. Open the template to be edited.
  2. In the Information section, double-click the Counter field and specify the counter as required.
    Alternatively, you can click Edit in the detail view to edit the field.
  3. Click Save.

Editing Standard Text Blocks

In the main content area, the template includes three generic text blocks that you can use for any running text to be rendered in the final document.

  • Text 1: Text to be rendered above the invoice line item table, can be used, for example, to edit a letter-like text introducing the invoice that follows.
  • Text 2: Text to be rendered below the invoice line item table, can be used, for example, to add payment terms.
  • Text 3: Additional text to be rendered below the Text 2 block.

To edit the generic text blocks:

  1. Open the template to be edited.
  2. In the Texts section, double-click the Text 1, Text 2 or Text 3 field and specify the information as required.
    Alternatively, you can click Edit in the detail view and edit all fields at once.
  3. Click Save.

Info

Template text blocks can contain

  • plain text
  • placeholders
  • HTML code for tables, lists, links, etc.

If you use HTML code in template text blocks, make sure to write all code in a single line to avoid line breaks being converted to <br/> tags.

Adjusting Invoice Line Item Table

The Table Columns field determines the contents of the line item table on the printed invoice. This field contains a list of invoice line item fields, separated by semicolon, which determines the visible table columns and their sequence. If the Table Columns field is left blank, JustOn defaults to the following setting:

PosNo;Title__c+Description__c;UnitPriceCalc__c;Quantity__c+Unit__c;TaxRate__c;PosTotalNet__c

This produces the following invoice line item information:

  • Position number
  • Item title and description
  • Calculated item price (the unit price multiplied with the commission, if defined)
  • Item quantity
  • Tax rate
  • Item net total

Depending on your organization's requirements, you must remove columns you do not need or add new columns. To do so:

  1. Open the template to be edited.
  2. In the Information section, double-click the Table Columns field and specify the information as required.
  3. Click Save.

Info

You can use any invoice line item field. Note that the specified order defines the column sequence.

To remove, for example, the item description, quantity unit and tax rate and to show the billing factor and an applicable item discount, type the following line in the Table Columns field:

PosNo;Title__c;UnitPriceNet__c;Quantity__c;BillingFactor__c;Discount__c;PosTotalNet__c

Adjusting Invoice Formatting

The invoice template defines display formats for date and time display as well as currency and number display.

Field Description
Use Unicode Font (checkbox) Specifies whether to use the font Arial Unicode for the text rendering. This allows for printing virtually any character of any language, but impedes bold and italic text formatting.
Date Format Specifies the format for all date fields of the invoice.
Month Format Specifies the format for the [LastMonth], [CurrentMonth] and [NextMonth] placeholders.
Time Format Specifies the format for displaying time values.
Leading Currency (checkbox) Controls whether the currency sign (like $ or €) is displayed before (checked) or after (unchecked) the value.
Decimal Separator Specifies the decimal separator for all number fields like currency values or percentage values.
Grouping Separator Specifies the grouping separator for all number fields like currency values.

Note

Selecting or changing the template language does not modify the (region-specific) formatting settings.

Depending on your organization's localization requirements, you must adjust the display of date, time, currency or number values. To do so:

  1. Open the template to be edited.
  2. Click Edit.
  3. In the Formatting section, modify the fields as required.
  4. Click Save.

Info

For details about supported date and time formats, refer to the Simple Date Format syntax in the Java Documentation.

Info

If you send email with non-Latin data, like the Euro symbol, Hebrew, Chinese, Japanese, Russian, etc., set your email encoding to Unicode (UTF-8). For details, see Why do emails contain garbage characters?.

Usually, your organization has defined a layout model for printed documents. As this model most certainly includes a company logo, you have to add an image file and configure its display when customizing your template.

Info

When attaching an image file as your organization's logo, consider that the recommended file format is PNG and that the file size should not exceed 30 kB in order to keep the resulting PDF file size manageable.

Attaching Image

You can add image files as attachments to your template.

  1. Open the template to be edited.
  2. In the Notes & Attachments section, click Attach File.
  3. Select the intended file using using your browser's file selection dialog.
  4. Click Attach File.
  5. Click Done.
    ▶ This completes the image upload operation and returns you to the previous page.

Note

Make sure that files are not set to be uploaded as Salesforce Files.

To verify this, open the General Settings page for Salesforce Files. The checkbox Files uploaded to the Attachments related list on records are uploaded as Salesforce Files, not as attachments must not be selected. See also How to display the Attach File button in Notes & Attachments?.

Handling Multiple Images

You can add multiple image files as attachments to your template. There are two ways to specify the image attachment to be used as the company logo:

  • Add the description text logo to the image attachment that you want to use as your company logo. If there is none of the attached images marked as logo this way, JustOn does not print a logo to the invoice PDF.
  • Use the placeholder [img|byid:<ATTACHMENTID>] in the header text (see Populating Required Template Fields). Replace <ATTACHMENTID> with the Salesforce record ID of the attached image file.
    Using this placeholder allows for including other image file attachments in other text fields, if necessary.

Configuring Image Display

Generally, the layout, styling, positioning of the template building blocks is controlled using CSS, see CSS Rules.

By default, the company logo is rendered unscaled on top of the page and aligned with the left margin. Depending on your organization's requirements, you must adjust the image display, like changing the display size or aligning the image with the right margin.

To adjust the image display, you have to provide custom CSS rules. To do so:

  1. Open the template to be edited.
  2. In the Layout & Design section, double-click the Custom CSS field and specify the CSS code as required.
    Alternatively, you can click Edit in the detail view to edit the field.
  3. Click Save.

Following the mentioned examples, you can use this CSS to resize the image:

.logo {width: 60%}

To align the image with the right margin, you can use this CSS:

.c1 .block_0 {
    width: 100%;
    text-align: right;
}

Configuring Overrides

Depending on your organization's requirements, you must modify some labels or the number of decimal places that are to be printed on the invoice PDF. To do so, you configure override labels and decimal places in the corresponding template fields.

Configuring Override Labels

The template field Override Labels allows to define a new label for individual fields. The setting accepts all objects (standard, custom and JustOn objects) and fields. It therefore applies to all placeholder fields as well as fields in the line item table and the transaction table.

The field value is in JSON notation and has the following syntax:

{
  "ObjectApiName" : { "FieldApiName" : "Label" }
}

To define, for example, new labels for some invoice line item fields, use:

{
    "InvoiceLineItem__c": {
        "Title__c": "Product Name",
        "UnitPriceNet__c": "Price"
    }
}

Some labels do not originate from fields, but can still be changed specifying them as Calculated:

{
    "Calculated": {
        "PosNo": "Position",
        "Subtotal": "Subtotal"
    }
}

Info

Labels are rendered in the language of the current user locale. If the language of the template differs from the user language, you need to override the labels for the fields PageLabel and OfLabel to produce a correctly localized invoice PDF.

The following code illustrates an example for German labels that may be used and must be overridden:

{
    "Calculated": {
        "PosNo" : "Pos.",
        "Subtotal" : "Zwischensumme",
        "PaymentAmount" : "Zahlbetrag",
        "RefundAmount" : "Erstattungsbetrag",
        "Credit" : "Gutschrift",
        "RoundingDifference" : "Rundungsdifferenz",
        "AccountBalance" : "Account-Saldo",
        "BalanceTitle" : "Posten",
        "OpenAmount" : "Offener Betrag",
        "SubTotalNet" : "Zwischensumme (netto)",
        "SubTotalGross" : "Zwischensumme (brutto)",
        "PageLabel" : "Seite",
        "OfLabel" : "von"
   }
}

To configure override labels:

  1. Open the template to be edited.
  2. In the Overrides section, double-click the Override Labels field and specify the override definition in JSON as required.
    Alternatively, you can click Edit in the detail view to edit the field.
  3. Click Save.

Configuring Decimal Places

The template field Decimal Places allows to define the number of decimal places to be displayed for individual fields. The setting accepts all objects (standard, custom and JustOn objects) and fields. It therefore applies to all placeholder fields as well as fields in the line item table and the transaction table.

The field value is in JSON notation and has the following syntax:

{
  "ObjectApiName" : { "FieldApiName" : number }
}

To set, for example, the number of displayed decimal places for the price and tax fields of the invoice line item to 2, use:

{
    "InvoiceLineItem__c": {
        "TaxRate__c": 2,
        "UnitPriceNet__c": 2,
        "Quantity__c": 2,
        "PosTotalNet__c": 2
    },
}

The setting also accepts special fields for calculated values:

{
    "Calculated": {
        "TaxAmount": 2,
        "SubTotalNet": 2,
        "SubTotalGross": 2
    }
}

To configure the number of decimal places:

  1. Open the template to be edited.
  2. In the Overrides section, double-click the Decimal Places field and specify the definition in JSON as required.
    Alternatively, you can click Edit in the detail view to edit the field.
  3. Click Save.

Info

If there is no definition of decimal places in the template, JustOn falls back to the following settings in this order:

(1) Decimal Places for Unit Price and Decimal Places for Quantity on the invoice line item
(2) Decimal Places for Unit Price and Decimal Places for Quantity in the global settings
(3) Global default: 2 decimal places for all numeric values

Configuring Subtotal Display

Depending on your business requirements, you must display a subtotal after an invoice line item.

Generally, a subtotal section includes a row for the calculated net subtotal, followed by one or more rows for each distinct tax rate. After the last invoice line item, there will be always a subtotal section.

There are two options:

  • Using the checkbox Display Subtotal After on the subscription item or the invoice line item, you can force JustOn to produce a subtotal section after each invoice line item when generating the invoice.
  • You can, however, define a criterion that triggers the subtotal section display, grouping the invoice line items by this criterion at the same time. To do so, use the field Subtotal Criteria on the invoice template: Specify a field of the invoice line item, and each time the contents of the changes, JustOn produces a subtotal section.

Displaying Grouped Subtotal Section

Subtotal Criteria set to TaxRate__c
PosTitleUnit PriceTax RateTax AmountPos Total Net
1A10,0010%1,0010,00
2B25,0010%2,5025,00
Subtotal (net)35,00
Tax (10%)3,50
3C25,005%1,2525,00
Subtotal (net)25,00
Tax (5%)1,25
4D............

To set a subtotal criterion:

  1. Open the template to be edited.
  2. In the Line Items section, double-click the Subtotal Criteria field and specify the API name of the invoice line item field you want to use as subtotal criterion.
    Alternatively, you can click Edit in the detail view to edit the field.
  3. Click Save.

Info

You can define a custom formula field on the invoice line item to be used as criterion if you must model complex subtotal criteria.

Displaying Gross Subtotal

You may want to display the gross subtotal, that is, the sum of the net subtotal and the taxes, for each subtotal section.

Subtotal Criteria set to TaxRate__c, including gross subtotal
PosTitleUnit PriceTax RateTax AmountPos Total Net
1A10,0010%1,0010,00
2B25,0010%2,5025,00
Subtotal (net)35,00
Tax (10%)3,50
Subtotal (gross)38,50
3C25,005%1,2525,00
Subtotal (net)25,00
Tax (5%)1,25
Subtotal (gross)26,25
4D............

To enable the gross subtotal display, you must apply the following CSS rule:

.invoice-table .subtotal-calculated.gross {
    display: table-row;
}
  1. Open the template to be edited.
  2. In the Layout & Design section, double-click the Custom CSS field and specify the CSS code as required.
    Alternatively, you can click Edit in the detail view to edit the field.
  3. Click Save.

Using CSS to Control Output

Certain use cases require multiple templates with only small differences. Multiple templates, however, may become difficult to maintain. This section illustrates some example requirements and shows how to cover them with a single template.

Available Style Classes

JustOn supports specific CSS classes that allow for applying some custom styling to the contents of certain invoice or dunning fields.

The following classes are available in the body element of the invoice PDF.

Considered Invoice Field Available CSS Classes Notes
Class class-Invoice
class-Credit
Type type-Installment
no-type
Email Invoice is-email-invoice
no-email-invoice
Print Invoice is-print-invoice
no-print-invoice
Tenant tenant-<Company_Name>
no-tenant
The tenant class name is composed of tenant- and the name of the tenant, where the allowed characters include a–z, A–Z, 0–9, and underscore (_). That is, you must replace dots, commas or spaces with underscores, and special characters with their nearest ASCII neighbor.

The following classes are available in the body element of the dunning PDF.

Considered Dunning Field Available CSS Classes Notes
Level level-1
Email Dunning is-email-dunning
no-email-dunning
Print Dunning is-print-dunning
no-print-dunning
Tenant tenant-<Company_Name>
no-tenant
The tenant class name is composed of tenant- and the name of the tenant, where the allowed characters include a–z, A–Z, 0–9, and underscore (_). That is, you must replace dots, commas or spaces with underscores, and special characters with their nearest ASCII neighbor.

Info

You can define the field AdditionalStyleClass on the invoice or dunning. Its content will be normalized and added as an additional style class to the body element. Use this field to consider the values of further invoice or dunning fields to be styled using CSS.

Depending on your business, you may decide on a per customer basis whether to email PDF documents or to post hard copies. To this end, you can mark invoices using the Email Invoice or Print Invoice checkboxes.

Now assume that you print invoices or statements on your company stationery, which already includes all relevant company information and design elements. In this case, you hide the header, footer and logo.

The following custom CSS rule suppresses the header, footer and logo if the invoice is marked as Print Invoice.

.is-print-invoice .page-footer, .is-print-invoice .page-header, .is-print-invoice .header, .is-print-invoice .logo {
    display: none;
}
  1. Open the template to be edited.
  2. In the Layout & Design section, double-click the Custom CSS field and specify the CSS code as required.
    Alternatively, you can click Edit in the detail view to edit the field.
  3. Click Save.

If you work with tenants, you can apply individual company information for them. The following example assumes that you want to use tenant-specific logos and footers, whereas the other information (like invoice texts and table configurations) remain the same. Implementing this example involves three steps:

Adding Tenant-Specific Logos

You can add the two logos using the image-by-ID mechanism (as mentioned in Handling Multiple Images) to a text building block like Header or Info Left.

Info

Following the example, the images are moved using the position CSS declaration, so you can use any generic text container to hold the image references.

Assuming the image IDs are ONE and TWO, use the following placeholders to declare the logos:

[img|byid:ONE][img|byid:TWO]
  1. Open the template to be edited.
  2. In the Header & Footer section, double-click, for example, the Header field and add the placeholders as required.
    Alternatively, you can click Edit in the detail view to edit the field.
  3. Click Save.

Adding Tenant-Specific Footers

Now you add two footers to the Footer field. To allow them for being addressed individually, you wrap them in addressable DIV elements, like

<div class="footer-ONE">Tenant ONE</div>
<div class="footer-TWO">Tenant TWO</div>
  1. Open the template to be edited.
  2. In the Header & Footer section, double-click the Footer field and add the footer texts as required.
    Alternatively, you can click Edit in the detail view to edit the field.
  3. Click Save.

Finally, you hide the logos and footers by default and enable them based on the tenant (named FIRST and SECOND following the example). These custom CSS rules do the job:

#ONE, #TWO {
    position: absolute;
    left:0;
    top:0;
    display: none;
}

.footer-ONE, .footer-TWO {
    display: none;
}

.tenant-FIRST #ONE, .tenant-FIRST .footer-ONE {
    display: block;
}

.tenant-SECOND #TWO, .tenant-SECOND .footer-TWO {
    display: block;
}
  1. Open the template to be edited.
  2. In the Layout & Design section, double-click the Custom CSS field and specify the CSS code as required.
    Alternatively, you can click Edit in the detail view to edit the field.
  3. Click Save.

Displaying Outstanding Invoices

Depending on your business requirements, you can have JustOn print a table of outstanding invoices on an invoice PDF. This table lists other open invoices of the corresponding account.

To configure the outstanding invoices table display in the invoice template, use the following fields:

Field Description Default Value
Outstanding Invoices Checkbox to enable or disable the outstanding invoices table display on the invoice.
Outstanding Invoices Text Specifies the text to be printed above the table of outstanding invoices. For your information, below is a list of outstanding invoices that are either unpaid, partially paid or overpaid.

To configure the outstanding invoices table display:

  1. Open the template to be edited.
  2. Click Edit in the detail view.
  3. In the Additional Content section, select or deselect the checkbox Outstanding Invoices modify the value for Outstanding Invoices Text as required.
  4. Click Save.

Accessing Template Debug Mode

The layout, styling, positioning of the template building blocks is controlled using CSS rules. JustOn defines a default set of CSS rules (see CSS Rules).

To identify the class for an element that you want to override using custom CSS, you can proceed as follows:

  1. Open the invoice.
    A standard URL of an invoice may look like
    https://<server>/apex/InvoiceView?id=<id>&sfdc.override=1 (Classic UI) or
    https://<server>/one/one.app#/sObject/<id>/view (Lightning UI)
  2. Modify the URL as follows, and press Enter.
    For Classic, replace the InvoiceView directive with InvoicePDF and append the query string &debug=true like:
    https://<server>/apex/InvoicePDF?id=<id>&sfdc.override=1&debug=true
    For Lightning, replace the path with apex/ONB2__InvoicePDF and add the query string as required:
    https://<server>/apex/ONB2__InvoicePDF?id=<id>&sfdc.override=1&debug=true.

If required, you can also add a language query string, like &lang=en, for example
https://<server>/apex/InvoicePDF?id=<id>&sfdc.override=1&debug=true&lang=en

▶ This opens the intermediate HTML file, which you can now inspect using your tool of choice.

Info

For further help with template customization, contact the JustOn support team.