PDF Invoice Customisation

From WHMCS Documentation

Revision as of 23:07, 20 November 2020 by SarahK (talk | contribs)

There are two invoice templates. One is for the system theme invoice template (viewinvoice.tpl). The other is for the PDF version of an invoice (invoicepdf.tpl). The template files are in the active WHMCS system theme template folder.

The logo on the PDF invoices is in the /assets/img/ folder. To change this logo, upload the required logo to the /assets/img/ folder. The name of the file should be logo.jpg or logo.png.

You can change the width of the logo image in the invoicepdf.tpl template file. On line 10, adjust the last number (75) before the closing bracket ();). This variable defines the image width. A developer can then increase or decrease this.

Header & Footer

This section describes a feature available in WHMCS 7.0 and above.

It is possible to cause a header or footer to automatically repeat on every page of a multi-page PDF invoice. If they are present in your theme, the system will include the following system theme template files for every rendered PDF page:

  • invoicepdfheader.tpl
  • invoicepdffooter.tpl

The system only requires the respective header or footer files. For example, for a customized footer on each page, create a invoicepdffooter.tpl file. You must store these files in the same directory as the invoicepdf.tpl system theme template file.

During template processing, Smarty will provide each of these system theme template files with the same variables as invoicepdf.tpl.

Editing Text and Content

A developer can customise the PDF invoices. This includes adding or removing text, altering the layout, or adding further images and formatting. Do this by editing the invoicepdf.tpl system theme template file in the active template folder. The file contains all the code relating to the layout and display of the invoice in its PDF format. You will need a basic working knowledge of PHP coding to understand and modify the file.

The system generates PDFs using TCPDF. See the full list of functions to build this.

Displaying Custom Fields

It is possible to display custom fields on printable and PDF invoices. To do this, select Configuration () > System Settings > Custom Fields > Show on Invoice or, prior to WHMCS 8.0, Setup > Custom Client Fields > Show on Invoice.

The following variables are available for use in the invoicepdf.tpl file:

  • $invoiceid — The ID of the invoice.
  • $invoicenum — The custom number of the invoice (only set this when you have enabled proforma or sequential invoicing).
  • $datecreated — The creation date of the invoice.
  • $duedate — The due date of the invoice.
  • $datepaid — The paid date and time, if invoice status is Paid.
  • $userid — The client ID number.
  • $clientsdetails["firstname"] — The client information First Name.
  • $clientsdetails["lastname"] — The client information Last Name.
  • $clientsdetails["companyname"] — The client information Company Name.
  • $clientsdetails["fieldname"] — Other client information values, where fieldname is that item's name.
  • $customfields — An array of Client Custom Fields (for example, $customfields['Custom Field Name']). See Easy Translation for help with dynamically translating Custom Field Names.
  • $subtotal
  • $tax
  • $taxrate
  • $credit
  • $total
  • $status — Paid, unpaid, or cancelled.
  • $paymentmethod
  • $notes
  • $companyname — The Company Name.
  • $companyurl — The Default Website URL.
  • $companyaddress — The Company Address.
  • $invoiceitems — An array of invoice items.

Obtain further data by running SQL queries from within the PHP template.

Changing/Translating Filename

The default filename for invoices is Invoice-xxx. For quotes, this is Quote-xxx. For both, xxx is the ID of the invoice or quote. It may be desirable to change the filenames the clients see or translate it into other languages. Achieve this in the same way as any text within WHMCS, by using the Language Files. Look for these strings:

$_LANG['invoicefilename'] = "Invoice-";
$_LANG['quotefilename'] = "Quote-";

Reducing the File Size of PDFs

The bulk of the file size for PDFs that WHMCS generates come from the embedded font files for UTF-8. Because the UTF-8 charset has a large range of supported characters, this means it takes up more space than, for example, the ISO-8859-1 character set. Unlike UTF-8, ISO-8859-1 only supports A-Z, a-z, 0-9, and other standard characters.

If no clients are using special characters in their names or addresses, the system does not require UTF-8. It is then possible to reduce the size of PDF files by changing the font. To do that, go to Configuration () > System Settings > General Settings or, prior to WHMCS 8.0, Setup > General Settings in the Invoices tab. Then, change PDF Font Family to Helvetica.

Additional Fonts

The use of certain special characters may not be available in the standard font. So, WHMCS supplies an alternative font type that supports Czech, Russian, Arabic, and Persian, among others.

Version 7.7 and later

In version 7.7 and later, the system doesn't require any additional files.

To make this change:

  1. Navigate to Configuration () > System Settings > General Settings or, prior to WHMCS 8.0, Setup > General Settings and select the Invoices tab.
  2. Select Dejavusans for the PDF Font Family setting.
  3. Click Save Changes.

Version 7.6 and earlier

To make this change:

  1. Download the font files from the URL below.
  2. Upload them to /vendor/tecnickcom/tcpdf/fonts/.
  3. Go to Configuration () > System Settings > General Settings or, prior to WHMCS 8.0, Setup > General Settings in the Invoices tab.
  4. Change PDF Font Family to dejavusans.
For more information, see the Download page.

Troubleshooting

Accented Characters

Due to a PHP limitation, the translations of the "Paid" and "Unpaid" text on the PDF Invoices may not display uppercase accented characters.

To resolve this, see this forum thread.

Question Marks

Sometimes, question marks appear in the PDF files in place of non-Latin or accented characters. This can suggest that the font doesn't support the character.

Go to Configuration () > System Settings > General Settings or, prior to WHMCS 8.0, Setup > General Settings in the Invoices tab. Then, change PDF Font Family to Freesans.

If the problem persists, download and install "dejavusans" using the steps in Additional Fonts. This font pack contains more characters than standard ones, so it is likely to work with these characters.

TCPDF error: Missing or incorrect image file

This means the logo.png or logo.jpg file in /assets/img/ is missing or is not a valid image file. This is the image that the system uses when creating the PDF invoice. Save the image file again and reupload it to /assets/img directory.

Retrieved from "http://3.17.75.209/index.php?title=PDF_Invoice_Customisation&oldid=29692"