Difference between revisions of "PDF Invoice Customisation"

Latest revision as of 17:41, 27 April 2022

You can customize invoice and quote PDF files using a template file system. You can find these files in the templates directory of the active WHMCS system theme.

1 Template Files
2 Header and Footer
- 2.1 Invoice Header and Footer
- 2.2 Quote Header and Footer
3 Modifying the Logo
4 Editing Text and Content
- 4.1 Adding Custom Fields
5 Changing or Translating Filenames
6 Reducing the File Size of PDFs
7 Additional Fonts
- 7.1 WHMCS 7.7 and later
- 7.2 WHMCS 7.6 and earlier
8 Troubleshooting

Template Files

You can customize the following templates:

templates/viewinvoice.tpl controls the system theme invoice template.
templates/invoicepdf.tpl controls the PDF version of the invoice.
templates/quotepdf.tpl controls quote PDFs.

Header and Footer

We added this feature in WHMCS 7.0.

You can cause a header or footer to automatically repeat on every page of a multi-page PDF invoice or quote by updating the header and footer templates.

Invoice Header and Footer

If they exist in your theme, the system will include the following system theme template files on 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 the 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 files with the same variables that it provides to invoicepdf.tpl.

Quote Header and Footer

If they exist in your theme, the system will include the following template files for every rendered PDF page:

quotepdfheader.tpl
quotepdffooter.tpl

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

During template processing, Smarty will provide each of these files with the same variables that it provides to quotepdf.tpl.

Modifying the Logo

The logo on PDF invoices and quotes 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.

Editing Text and Content

You can customise the contents of PDF invoices and quotes by adding or removing text, altering the layout, or adding images and formatting. To do this, edit the invoicepdf.tpl or quotepdf.tpl system theme template files in the active template folder. These files contain all of the code relating to the layout and display in the PDF file.

You will need a basic working knowledge of PHP coding to understand and modify the file.

The system generates PDFs using TCPDF. For more information, see the TCPDF website.

Adding Custom Fields

To display custom fields on printable and PDF invoices, go to Configuration () > System Settings > Custom Fields or, prior to WHMCS 8.0, Setup > Custom Client Fields. Then, select 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.

You can retrieve more data by running SQL queries from within the PHP template.

Changing or Translating Filenames

Invoices and quotes have default generated filename formats:

The default filename for invoices is Invoice-xxx.
The default filename for quotes is Quote-xxx.

In both of these filenames, xxx is the ID of the invoice or quote.

To change or translate these, use the WHMCS language files. When you do this, look for these lines:

$_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, these files are larger than, for example, files that use 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. You can then reduce the size of PDF files by changing the font.

To do this, change PDF Font Family to Helvetica in the Invoices tab at Configuration () > System Settings > General Settings or, prior to WHMCS 8.0, Setup > General Settings.

Additional Fonts

The standard font may not support certain special characters. WHMCS supplies an alternative font type that supports languages that require these characters (for example, Czech, Russian, Arabic, and Persian).

WHMCS 7.6 and earlier requires you to download additional files in order to change to the alternate font. In WHMCS 7.7 and later, WHMCS ships with all required files.

WHMCS 7.7 and later

To change to the alternate font in WHMCS 7.7 and later:

Go to Configuration () > System Settings > General Settings or, prior to WHMCS 8.0, Setup > General Settings.
Select the Invoices tab.
Select Dejavusans for PDF Font Family.
Click Save Changes.

WHMCS 7.6 and earlier

To change to the alternate font in WHMCS 7.6 and earlier:

Download the font files.
Upload the font files to the /vendor/tecnickcom/tcpdf/fonts/ folder.
Go toSetup > General Settings.
Select the Invoices tab.
Select dejavusans for PDF Font Family.
Click Save Changes.

Troubleshooting

Accented Characters

Due to a limitation in PHP, 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 indicate that the character is unsupported in the current font.

To resolve this:

Go to Configuration () > System Settings > General Settings or, prior to WHMCS 8.0, Setup > General Settings.
Select the Invoices tab.
Select Freesans for PDF Font Family.
Click Save Changes.

If the problem persists, download and install "dejavusans" using the steps above. The dejavusans font pack includes additional characters and is more likely to contain the characters you need.

TCPDF error: Missing or incorrect image file

This error indicates that the logo.png or logo.jpg file in the /assets/img/ directory is missing or is not a valid image file. The system uses this image when creating the PDF invoice.

To resolve this, save the image file again and reupload it to the /assets/img directory.

