Revision as of 06:47, 21 April 2016

Addon modules allow you to create both admin pages and hooks to extend WHMCS further.

Addon Modules can consist of just an admin page, just hooks, or both. They are all managed through the Setup > Addon Modules interface.

There are other types of module in WHMCS. These are Payment Gateways, Provisioning Modules and Registrar Modules.

Once activated, modules will display in the "Addons" menu within the admin area for access from any page.

Management options consist of activating and deactivating of the modules. Access control allows full admins to define which of the administrator roles can access each addon module.

We have a Video Tutorial demonstrating addon module management & access control @ http://www.whmcs.com/get-support/video-tutorials/#prettyPhoto/15/

Getting Started

To get started, you need to begin by choosing a name for your module. The module name chosen must be unique and should be all lowercase. The name must only contain letters & numbers whilst always starting with a letter. Underscore is the only accepted special character. For example, valid names would be:

mymodulename OR my_module_name OR my_module

Once you have chosen your name, you need to create a directory and module file for it. Addon modules are found in the /modules/addons/ directory. Each module can be found within it's own directory /your_module_name/. Then the core module file within it should be “your_module_name.php” to match the folder.

Configuration

The first step in the module is defining the configuration data. This includes the module name, version number, author, description. Also, this contains any custom configuration fields. Below is an example of the config function function:

function demo_config() {
    $configarray = array(
    "name" => "Addon Example",
    "description" => "This is a sample config function for an addon module",
    "version" => "1.0",
    "author" => "WHMCS",
    "fields" => array(
        "option1" => array ("FriendlyName" => "Option1", "Type" => "text", "Size" => "25",
                              "Description" => "Textbox", "Default" => "Example", ),
        "option2" => array ("FriendlyName" => "Option2", "Type" => "password", "Size" => "25",
                              "Description" => "Password", ),
        "option3" => array ("FriendlyName" => "Option3", "Type" => "yesno", "Size" => "25",
                              "Description" => "Sample Check Box", ),
        "option4" => array ("FriendlyName" => "Option4", "Type" => "dropdown", "Options" =>
                              "1,2,3,4,5", "Description" => "Sample Dropdown", "Default" => "3", ),
        "option5" => array ("FriendlyName" => "Option5", "Type" => "radio", "Options" =>
                              "Demo1,Demo2,Demo3", "Description" => "Radio Options Demo", ),
        "option6" => array ("FriendlyName" => "Option6", "Type" => "textarea", "Rows" => "3",
                              "Cols" => "50", "Description" => "Description goes here", "Default" => "Test", ),
    ));
    return $configarray;
}

The first 4 fields: name, version, author & description should all be self-explanatory. These contain the display name for the module which will show within the admin area. Also, the version number, name/company of the creator, and a brief description of the addon.

The fields section is where you can define the input you need from end users to be able to make the module work. In this example we are asking for some API related information. Supported field types are “text”, “password”, “yesno” (checkboxes), “textarea”, “dropdown” and “radio”. If using the textarea option, a “Rows” parameter is used to show the height of the box. If using the dropdown type, then you must provide an “Options” parameter with comma separated values.

There is a language variable you can also include if you will be using language files for your module. We’ll look at languages in more detail later on.

Installation & Uninstallation

Modules can contain both activate and deactivate functions. These functions run when an admin user activates or deactivates the module in the Addon Modules configuration area.

These functions can be used run any code required when activating or deactivating the module. For example, to create custom tables, database entries, or perform license checks. They can also be used to return messages, or errors to a user. So, if you want to fail the process due to a problem, or want to notify the user of a missing requirement or license issue.

The deactivation function should undo everything that the activation function does to remove the module from the users system.

There will already be an active database connection when the module is run, so to access the WHMCS database you won’t need to reconnect to the database.

For example, the activate and deactivate functions could create and drop a table for use by the custom module as below:

