Customizing Standard Templates

A standard template takes the content of the PDF from two places:

• The template record holds texts, labels, switches and formats. You change them in the record fields, without touching any code.
• The Liquid file attached to the template defines structure, appearance and fixed content – which blocks and which template fields are printed in which order, the columns of the invoice line item table, the default texts of the labels, the logo, fonts, colors and page layout.

A template field takes effect only if the Liquid file reads it. So before you change a standard template, check which of the two holds what you want to change. Some content that a classic template takes from template fields – for example, the header, the info blocks, the addresses or custom CSS – is part of the Liquid file on a standard template.

This article covers the following tasks:

• Locating relevant configuration
• Adding field to invoice line item table
• Printing shipping and handling fees
• Using override labels on standard templates
• Keeping changes across upgrades

For the basic setup of a standard template, see Configuring Standard Templates. For working with Liquid code in general – debug mode, filters, fonts and images – see Working With Liquid Code.

Locating Relevant Configuration

The following table shows where to make a change when you use the Liquid file that JustOn Billing & Invoice Management delivers. For a field-by-field list, see Standard Template Field Usage.

Adding Field to Invoice Line Item Table

Every field of the Invoice Line Item object that the user creating the PDF can read is available in the Liquid file, with no further configuration. Fields of related records, like the item or the subscription, are not available on the line item.

The following steps refer to the Liquid file that JustOn Billing & Invoice Management delivers, in which the columns are written into the file. If your Liquid file has been customized, its line item table may be structured differently. The example adds the custom field CostCenter__c.

A field is available as row.lineItem.<field>. Write the API name in lowercase and without the namespace prefix – row.lineItem.unit__c, not row.lineItem.ONB2__Unit__c. Custom fields you have created yourself have no namespace prefix anyway.

To add a column next to the description:

1. Find the API name of the field in the data structure.

   Open an invoice in the Liquid template debug mode with the URL parameter &debug=data, and look up the field in one of the lineItem entries of invoiceTable.

2. In the Liquid file, add a header cell to the table header.

   The table header is the <tr class="line-item-header"> element. Add the new <th> element at the position where the column is to appear:

   <th class="header-title">{{ labels['lineItemsTable.title'] | default: 'Title' }}</th>
   <th>{{ labels['lineItemsTable.costCenter'] | default: 'Cost Center' }}</th>
   

   For the column label, you can write a literal text, or read a label key with a fallback as shown here. To translate a label key, add it to the override labels of the template, see Using Override Labels on Standard Templates.

3. Add a data cell at the same position in the line item row.

   The line item row is the <tr class="line-item-row"> element. Add the new <td> element after the cell with the description:

   <td class="table-cost-center"><div>{{ row.lineItem.costcenter__c }}</div></td>
   

4. Adjust the column span of the subtotal and total rows.

   These rows span the table width with a calculated column span. Increase both values by one for each column you add:

   {% if hasdiscount %}
     {% assign invoice_colspan = 7 %}
   {% else %}
     {% assign invoice_colspan = 6 %}
   {% endif %}
   

   On final invoices, the title row of the received payments block uses a fixed column span (colspan="7"). Increase it as well.

5. Upload the edited file to the template and check the result.

   For uploading the file, see Attaching a Liquid File. Then create the PDF for a draft invoice and make sure that the new column is printed and that the subtotal and total rows are aligned.

Printing Shipping and Handling Fees

As of v2.123, the Liquid file that JustOn Billing & Invoice Management delivers prints line items of the type Shipping Fees and Handling Fees: one row per fee with its title and net amount, followed by the tax of the fees per tax rate – like a classic template. On final invoices, the tax of the fees is also listed in the remaining amount block.

The tax rows of the fees are printed separately from the tax rows of the products, so a tax rate can appear twice – once for the products and once for the fees. The fee rows use the labels of the line item table: the title of the fee line item, and the tax label from the Tax Label field or the override label totals.tax.

A Liquid file that was attached to a template before v2.122 does not print the fees, although their amounts are included in the grand total. As a result, the printed line items do not add up to the grand total. To print the fees, add the code of the current delivered Liquid file to the attached file:

1. In the Liquid file, find the comment <!-- Display the grand total for non final invoice: -->.

   It follows the loop over the rows of the line item table, directly before the grand total row.