@@ Line 1: / Line 1: @@
-==Modifying the Logo==
+You can customize invoice and quote PDF files using a template file system. You can find these files in the <tt>templates</tt> directory of the active WHMCS system theme.
-The logo displayed on the PDF invoices is located in the images folder.  To change this to your own logo simply upload your logo to the images folder and name it "logo.jpg".
+== Template Files ==
-==Editing Text & Content==
+You can customize the following templates:
-You can fully customize the PDF invoices adding or removing text from them.  This is done by editing the file "includes/pdfconfig.php".  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 in order to understand and modify the file.
+* <tt>templates/viewinvoice.tpl</tt> controls the system theme invoice template.
+* <tt>templates/invoicepdf.tpl</tt> controls the PDF version of the invoice.
+* <tt>templates/quotepdf.tpl</tt> controls quote PDFs.
-The PDF's are generated using FPDF (Free PDF) & you can find a list of variables here: http://www.fpdf.org/
+== Header and Footer ==
-==Available Variables==
+<div class="docs-alert-info">
+We added this feature in WHMCS 7.0.
+</div>
-The following variables are available for usage in the pdfconfig.php file.
+You can cause a header or footer to automatically repeat on every page of a multi-page PDF invoice or quote by updating the header and footer templates.
-*$datecreated - The date the invoice was created
+=== Invoice Header and Footer ===
-*$duedate - The date the invoice is due
-*$datepaid - Shows paid date/time if invoice is set to Paid
+If they exist in your theme, the system will include the following system theme template files on every rendered PDF page:
-*$userid - Client ID Number
-*$clientsdetails["firstname"] - Client Info First Name
+* <tt>invoicepdfheader.tpl</tt>
-*$clientsdetails["lastname"] - Client Info Last Name
+* <tt>invoicepdffooter.tpl</tt>
-*$clientsdetails["companyname"] - Client Info Company Name
-*$clientsdetails["fieldname"] - etc...
+The system only requires the respective header or footer files. For example, for a customized footer on each page, create the <tt>invoicepdffooter.tpl</tt> file. You must store these files in the same directory as the <tt>invoicepdf.tpl</tt> system theme template file.
-*$clientsdetails["customfields1"] - Client Info Custom Field #1
-*$subtotal
+During template processing, Smarty will provide each of these files with the same variables that it provides to <tt>invoicepdf.tpl</tt>.
-*$tax
-*$taxrate
+===Quote Header and Footer===
-*$credit
-*$total
+If they exist in your theme, the system will include the following template files for every rendered PDF page:
-*$status - Paid, Unpaid or Cancelled
-*$paymentmethod
+* <tt>quotepdfheader.tpl</tt>
-*$notes
+* <tt>quotepdffooter.tpl</tt>
-*$companyname - Your Company Name
-*$companyurl - Your Default Website URL
+The system only requires the respective header or footer files. For example, for a customized footer on each page, create the <tt>quotepdffooter.tpl</tt> file. You must store these files in the same directory as the <tt>quotepdf.tpl</tt> template file.
-*$companyaddress - Your Company Address
-*$currencysymbol - Active Currency Symbol
+During template processing, Smarty will provide each of these files with the same variables that it provides to <tt>quotepdf.tpl</tt>.
-*$invoiceitems - Array of invoice items
-*$grandtotal - Grand Total of invoice items
+== Modifying the Logo ==
+The logo on PDF invoices and quotes is in the <tt>/assets/img/</tt> folder. To change this logo, upload the required logo to the <tt>/assets/img/</tt> folder. The name of the file should be <tt>logo.jpg</tt> or <tt>logo.png</tt>.
+You can change the width of the logo image in the <tt>invoicepdf.tpl</tt> template file. On line <tt>10</tt>, adjust the last number (<tt>75</tt>) before the closing bracket (<tt>);</tt>). This variable defines the image width.
+== Editing Text and Content ==
+You can customise the contents of PDF invoices and quotes by adding or removing text, altering the layout, or adding images and formatting. To do this, edit the <tt>invoicepdf.tpl</tt> or <tt>quotepdf.tpl</tt> system theme template files in the active template folder. These files contain all of the code relating to the layout and display in the PDF file.
+You will need a basic working knowledge of PHP coding to understand and modify the file.
+<div class="docs-alert-success">
+The system generates PDFs using TCPDF. For more information, see the [https://tcpdf.org/ TCPDF website].
+</div>
+===Adding Custom Fields===
+To display custom fields on printable and PDF invoices, go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Custom Fields]]''' or, prior to WHMCS 8.0, '''Setup > Custom Client Fields'''. Then, select '''Show on Invoice'''.
+The following variables are available for use in the <tt>invoicepdf.tpl</tt> file:
+* <tt>$invoiceid</tt> — The ID of the invoice.
+* <tt>$invoicenum</tt> — The custom number of the invoice. Only set this when you have enabled proforma or sequential invoicing.
+* <tt>$datecreated</tt> — The creation date of the invoice.
+* <tt>$duedate</tt> — The due date of the invoice.
+* <tt>$datepaid</tt> — The paid date and time, if invoice status is '''Paid'''.
+* <tt>$userid</tt> — The client ID number.
+* <tt>$clientsdetails["firstname"]</tt> — The client information '''First Name'''.
+* <tt>$clientsdetails["lastname"]</tt> — The client information '''Last Name'''.
+* <tt>$clientsdetails["companyname"]</tt> — The client information '''Company Name'''.
+* <tt>$clientsdetails["fieldname"]</tt> — Other client information values, where <tt>fieldname</tt> is that item's name.
+* <tt>$customfields</tt> — An array of '''Client Custom Fields''' (for example, $customfields['Custom Field Name']). See [[Easy Translation]] for help with dynamically translating '''Custom Field Names'''.
+* <tt>$subtotal</tt>
+* <tt>$tax</tt>
+* <tt>$taxrate</tt>
+* <tt>$credit</tt>
+* <tt>$total</tt>
+* <tt>$status</tt> — Paid, unpaid, or cancelled.
+* <tt>$paymentmethod</tt>
+* <tt>$notes</tt>
+* <tt>$companyname</tt> — The '''Company Name'''.
+* <tt>$companyurl</tt> — The '''Default Website URL'''.
+* <tt>$companyaddress</tt> — The '''Company Address'''.
+* <tt>$invoiceitems</tt> — An array of invoice items.
+You can retrieve more data by running SQL queries from within the PHP template.
+== Changing or Translating Filenames ==
+Invoices and quotes have default generated filename formats:
+* The default filename for invoices is <tt>Invoice-xxx</tt>.
+* The default filename for quotes is <tt>Quote-xxx</tt>.
+In both of these filenames, <tt>xxx</tt> is the ID of the invoice or quote.
+To change or translate these, use the WHMCS [[Language Files|language files]]. When you do this, look for these lines:
+<div class="source-cli">
+$_LANG['invoicefilename'] = "Invoice-";
+<br/>$_LANG['quotefilename'] = "Quote-";
+</div>
+== 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, these files are larger than, for example, files that use the ISO-8859-1 character set. Unlike UTF-8, ISO-8859-1 only supports <tt>A-Z</tt>, <tt>a-z</tt>, <tt>0-9</tt>, and other standard characters.
+If no clients are using special characters in their names or addresses, the system does not require UTF-8. You can then reduce the size of PDF files by changing the font.
+To do this, change '''PDF Font Family''' to ''Helvetica'' in the '''[[Invoice Tab|Invoices]]''' tab at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > General Settings''' or, prior to WHMCS 8.0, '''Setup > General Settings'''.
+== Additional Fonts ==
+The standard font may not support certain special characters. WHMCS supplies an alternative font type that supports languages that require these characters (for example, Czech, Russian, Arabic, and Persian).
+WHMCS 7.6 and earlier requires you to download additional files in order to change to the alternate font. In WHMCS 7.7 and later, WHMCS ships with all required files.
+=== WHMCS 7.7 and later ===
+To change to the alternate font in WHMCS 7.7 and later:
+# Go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[General Settings]]''' or, prior to WHMCS 8.0, '''Setup > General Settings'''.
+# Select the '''[[Invoice Tab|Invoices]]''' tab.
+# Select ''Dejavusans'' for '''PDF Font Family'''.
+# Click '''Save Changes'''.
+=== WHMCS 7.6 and earlier ===
+To change to the alternate font in WHMCS 7.6 and earlier:
+# [https://www.whmcs.com/download/106/dejavusans_tcpdf_font Download the font files.]
+# Upload the font files to the <tt>/vendor/tecnickcom/tcpdf/fonts/</tt> folder.
+# Go to'''Setup > General Settings'''.
+# Select the '''[[Invoice Tab|Invoices]]''' tab.
+# Select ''dejavusans'' for '''PDF Font Family'''.
+# Click '''Save Changes'''.
+== Troubleshooting ==
+=== Accented Characters ===
+Due to a limitation in PHP, the translations of the '''Paid''' and '''Unpaid''' text on the PDF Invoices may not display uppercase accented characters.
+To resolve this, see [http://forum.whmcs.com/showthread.php?t=45594 this forum thread].
+=== Question Marks ===
+Sometimes, question marks appear in the PDF files in place of non-Latin or accented characters. This can indicate that the character is unsupported in the current font.
+To resolve this:
+# Go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[General Settings]]''' or, prior to WHMCS 8.0, '''Setup > General Settings'''.
+# Select the '''[[Invoice Tab|Invoices]]''' tab.
+# Select ''Freesans'' for '''PDF Font Family'''.
+# Click '''Save Changes'''.
+If the problem persists, download and install "dejavusans" using the steps [[#Additional_Fonts|above]]. The ''dejavusans'' font pack includes additional characters and is more likely to contain the characters you need.
+===TCPDF error: Missing or incorrect image file===
+This error indicates that the <tt>logo.png</tt> or <tt>logo.jpg</tt> file in the <tt>/assets/img/</tt> directory is missing or is not a valid image file. The system uses this image when creating the PDF invoice.
+To resolve this, save the image file again and reupload it to the <tt>/assets/img</tt> directory.

Documentation