Third party developers can write extensions that integrate with the nBill administration control panel. There are various files that would typically be included in an extension. It would also usually require one or more database tables, and one or more additional menu items on the nBill main menu (in most cases it is best to make new menu options appear under the 'Extensions' menu).

In order to integrate your extension with nBill, it is necessary to follow the correct naming convention with your files, and construct an appropriate install file to allow the extension to be installed using the nBill extension installer (this will copy the files to the correct location, run any database queries you require, and insert any new menu items you require). The different types of file that are typically contained in an nBill extension are explained below, but you do not have to have all of these files, and you could add further files of your own (eg. if you want to refer to a library of functions).

Let's suppose you want to create a new audit log extension for example, to record information about all of the activity that occurs within nBill, and allow the administrator to view the event log. We will call the extension 'audit_log'.

Main Control File - /admin.proc/<extension>.php
The main control file should be named audit_log.php and placed in a folder called admin.proc. This is the file that will be executed when the user clicks on the link to the audit log in the nBill control panel.

Presentation File - /admin.html/<extension>.html.php
The presentation file should be named audit_log.html.php, and this should be used to construct the HTML to output. The presentation file should be placed in a folder called admin.html.

Language File - /language/<language>/<extension>.<language>.php
Your language file would be named audit_log.en-GB.php (assuming you are writing in English), and this would go in a folder named en-GB (or whatever language you are writing in - you can create multiple language folders/files if required), which in turn would be placed in a folder named language.

Front End Control File - /proc/<extension>.php
Front End Presentation File - html/<extension>.html.php
In this example, we do not really need any functionality in the website front-end, but if required, a /proc/audit_log.php and /html/audit_log.html.php file could be added.

Install File - /extensions/<extension>.install.php
Uninstall File - /extensions/<extension>.uninstall.php
For any processing that needs to be carried out immediately after the extension is installed, you could create a file named audit_log.install.php and place it in a folder called extensions. Likewise, for any processing that needs to be carried out immediately before uninstalling the extension, you could create a file named audit_log.uninstall.php in the same folder.

Event Files - /events/<event>/<extension>_<event>.php
In order to capture information about activity within nBill, the audit log extension would also require a file for each nBill event that you want to capture. That way, when the event is fired, the extension would be able to record details about the activity in its database table, which can then be reported on in the back end. In this example, we will assume you just want to record activity from the record_updated event, but you could add a file for every event if you want. The file name does not matter, but place each file in a folder according to the name of the nBill event, and place all of those folders in a parent folder called events.

Other Files
You can add other files if you wish, for example you would typically have an image file for the menu item icon, and you might want to include a library of classes or functions. Menu item images should be placed in a folder named /images/icons/ and library or other files can be placed in the /extensions/ folder.

Installation File
In order to actually install the extension with the nBill extension installer, you need to have a file in the root folder with a .nbe (nBill Extension) file extension. This is just a plain text file - the contents of it will be explained later.

So now, our file structure looks something like this:

audit_log (ie. some location on your computer)
  |-- admin.html
  |     |
  |     |-- audit_log.html.php
  |-- admin.proc
  |     |
  |     |-- audit_log.php
  |-- events
  |     |
  |     |-- record_updated
  |            |
  |            |-- audit_log_record_updated.php
  |-- extensions
  |      |
  |      |-- audit_log.install.php
  |      |-- audit_log.uninstall.php
  |-- html
  |     |
  |     |-- audit_log.html.php
  |-- images
  |     |
  |     |-- icons
  |           |
  |           |-- audit_log.gif
  |-- language
  |      |
  |      |-- en-GB
  |             |
  |             |-- audit_log.en-GB.php
  |-- proc
  |     |
  |     |-- audit_log.php
  |-- extension_audit_log.nbe
In reality you would probably not need all of these files (eg. in this audit log example there would not likely be any need for any front-end functionality, so /proc/audit_log.php and /html/audit_log.html.php would not be required).

Now to create the installation file that will copy these files to the right places on the target system, run any database queries, and insert a new menu item in the nBill control panel. As noted above, this is just a text file with a .nbe extension - in this example, we are calling it extension_audit_log.nbe.

