Flash Player 9 (or above) is needed to view presentations.
We have detected that you do not have it on your computer. To install it, go here.

Like this document? Why not share!

Whmcs addon module docs






Total Views
Views on SlideShare
Embed Views



0 Embeds 0

No embeds


Upload Details

Uploaded via as Adobe PDF

Usage Rights

© All Rights Reserved

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
Post Comment
Edit your comment

Whmcs addon module docs Whmcs addon module docs Document Transcript

  • WHMCS Addon Module Docs Last Updated: 7th December 2010 WHMCS | Addon Module Documentation 1
  • Contents3. Introduction4. Getting Started5. Configuration6. Activating/Deactivating7. Content/Output8. Sidebar9. Multi-Language10. Hooks11. Upgrades12. Useful Resources WHMCS | Addon Module Documentation 2
  • IntroductionAddon modules allow you to create both admin pages and hooks to extend WHMCS further.Modules can consist of just an admin page, or just hooks, or both. And they are all managedthrough the Setup > Addon Modules interface.Once activated, the modules will display in a dedicated “Addons” dropdown menu withinthe admin area for quick & easy access from any page.Management options consist of activating and deactivating of the modules, aswell as accesscontrol which allows full admins to define exactly which of the administrator roles areallowed to access each addon module.Why would I use a module for a hook?You might be asking why would I create an admin module when I could just create a hook?And the answer to that would be that creating a module provides an easy way for users toinstall and remove the addon through the dedicated addon modules WHMCS | Addon Module Documentation 3
  • Getting StartedTo get started, you need to begin by choosing a name for your module. This name should beunique among all the modules in WHMCS, and should contain only letters & numbers, alllowercase. Underscores are on the only special characters that are accepted. For example,valid names would be:mymodulenamemy_module_namemy_module_v5Once you have chosen your name, you need to create a directory and module file for it. Thedirectory should be in the format /modules/addons/your_module_name/ and then the keymodule file within it should be named “your_module_name.php”.We have created an example module file which you can use as a basis for all your custommodules to help with getting started, and that can be found at the path/modules/addons/addonexample/ within your WHMCS installation.Now let’s move onto customising the module… WHMCS | Addon Module Documentation 4
  • ConfigurationThe first step in the module is defining the configuration data. This includes the modulename, version number, author, description and any configuration fields that might beneeded. Below is an example of the config function function:function your_module_name_config() { $configarray = array( name => Friendly Display Name Here, version => 1.0, author => Your Name Here, description => Description of your Addon/Module Here, fields => array( username => array("FriendlyName" => "API Username", "Type" => "text", "Size" =>"30", ), password => array("FriendlyName" => "API Password", "Type" => "password", "Size"=> "30", ), signature => array("FriendlyName" => "API Signature", "Type" => "password", "Size"=> "50", “Description” => “You will find this in your account settings“, ), ), ); return $configarray;}The first 4 fields: name, version, author & description should all be fairly self-explanatory.These just need to contain the name you want displaying within the admin area for yourmodule, version number, your name/company 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 tomake the module work. In this example we are asking for some API related information.Supported field types are “text”, “password”, “yesno” (checkboxes), “textarea” and“dropdown”. If using the textarea option then you can add a “Rows” parameter to definethe height of the box, and if using the dropdown type, then you must specify an “Options”parameter with a comma separated list of values.There is an optional language variable you can also include if you will be using language filesfor your module - we’ll look at those in more detail later on. WHMCS | Addon Module Documentation 5
  • Activating/DeactivatingModules can contain both activate and deactivate functions which run when an admin useractivates or deactivates the module in the Addon Modules configuration area.These functions can be used to create custom tables, database entries, perform licensechecks, or anything else you need to run at the time of initial activation or final deactivation.The deactivation function should undo everything that the activation function does in orderto fully remove the module from the users system.One point to note is that there will already be an active database connection when themodule is run, so to access the WHMCS database you won’t need to reconnect to thedatabase.So for example, the activate and deactivate functions could create and drop a table for useby the custom module as below:function your_module_name_activate() { $query = "CREATE TABLE `mod_customtable` (`id` INT( 1 ) NOT NULL AUTO_INCREMENTPRIMARY KEY ,`key` VARCHAR( 16 ) NOT NULL ,`value` TEXT NOT NULL )"; mysql_query($query);}function your_module_name_deactivate() { $query = "DROP TABLE `mod_customtable`"; mysql_query($query);} WHMCS | Addon Module Documentation 6
  • Content/OutputOutput from the modules needs to be defined in the function your_module_name_outputand should be actually output, (ie. echo’d) not returned.All output will then be captured by WHMCS and displayed within the admin interfacetemplate. The module name is automatically prefixed to the output.VariablesThe output function is passed all of the fields defined in your modules config, along with thevalues users have set for them, aswell as a “modulelink” variable which you can use to linkback to the module.Linking/ActionsUsing the modulelink variable passed into the output function, you can then create links andforms that post back to your module. The modulelink will be in the format“addonmodules.php?module=xxxxxx” so for links you can then append “&var1=x&var2=y”or with forms you can use the POST form method to receive user input.Within the output function you can then check the $_GET or $_POST variables received inthe request in order to display other output or perform various tasks once links have beenfollowed.Admin User DataYou can access the currently logged in admin ID should you need that within your moduleusing $_SESSION[‘adminid’] and from that can lookup any additional information you needin tbladmins.Examplefunction your_module_name_output($vars) { $modulelink = $vars[modulelink]; $username = $vars[username]; $password = $vars[password]; echo <p>Your username is .$username.</p>;} WHMCS | Addon Module Documentation 7
  • SidebarAn addon module can also define HTML code to be displayed in the sidebar. You can doanything you want with this, but it is ideal for creating custom sub menus specific to acustom module.The function is passed all the same variables as the main content output function, and socan be used like this:function your_module_name_sidebar($vars) { $modulelink = $vars[modulelink]; $username = $vars[username]; $password = $vars[password]; $sidebar = <span class="header"><img src="images/icons/addonmodules.png"class="absmiddle" width="16" height="16" /> Sample</span><ul class="menu"> <li><a href="#">Sample Sidebar Link 1</a></li> <li><a href="#">Sample Sidebar Link 2</a></li> </ul>; return $sidebar;} WHMCS | Addon Module Documentation 8
  • Multi-LanguageModules can be designed to support multiple languages should you wish.For this, the addon module simply needs a lang subfolder creating within it, and within thatlanguage files can be created matching the names of the main WHMCS admin area languagefiles located in the /admin/lang/ folder.The language variables for custom modules are kept separate in language files within themodule’s own folder to make installation and updating easier.If language files exist, WHMCS will then automatically load these whenever the custommodule is accessed, automatically selecting the appropriate language file based on thecurrently logged in administrators language profile setting. If no matching language fileexists within the custom module’s folder for the language the admin is using then it willsimply fall back to the default language you set in the module’s config array.The language variables are then passed into both the _output and _sidebar functionsvariables array using “_lang”.Please refer to the example addon modules language file located in/modules/addons/addonexample/lang/english.php for the format to use for your customlanguage variables.Below is a demonstration of how you specify the default language for your module in theconfig array.function your_module_name_config() { $configarray = array( name => Friendly Display Name Here, version => 1.0, author => Your Name Here, description => Description of your Addon/Module Here, language => english, fields => array(etc… WHMCS | Addon Module Documentation 9
  • HooksTo create hooks that your module should define within WHMCS, you simply need to createa file named “hooks.php” within your custom module folder, and that will then beautomatically detected and any hooks 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 http://wiki.whmcs.com/Hooks for more information on creating hooks. WHMCS | Addon Module Documentation 10
  • UpgradesReleasing updates and upgrades to your custom modules is likely something you will wantto do at some point in time. And if those require modifying the database structure orperforming other functions that would otherwise be performed in the _activate functionwhen being activated for the first time, then you need some way of handling that.With the Addon Modules system, this is a breeze with the upgrade function. The upgradefunction is called the first time a module is accessed following an update. The update isdetected by a change of version number in the _config array of the module, and so if achange is detected, the _upgrade function will be called. The upgrade function is passed theprevious version number so that you can then decide what updates you need to run withinthat function to bring it up to date with your latest version.An example of how this function can be used is demonstrated below:function your_module_name_upgrade($vars) { $version = $vars[version]; if ($version=="1.0") { $query = "ALTER TABLE mod_customtable ADD extrafield TEXT NOT NULL;"; mysql_query($query); }} WHMCS | Addon Module Documentation 11
  • Useful ResourcesHere are some code samples for how to match the styles of WHMCS within your customcode.Data TableUsed to output a table of data<div class="tablebg"><table class="datatable" width="100%" border="0" cellspacing="1" cellpadding="3"><tr><th>Col 1</th><th>Col 2</th><th>Col 3</th></tr><tr><td>Data Row 1</td><td>Data Row 1</td><td>Data Row 1</td></tr><tr><td>Data Row 2</td><td>Data Row 2</td><td>Data Row 2</td></tr></table></div>Fields TableUsed to output form fields<table class="form" width="100%" border="0" cellspacing="2" cellpadding="3"><tr><td width="20%" class="fieldlabel">Field Name 1</td><td class="fieldarea">FieldContents</td></tr><tr><td class="fieldlabel">Field Name 2</td><td class="fieldarea">Field Contents</td></tr></table> WHMCS | Addon Module Documentation 12