Invoice customisation with JavaScript

The Banana invoice is constructed with a Javascript program. The Extension also allows you to add Javascript programming so that you can completely customize the content and format of the invoice (this functionality requires the Advanced plan).

See more about Banana Accounting API Extensions Reference.

Add your custom Javascript file

Three steps are required to define and use your Javascript file:

1. Add the document table to the Banana Accounting file.
   If it is not already present you need to add the Documents table in the Banana document with the menu command Tools > Add new features > Add document table.
2. Add a new Javascript type document to the document table.
   1. In the ID column enter the file name including the extension .js (e.g. "myFile.js").
      If the id is missing the ".js" at the end, it won't work.
   2. In the Description column enter a comment (optional).
   3. In the Attachments column, double click on the cell or select the edit symbol, then select Javascript Code and confirm with OK.
   4. An editor will open in which you can write the code.
   5. Delete everything in it.
   6. Insert the Javascript code. You can modify the content at any time.
      
      
      Documents table - Javascript Code attachment
       
3. Tell the invoice layout to use the customized Javascript attachment file.
   1. Select Settings of the Print invoices dialogue.
   2. In the Javascript/CSS > JS file name, enter the name of the newly created Javascript attachment file with the extension ".js" at the end (e.g. "myFile.js").
   3. Click Ok to confirm.
      
      
      Settings Dialogue - Javascript File Property

Javascript Hook Replacement Functions

The invoice layout is created with a set of predefined Javascript functions.

The hook functions are Javascript replacements functions to be used instead of the the predefined.

The hook functions should be defined in the ".js" file of the Documents table.

• The name of the hook function is the name of the predefined function used in the layout, preceded by the text "hook_".
  For example, if you want to change the header printing you have to define the hook_print_header() that will replace the predefined print_header() function.
  • The parameters must be the same as those used in the main function.
  • If you create your own hook function, it is necessary to know how it works the function you want to replaces.
• When generating the invoice, the layout extension checks for the existence of a hook replacement function and, if available, utilizes it to substitute the predefined function.
• Hook functions let you selectively change some part of how the invoice is build, without directly modifying the original script of the invoice Layout.

Graphic explanation of the Hook functions

With the hook functions, you can customize the following sections of the invoice.

(1) hook_print_header()

Function that prints the header part of the invoice (logo and texts).

(2) hook_print_info_first_page() and hook_print_info_other_pages()

Functions that print the information parts of the invoice.

(3) hook_print_customer_address()

Function that prints the customer address part of the invoice.

(4) hook_print_shipping_address()

Function that prints the shipping address part of the invoice (in case it exists).

(5) hook_print_text_begin()

Function that prints the title and begin text parts of the invoice.

(6) hook_print_details_net_amounts() and hook_print_details_gross_amounts()

Functions that print the invoice details using net/gross amounts.
Use the hook_formatItemsValue() function to change the format and style of the items.

(7) hook_print_final_texts()

Function that prints the final texts, notes and greetings parts of the invoice, right after the invoice details.

(8) hook_print_footer()

Function that prints the footer at the bottom of the page (usable only when not printing the QR slip).

List of Hook functions

This file contains all the available hook functions with their parameters and an empty function body, that should be replaced with your implementation. 

• See examples of invoice customization.
   

// Function used to set all the variable values used by the invoice layout script
function hook_set_variables(variables, userParam) {...}
// Function used to print the header at the top of the page (logo and text address)
function hook_print_header(repDocObj, userParam, repStyleObj, invoiceObj, texts) {...}
// Function used to print the invoice information on the first page
function hook_print_info_first_page(repDocObj, invoiceObj, texts, userParam) {...}
// Function used to print the invoice information from page 2 onward
function hook_print_info_other_pages(repDocObj, invoiceObj, texts, userParam) {...}
// Function used to print the customer address
function hook_print_customer_address(repDocObj, invoiceObj, userParam) {...}
// Function used to print the shipping address
function hook_print_shipping_address(repDocObj, invoiceObj, texts, userParam) {...}
// Function used to print the text before the invoice details (title and begin text)
function hook_print_text_begin(repDocObj, invoiceObj, texts, userParam) {...}
// Function used to print the invoice details using net amounts (VAT excluded)
function hook_print_details_net_amounts(banDoc, repDocObj, invoiceObj, texts, userParam, detailsTable, variables) {...}
// Function used to print the invoice details using gross amounts (VAT included)
function hook_print_details_gross_amounts(banDoc, repDocObj, invoiceObj, texts, userParam, detailsTable, variables) {...}
// Function used to print the text after the invoice details (notes, greetings, etc.)
function hook_print_final_texts(repDocObj, invoiceObj, userParam) {...}
// Function used to print the footer at the bottom of the page. Usable only when not printing the QR slip part.
function hook_print_footer(repDocObj, texts, userParam) {...}
// Function used to format the value and set the className of the item
function hook_formatItemsValue(value, variables, columnName, className, item) {...}
// Function used to modify the QR settings
function hook_modify_settings_qr(invoiceObj, qrcodeData) {...}

