Invoice Templates

Pricing / Buy Now

Invoice Templates

The invoices produced by nBill are template-driven. It is therefore possible to format your invoice to get whatever look-and-feel you want, and you can use a different template for different vendors if you are making use of the multi-company feature.

Full instructions for creating an invoice template are in the comments of the default template file (com_nbill/templates/invoice_default/index.php), but for your convenience are reproduced here:

/*
You can create your own invoice template based on this one, but if you want to modify this one directly, it is recommended to backup this file first (you should also keep a record of any changes you make and backup your customised file, as your changes could be lost when you upgrade). It is best to add your own template to another folder inside the components/com_nbill/templates folder, and update the vendor record with your own template's folder name.

There are various variables and objects available to you, and these are described below. You can use standard PHP code and HTML to define how the data is displayed (bear in mind that this file is included once for each invoice).

CSS class definitions must be stored in a separate file called 'template.css' in the same folder as this index.php file. A link to this CSS file (if it exists) will automatically be added by the component.

Do not try to link to template.css or any other style sheet from this template file as this would result in invalid HTML (the <head> section has already been defined by the time we get to this file), and the PDF generator (if you are using it) will probably not read the stylesheet.

However, you can add styling in here if it is only going to be used for HTML previews and you don't mind invalid HTML - just wrap it in a php condition (checking the $pdf flag). Inline style attributes are ok for both HTML and PDF.

Variables available:
Some of the variables are arrays indexed by document id - this is because the data for all invoices to be printed is already stored in these variables before this template file is invoked to provide the layout for each invoice. You can just use $document->id as the index for these arrays.

$pdf (boolean) Whether or not the output will be rendered as a PDF document (use this to suppress display of any elements that don't get rendered properly in PDF format - eg. shading and borders together can sometimes cause problems)
$template_path (string) Fully qualified path to this template
$logo_file (string) Fully qualified image file name for the logo associated with this vendor (use this to check whether a logo file exists)
$logo_src (string) HTTP src reference for the vendor logo (use this to actually include the image)
$currency_symbol (array) Array of currency symbols, indexed by document id
$date_format (string) Date format string (eg. "d/m/Y")
$document (object) Contains global information about the invoice:
        ->id (int) Unique document identifier
        ->vendor_id (int) Unique identifier for vendor (you can ignore this)
        ->entity_id (int) Unique identifier for client (you can ignore this)
        ->document_no (string) The invoice number
        ->vendor_name (string) Name of the vendor
        ->vendor_address (string) Address of vendor (bear in mind that this might contain line breaks ("\n") which need converting to "<br />")
        ->billing_name (string) Name of person or company to whom invoice is made out
        ->billing_address (string) Billing address without country (bear in mind that this might contain line breaks ("\n") which need converting to "<br />")
        ->billing_country (string) 2 character country code
        ->billing_country_desc (string) Full country name (NOTE: This may appear in upper case - use ucwords(strtolower($document->billing_country_desc)) to convert to title case)
        ->reference (string) Your own reference
        ->document_date (int) Invoice date expressed as number of seconds since UNIX epoch (1st Jan 1970) - use PHP date() function in conjunction with $date_format variable to return a readable date
        ->tax_desc (string) Description of Vendor's tax code (eg. "VAT Number")
        ->tax_no (string) Vendor's VAT number or equivalent
        ->tax_exemption_code (string) Client's VAT number or reseller certification number
        ->currency (string) 3 character currency code (eg. USD or GBP)
        ->total_net (decimal) Net total of invoice (use format_number function to render in an acceptable format for currency)
        ->total_tax (decimal) Total tax for invoice (use format_number function to render in an acceptable format for currency)
        ->total_shipping (decimal) Total shipping for invoice (use format_number function to render in an acceptable format for currency)
        ->total_shipping_tax (decimal) Total tax for shipping (use format_number function to render in an acceptable format for currency)
        ->total_gross (decimal) Gross total (ie. amount due) (use format_number function to render in an acceptable format for currency)
        ->payment_instructions (string) Details of how the customer can pay
        ->small_print (string) Legal information
        ->paid_in_full (0 or 1) Whether the whole invoice has already been paid
        ->partial_payment (0 or 1) Whether the invoice has been partly paid
        ->refunded_in_full (0 or 1) Whether the invoice has been refunded in full
        ->partial_refund (0 or 1) Whether the invoice has been partly refunded
        ->notes (string) Your own additional notes - NB. In most cases, you will not want this displayed on the invoice!
        ->document_type (string) 'IN' = Invoice; 'CR' = Credit Note; 'QU' = Quote; 'PO' = Purchase Order
$document_items (array) Array of objects containing information about the individual items that make up the invoice
        ->id (int) Unique invoice ITEM identifier
        ->document_id (int) Unique document identifier (NB. ALWAYS check that this matches the value in $document->id otherwise you might end up writing items from other invoices onto the current one!)
        ->vendor_id (int) Unique identifier for vendor (you can ignore this)
        ->entity_id (int) Unique identifier for client (you can ignore this)
        ->nominal_ledger_code (string) This would not normally be included on the invoice, so ignore it
        ->product_description (string) Item description
        ->detailed_description (string) HTML description (unlimited size)
        ->net_price_per_unit (decimal) Cost per unit of the given item
        ->no_of_units (decimal) Quantity (note, this can be a decimal fraction)
        ->discount_amount (decimal) Amount of any discount applied to this item
        ->discount_description (string) Description of discount (ie. what it's for)
        ->net_price_for_item (decimal) Net price after multiplying unit price by quantity and subtracting any discount
        ->tax_for_item (decimal) Amount of tax
        ->shipping_id (int) Unique identifier for shipping service (you can ignore this)
        ->shipping_for_item (decimal) Cost of shipping for this item
        ->tax_for_shipping (decimal) Amount of tax applied to shipping amount
        ->gross_price_for_item (decimal) Total price for this item, including tax and shipping
$show_remittance (boolean) Whether or not to add a remittance advice slip to the end of the invoice
$show_paylink (boolean) Whether or not to add a link to allow the user to pay online
$payment_date (int) Date payment was received (null if invoice not paid in full, or income item not found), expressed as number of seconds since UNIX epoch (1st Jan 1970) - use PHP date() function in conjunction with $date_format variable to return a readable date
$payment_method (string) Method of payment (null if invoice not paid in full, or income item not found)
$transaction_no (string) Receipt number for the payment (null if invoice not paid in full, or income item not found)

The following "$hide_" variables allow you to determine whether it is possible to suppress the dispaly of certain fields to save space (eg. if there is only one unit mentioned on the invoice, there is no need to display the unit price and quantity). However, you do not have to hide these fields if you don't want to. All of these "$hide_" variables are arrays indexed by invoice id.
$hide_unit_price
$hide_quantity
$hide_discount
$hide_net_price
$hide_tax
$hide_shipping
$hide_shipping_tax

There are two special arrays which contain a summary of tax information for the invoice:

$tax_rates
$tax_rate_amounts

These 2 arrays are indexed by invoice number, and contain another array for each invoice detailing the total amount of tax for each tax rate (the indices for both variables are calibrated, so $tax_rates[$document->id][0] will contain the tax rate for the amount held in $tax_rate_amounts[$document->id][0]). Use these to display a summary of the total amount charged in tax for each tax rate that appears on the invoice (typically there will only be one tax rate, but if you have to charge a separate rate for a different item or for shipping, it is handy to have a summary). See the default template for an example of how to use these arrays.
*/