The .nbe file contains various settings, in the format key=value, each on a separate line. If you want to break a value onto more than one line, you can enclose it in square braces. Comments can be included anywhere in the file by using either a hash symbol (#) or two forward slashes (//). Anything that follows a hash or two slashes will be ignored by the installer. If you need to use a hash or double slash in your data (eg. if you want to use the #__prefix for creating a new database table using the existing database table prefix), you must 'escape' the hash by inserting a backslash before it, like this: \#

Here is a sample nBill feature extension installation file containing comments about what entries you can include:


# This is a sample install file for an nBill Feature extension - replace any values with your own as indicated
# In all cases where you see <extension_name>, replace it with your actual extension name!
# Lines that start with a hash (#) or double slash (//) or that are blank, will be ignored by the installer
# If you need to use a hash or double slash in the data, prefix with a backslash escape character (eg. \// or \#)
# Always start a new setting on a new line.
# If you want a line break within a setting, surround the setting value with square brackets
# When you publish your extension, you can delete these comment lines from the top of the file!
# You MUST use the correct file naming convention for your feature extension to work correctly.
# Typically this consists of the following files:
# admin.proc/<extension_name>.php //Back end processing file
# admin.html/<extension_name>.html.php //Back end output file
# language/en-GB/<extension_name>.en-GB.php //Repeated for as many languages as your extension supports
# proc/<extension_name>.php //Front end processing file
# html/<extension_name>.html.php //Front end output file

# The following directive tells the installer whether or not to convert the files in this extension to UTF-8.
# If your files are encoded as ISO-8559-1 (this is usually the default for text editors, so they probably are),
# some CMSs (eg. Joomla 1.5, Mambo 4.6) will require them to be converted to UTF-8. Other CMSs may prefer them
# to be kept as ISO-8559-1, or the user might be able to choose. If the files are NOT encoded using ISO-8559-1,
# you must set this option to C (Don't Convert), as the conversion process will not work with any other encoding.
# In most cases though, it is necessary to set this option to A.
# Valid values for this directive are:
# A = Convert if required by CMS
# B = Convert always
# C = Don't Convert


#Minimum version of nBill on which this extension installation will work

# The name is used for the folder name, so no spaces or punctuation allowed:

# The title is used as the human-readable display value:
title=***Enter Pretty Name Here***

author=***Enter your own name or company name here***

date=***Enter date of this release***

copyright=***Any copyright message***

license=***Licensing information goes here***

author_email=***Contact e-mail address***


version=***Version number of this extension***

description=***Constant that contains the extension description***

file=***Front-end file (eg. proc/<extension_name>.php)***

file=***Another front-end file (eg. html/<extension_name>.html.php)***

admin_file=***Back-end processing file (eg. admin.proc/<extension_name>.php)***

admin_file=***Back-end output file (eg. admin.html/<extension_name>.html.php)***

admin_file=***Back-end Language file (eg. language/en-GB/<extension_name>.en-GB.php)***

# If you want to run some code after installation, include an install file - it MUST be named as indicated below

# If you want to run some code after uninstallation, include an uninstall file - it MUST be named as indicated below

# If you want to add a menu item to the back-end, add a line for each menu item. It is recommended
# to place your menu items under the 'Extensions' menu (so that it is clear to the user what is
# part of the nBill core and what is a 3rd party extension), however, you may add your menu items
# wherever you like - at the top level, or as a child of any existing menu item. You MUST specify the
# following key/value pairs when defining a menu item:
# extension_menu (a string key to identify the menu item - make sure you use something unique that no other extension is likely to clash with
# parent_id (if this is a child of another menu item you have defined, enter the parent key here. Otherwise, you MUST enter "-1" [without quotes])
# main_menu_parent_id (enter the numeric id of the menu item on the main menu that you want this to be a child of, or "-1" if it is a child of another menu item in this extension.
# ordering (enter the numerical position you want this menu item to have in relation to its siblings - if more than one item has the same position, the ordering between them will be random)
# text (you can enter either a hard-coded text value, or a constant name - if using a constant, ensure a value is defined for it in your extension's language file)
# published (either 0 [unpublished] or 1 [published] - in virtually every case you should use a value of 1!
# NOTE: if both parent_id and main_menu_parent_id are set to -1, the menu item will appear at the very top level - ie. on the nBill menu bar itself
# In addition to the above 6 mandatory settings (extension_menu, parent_id, main_menu_parent_id, ordering, text, published),
# you can also specify the following optional settings:
# description (text shown in status bar when mouse is hovered over the menu item)
# image (relative path to the image you want to see at the side of the menu item [include the image file in your extension package])
# url (where you want the menu item to link to).
# For example:

# Repeat for as many menu items as you want to add...

# If you want to run an additional database query, you can define it like this:
query=[***Enter your SQL here, on multiple lines if you like***]

# If the database changes you make by running additional queries, above, can be undone by running another query,
# enter the query here (undo queries will be run if the installation fails or when the extension is uninstalled)
undo_query=[***Enter your SQL here, on multiple lines if you like***]

Comments in the file are completely optional, as they are ignored by the installer. So for our example with the audit log extension, the installation file might look something like this:

title=Audit Log
author=Russell Walker, Netshine Software Limited
date=January 2019
copyright=(c)2019 Netshine Software Limited. All rights Reserved.
license=You can use this as the basis for your own feature extension.
author_email=This email address is being protected from spambots. You need JavaScript enabled to view it.
description=NBILL_AUDIT_LOG_DESC //This is a constant that will be defined in the language file.
query=[CREATE TABLE `\#__nbill_ext_audit_log` (
  `timestamp` int(11) NOT NULL default '0',
  `log_data` text NOT NULL default '',
  PRIMARY KEY  (`id`)
undo_query=DROP TABLE `\#__nbill_ext_audit_log`;

Then all you have to do is zip up all of your files in the structure defined above, and you can then use the nBill extension installer to upload and install the zip file. Of course, you will also need to write some code to do the work!