Examples of a hook functions 

Within your hook function you can call the original hook function. This way you can limit the changes to the code.
For example this hook function call the original one, only in a specific case.

/** 
 * This function prints the final text only for INVOICES and not for CREDIT NOTES.
 * Invoices = DocType 10
 * Credit notes = DocType 12
 */
function hook_print_final_texts(sectionClassFinalTexts, invoiceObj, userParam) {
   // We can check the DocType and print the text only when is not 12
   if (invoiceObj.document_info.doc_type !== "12") {
      print_final_texts(sectionClassFinalTexts, invoiceObj, userParam);
   }
}

Predefined variables

The predefined variables are the default used by the invoice layout script.

The variables for decimals start with "decimals_". (decimals_quantity, decimals_unit_price, decimals_amounts).

The variable that start with "$" are template variable that you can use in the CSS styles ($font_family, $font_size, $text_color, ...).
Example of an extract of the predefined CSS invoice layout.

body {
  font-family: $font_family;
  font-size: $font_size;
  color: $text_color;
}

List of all predefined variables and their default values that you can override with the hook_set_variables() function:

/* Variable that sets the decimals of the Quantity column */
variables.decimals_quantity = "";
/* Variable that sets the decimals of the Unit Price column */
variables.decimals_unit_price = 2;
/* Variable that sets the decimals of the Amount column */
variables.decimals_amounts = 2;
/* Variables that set the colors */
variables.$text_color = userParam.text_color;
variables.$background_color_details_header = userParam.background_color_details_header;
variables.$text_color_details_header = userParam.text_color_details_header;
variables.$background_color_alternate_lines = userParam.background_color_alternate_lines;
variables.$color_title_total = userParam.color_title_total;
/* Variables that set the font */
variables.$font_family = userParam.font_family;
variables.$font_size = userParam.font_size+"pt";
/* Variables that set the font size and margins of the Invoice Begin Text */
variables.$font_size_title = userParam.font_size*1.4 +"pt";
/* Variables that set font size, margins, padding and borders of the Invoice Details */
variables.$font_size_header = userParam.font_size*1.2 +"pt";
variables.$font_size_total = userParam.font_size*1.2 +"pt";
/* Variables that set the position of the invoice address
 * Default margins when the address on right: 12.3cm margin left, 4.5cm margin top
 * Default margins when the address on left: 2.2cm margin left, 5.5cm margin top
 * Sum userParam dX and dY adjustments to default values */
variables.$right_address_margin_left = parseFloat(12.3) + parseFloat(userParam.address_position_dX)+"cm";
variables.$right_address_margin_top = parseFloat(4.5) + parseFloat(userParam.address_position_dY)+"cm";
variables.$left_address_margin_left = parseFloat(2.2) + parseFloat(userParam.address_position_dX)+"cm";
variables.$left_address_margin_top = parseFloat(5.5) + parseFloat(userParam.address_position_dY)+"cm"; 

Example of 'hook_set_variables' function

You can overwrite the predefined variable with the hook_set_variables() function. 
Only use the variable that you want to replace. 

// Example of hook function usage that sets
// the decimals of the Amounts columns to 4
// the font type to Times New Roman
function hook_set_variables(variables, userParam) {
   variables.decimals_amounts = 4;
   variables.$font_family = "Times New Roman";
}