logo

Templates in ccInvoices

Page contents:

Introduction

ccInvoices has a set of templates for commonly used documents and messages. Note that the default font in Joomla! and the template is helvetica. This is one of the best font’s as it is installed on most computers and will cause the least issues because of that. The font can be changed in the PDF settings of a template.

The default templates are:

  • Invoice PDF: template for the PDF invoice
  • Invoice export CSV: text template for CSV exports of invoices
  • Invoice note: template for the invoice note (will be shown in the Invoice PDF with tag {invoice_note})
  • Invoice e-mail: template of the e-mail used when sending an invoice to customers
  • Invoice e-mail reminder: template of the e-mail used when sending a payment reminder to customers
  • New user e-mail: when a new user is created in ccInvoices, not the default Joomla! notification is sent, but this e-mail. You can customize the email to include instructions to the user about viewing and paying invoices.

ccInvoices templates overview

Modifying templates

It is possible to modify the templates, for example to add some mandatory information for your country. This can easily be done with the help of the Joomla! WYSIWYG editor. To modify templates, login to the Joomla! administrator, then go to Components > ccInvoices > Templates. There open and edit the template save. On the right of the template edit view, when applicable, there will be a box containing all possible template tags (which will be converted to actual information when the document is created) and PDF settings.

In ccInvoices 1.6+ the Invoice PDF template has a separate box for the layout of the invoice items for new ccInvoices installations. This solves issues where the invoice items where not aligned correctly. To keep backward compatibility with older versions of ccInvoices, this feature is disabled for users that upgrade to ccInvoices 1.6+. To enable it go to the template, click “PDF settings” and select “New layout”. Please review your template after you changed this setting.

Your template modifications will not be lost when uninstalling or upgrading ccInvoices.

ccInvoices template edit

JCE and template tags

In JCE editor, they have an option as “Keep non-breaking spaces” under Admin > Components > JCE Editor > Editor global configuration. If we use “yes” then it will change the extra space to “ ”. In Joomla default, TinyMCE Editor, doesn’t support this. It can cause issues with tags because with the extra space they are no longer recognized and converted to data. You can fix the issue, by changing the “Keep non-breaking spaces” option to “no”.

 

Using if functions for tags

You can use if statements to only show tags when they have a value. Syntax example:

 {if:tag_name}…{/if} and {if:!tag_name}…{/if} 

Another example: {if:contact_tax_id}VAT ID: {contact_tax_id}{/if}

That will make the text only show if {contact_tax_id} has a value (and is not 0).

How to use “VAT deferred”

ccInvoices had a basic implementation for deferred VAT:

1. Add ‘none’ or ‘geen’ to your possible tax values in ccInvoices > Configuration > Tax settings in format none;0;9;21 for example.

2. If you also want to hide the labels “Tax”, “Tax %” etc, you can use conditionals in ccInvoices > Templates > Invoice PDF. The format should be: {if:invoice_tax_total}Tax:{/if}

3. Open the invoice where no tax should be added in ccInvoices > Invoices

4. For one of the invoice items select “none” as Tax percentage, the entire invoice will then not display taxes

5. You might want to add a message to the invoice note saying “VAT deferred” manually

 

PDF settings

PDF settings can be used to change general document properties like orientation and margins.

Fonts

Only use exotic fonts like “Arial unicode” when your language is Chinese, Japanese or any other language that requires it. Using exotic fonts for English, Dutch etc will cause issues with PDF readers that do not have the that font pack installed. Times, Verdana and Helvetica are on almost all computers and safest to use.

If you need support for Chinese and other non-Western characters, Check out FAQ 7.

Background image

If you want to have a background image behind your invoices, you will need to create it in a PNG format in your favourite image editing software (Photoshop etc). You can then use the background image options under the PDF settings in the Invoice PDF template. To have a background image over the entire invoice, in full A4 paper size, the image you create needs to have the same size as a A4 piece of paper, which are width 210 millimeters and height 297 millimeters. Also enter these amounts into the PDF settings, and set all “positions” to 0.

 

HTML and CSS in templates

When styling a PDF document you can not use all HTML and CSS functions. This is limited by third-party PDF libraries. A PDF library converts HTML/CSS output to PDF, and unfortunately PDF libraries do not support as much CSS functions as browsers (Firefox, Chrome etc) do. Therefor, when using HTML and CSS to style a template in our extensions, try not to use advanced CSS functions. The only way to be sure what is and is not supported is by trial and error.

We already use the best PDF library in our extensions (TCPDF), and we will keep it up to date so even more CSS functions become available gradually.

 

About changes to the default template

We have had the request to change the default template a few times, so we thought we would explain here why we will not make cosmetic changes to the default template.

You are free to change the template to your liking, but it’s unlikely we will change it unless there is something broken. Please understand that all our customers have different ideas about what is professional, beautiful and good. And in different countries there are also different customs and requirements for invoices. So if we change the default invoice template, we will just get people asking to change it back or saying “this is not better”. That’s why it is a basic template with all information, and everyone can change it to their wishes. A Joomla! template is also not 100% perfect out of the box and people always change those, it’s the same situation.

We are sure you understand the logic of it all.

Default templates

Below is a zip file containing all current default templates in ccInvoices 1.6+. Every template is added as a .html file with the template code. This can be used when you want to revert back to the default template, or when you are upgrading from an earlier ccInvoices version and want to know what changes have been made in the default templates compared to your customized templates.

Download ccInvoices_templates.zip

Example: adding new column to template items

This is an example of adding a new column to the template items section (where products and services can be listed on the invoice) with the default Joomla! editor (TinyMCE). Notice that we added the column header/title “New Column Name” in the “Template header” box and add the actual tag for the new column in the “Template items” box. We used the {new_column_tag} as an example, it does not do anything, you could add any of the item tags, for example: {item_tax_amount}. If you are experienced with HTML, use Tools > Source Code for even more control.