2. Insert the following code directly before this comment:

   {% for feeSection in invoiceTable %}
     {% if feeSection.section == 'Detail:Shipping Fees' or feeSection.section == 'Detail:Handling Fees' %}
       {% for feeRow in feeSection.rows %}
         {% if feeRow.lineItem %}
           <tr class="fee-row">
             <td></td>
             <td colspan="{{ invoice_colspan }}">{{ feeRow.lineItem.title__c }}</td>
             <td>{{ feeRow.lineItem.postotalnet__c | currency }}</td>
           </tr>
         {% endif %}
         {% if feeRow.subtotalType == 'subtotalTax' %}
           <tr class="subtotal-tax fee-tax">
             <td></td>
             {% assign _feeTaxRatePct = feeRow.taxRate | percent %}
             {% assign _feeTaxLbl = labels['totals.tax'] | default: 'Tax ({rate})' %}
             <td colspan="{{ invoice_colspan }}">{{ _feeTaxLbl | replace: '{rate}', _feeTaxRatePct }}</td>
             <td>{{ feeRow.subtotal.subtotalTax | currency }}</td>
           </tr>
         {% endif %}
       {% endfor %}
     {% endif %}
   {% endfor %}
   

3. For final invoices, find the row <tr class="remaining-amount-gross"> in the remaining amount block.

   It follows the loop that prints the remaining tax per tax rate.

4. Insert the following code directly before this row:

   {% for feeSection in invoiceTable %}
     {% if feeSection.section == 'Detail:Shipping Fees' or feeSection.section == 'Detail:Handling Fees' %}
       {% for feeRow in feeSection.rows %}
         {% if feeRow.subtotalType == 'subtotalTax' %}
           <tr class="subtotalTax fee-tax">
             <td></td>
             {% assign _remFeeTaxPct = feeRow.taxRate | percent %}
             {% assign _remFeeTaxLbl = labels['totals.tax'] | default: 'Tax ({rate})' %}
             <td colspan="4">{{ _remFeeTaxLbl | replace: '{rate}', _remFeeTaxPct }}</td>
             <td>{{ feeRow.subtotal.subtotalTax | currency }}</td>
           </tr>
         {% endif %}
       {% endfor %}
     {% endif %}
   {% endfor %}
   

5. Upload the edited file to the template, see Attaching a Liquid File.

6. Create the PDF for a draft invoice with a shipping fee and check that the printed rows add up to the grand total.

Alternatively, create a new template using New, which attaches the current delivered file, and transfer your changes to it, see Keeping Changes Across Upgrades.

Using Override Labels on Standard Templates

The Override Labels field of a standard template translates the fixed labels of the PDF, like the column headers or the document type heading. A standard template reads only the v3 block of the field:

{
    "v3": {
        "lineItemsTable.quantity": "Menge",
        "lineItemsTable.costCenter": "Kostenstelle"
    }
}

The field is not a general label override like the override labels of classic templates:

• The Liquid file reads a fixed set of keys. The delivered file reads the keys listed in Override Labels.
• You can add any other key, but it has no effect until the Liquid file reads it – like the key lineItemsTable.costCenter in the example above.
• Field labels from Salesforce are not used. To label a column you add, write the label into the Liquid file or read your own key.

A key that is missing from the field falls back to the default text written in the Liquid file. For the labels that have a dedicated template field, the field value takes precedence over the key.

To use different labels for one invoice type, you specify the Override Labels field on the template detail for this type:

1. Open the template and copy the complete value of the Override Labels field.

2. In the Template Details section, click Edit in the row of the template detail for the invoice type, for example, Cancelation.

   If there is no template detail for this type yet, create one, see Creating New Template Detail.

3. Paste the copied value into the Override Labels field.

4. Change the keys you need.

   Modify, for example, messages.cancelRelated for the opening sentence of cancellations, or messages.credit for the opening sentence of credits without related invoice.

5. Click Save.

Keeping Changes Across Upgrades

The Liquid file attached to a template is a copy of the delivered file, created when the template is created. Package upgrades of JustOn Billing & Invoice Management do not change attached Liquid files. You can therefore edit the attached file directly – your changes are kept when you upgrade.

This also means that improvements to the delivered Liquid file in a later version do not reach your existing templates. To use them, create a new template using New, which attaches the current delivered file, and transfer your changes to it.