function demo_activate() {

    # Create Custom DB Table
    $query = "CREATE TABLE `mod_addonexample` (`id` INT( 1 ) NOT NULL AUTO_INCREMENT ... ";
	$result = mysql_query($query);

    # Return Result
    return array('status'=>'success','description'=>'This is an demo module only. In a real
           module you might instruct a user how to get started with it here...');
    return array('status'=>'error','description'=>'You can use the error status return to
           indicate there was a problem activating the module');
    return array('status'=>'info','description'=>'You can use the info status return to display
           a message to the user');

}

function demo_deactivate() {

    # Remove Custom DB Table
    $query = "DROP TABLE `mod_addonexample`";
	$result = mysql_query($query);

    # Return Result
    return array('status'=>'success','description'=>'If successful, you can return a message
           to show the user here');
    return array('status'=>'error','description'=>'If an error occurs you can return an error
           message for display here');
    return array('status'=>'info','description'=>'If you want to give an info message to a user
           you can return it here');

}

Admin Area Content/Output

The output from modules is defined in the function your_module_name_output. This should be actually output (i.e. echo’d) not returned. All output is captured by WHMCS and displayed within the admin interface template. The module name/title is prefixed to the output.

Variables

The output function is passing all the fields defined in your modules config, along with the values users have set for them, as well as a “modulelink” variable which you can use to link back to the module.

Linking/Actions

Using the modulelink variable passed into the output function, you can then create links and forms that post back to your module. The modulelink will be in the format “addonmodules.php?module=xxxxxx”. For links you can then append “&var1=x&var2=y”. For forms, use the POST form method to receive user input.

Within the output function, the $_GET or $_POST variables can be checked. This can be used to display other output or perform various tasks, once links have been followed.

Admin User Data

To access the currently logged in admin ID should the module need that, in the session, use $_SESSION[‘adminid’]. From that, the module can find any extra information you need in tbladmins.

Example

function demo_output($vars) {

    $modulelink = $vars['modulelink'];
    $version = $vars['version'];
    $option1 = $vars['option1'];
    $option2 = $vars['option2'];
    $option3 = $vars['option3'];
    $option4 = $vars['option4'];
    $option5 = $vars['option5'];
    $option6 = $vars['option6'];
    $LANG = $vars['_lang'];

    echo '<p>The date & time are currently '.date("Y-m-d H:i:s").'</p>';

}

Things aren't of course limited to just one file. Use the _output function to include other files, call templates, etc. The system is flexible.

Client Area Output

Addon Modules also support generating client area output. This is done with the use of an _clientarea function within the module.

The functionality allows for modules to return output in the form of template files. The template files are stored within the module folder.

You can return a page title, breadcrumb path, and template variables. You can also require a client login with a simple true/false response. Language strings from the modules language file (see below) are also available.

Access Client area modules using an URL in the format index.php?m=modulename

Here is a sample client area function demonstrating all the available return variables:

function demo_clientarea($vars) {

    $modulelink = $vars['modulelink'];
    $version = $vars['version'];
    $option1 = $vars['option1'];
    $option2 = $vars['option2'];
    $option3 = $vars['option3'];
    $option4 = $vars['option4'];
    $option5 = $vars['option5'];
    $option6 = $vars['option6'];
    $LANG = $vars['_lang'];

    return array(
        'pagetitle' => 'Addon Module',
        'breadcrumb' => array('index.php?m=demo'=>'Demo Addon'),
        'templatefile' => 'clienthome',
        'requirelogin' => true, # or false
        'vars' => array(
            'testvar' => 'demo',
            'anothervar' => 'value',
            'sample' => 'test',
        ),
    );

}

The above assumes a template, clienthome.tpl, existing within the module folder to use for the output.

Multi-Language

Modules can support multiple languages should you wish.

For this, the addon module needs a lang subfolder created within it. Within that, language files can be created matching the names of the main WHMCS admin area language files. The admin language files are located in the /admin/lang/ folder.

WHMCS has the language variables for custom modules separate to make installation and updating easier.

If language files exist, WHMCS will then load these whenever the custom module is accessed. WHMCS will select the appropriate language file based on the current administrators language setting. If no matching language file exists within the module folder, it will fall back to the default language set in the module’s config array.

A language file would be located at /modules/addons/youraddonname/lang/english.php

<?php
$_ADDONLANG['intro'] = "This is an example module to be used as a starting point for developers.";
$_ADDONLANG['description'] = "Creating an addon module is easy and this example demonstrates all the functionality an addon module can utilise.<br /><br />Addon modules offer the ultimate flexibility allowing you to create anything from a simple extra admin area page, to advanced fully custom modules interfacing with remote third party systems and hooking into & extending the core system.";
$_ADDONLANG['documentation'] = "This file is not protected so you can have a look at

The language variables are then passed into the _output and _sidebar functions array using “_lang”.

Below is a demonstration of how you specify the default language for your module in the config array.

function demo_config() {
    $configarray = array(
    "name" => "Addon Example",
    "description" => "This is a sample config function for an addon module",
    "version" => "1.0",
    "author" => "WHMCS",
    "language" => "english",
    "fields" => etc...

Hooks

Hooks that the module should define within WHMCS are defined in a file named “hooks.php”. This should be within your custom module folder. That will then become detected and any hooks that exist will be loaded on every page of WHMCS.

The hook functions within that file should be defined in exactly the same way as normal.

Please refer to Hook Documentation for more info on creating and working with hooks in WHMCS.

Upgrades

Releasing updates and upgrades to custom modules is likely something that is needed to be done at some point. If those modules need to modify the database structure or perform other functions that would be handled in the _activate function, then you need some way of handling that.

With the Addon Modules system, this is a breeze with the upgrade function. The upgrade function is called the first time a module is accessed following an update. The update is detected by a change of version number in the _config array of the module. The upgrade function is passed the previous version number so that the module can then decide what updates to run within that function. This allows the module to bring it up to date with your latest version.

An example of how this function can be used is demonstrated below:

function demo_upgrade($vars) {

    $version = $vars['version'];

    # Run SQL Updates for V1.0 to V1.1
    if ($version < 1.1) {
        $query = "ALTER `mod_addonexample` ADD `demo2` TEXT NOT NULL ";
    	$result = mysql_query($query);
    }

    # Run SQL Updates for V1.1 to V1.2
    if ($version < 1.2) {
        $query = "ALTER `mod_addonexample` ADD `demo3` TEXT NOT NULL ";
    	$result = mysql_query($query);
    }

}

WHMCS Marketplace

WHMCS offers a Marketplace which accepts submission of the completed module. Displayed listed are found under the Addons tab within the administration area and online at http://marketplace.whmcs.com . This is a great way to make WHMCS users aware of the module.

For help using the Marketplace please refer to https://marketplace.whmcs.com/help . We aim to review submissions in 1-2 weeks.