|
|
| (12 intermediate revisions by 4 users not shown) |
| Line 1: |
Line 1: |
| − | '''Provisioning Modules''', also referred to as '''Product or Server Modules''', allow you to create modules to allow for the provisioning and management of products & services in WHMCS.
| + | This page has moved to https://developers.whmcs.com/provisioning-modules/ |
| − | | |
| − | The core functionality of a module is for creating, suspending, unsuspending & terminating of products as various events occur such as new orders being paid for, items becoming overdue, overdue invoices being paid & cancellations being requested. But a module in WHMCS can do much more than just that, including automated password resets, upgrades/downgrades, renewals, admin based links, client area output, and more via custom functions.
| |
| − | | |
| − | {{Developer_Links}}
| |
| − | | |
| − | | |
| − | Other types of modules that can be created in WHMCS are [[Gateway Module Developer Docs|Payment Gateways]], [[Registrar Module Developer Docs|Domain Registrars]] and [[Addon Module Developer Docs|Addons]].
| |
| − | | |
| − | ==Getting Started==
| |
| − | | |
| − | Begin by downloading the Provisioning Module Template file for sample code to refer to here: https://github.com/WHMCS/sample-provisioning-module
| |
| − | | |
| − | ===Naming Conventions===
| |
| − | | |
| − | Provisioning Modules are stored in the '''/modules/servers/''' directory. The module name you choose must be unique, and should be all lowercase, containing only letters & numbers, always starting with a letter.
| |
| − | | |
| − | Within the module itself, all functions must then be prefixed with the module filename, followed by an underscore, and then the function name. For example if your module was called "mymodule" the create function would be named "mymodule_CreateAccount".
| |
| − | | |
| − | ===Product Configuration Options===
| |
| − | | |
| − | The required function of all provisioning modules is the ConfigOptions function. This is what defines the settings that can be configured on a per product basis when assigning a product to the module. The name of this function must be '''mymodule_ConfigOptions''' matching the name of your module.
| |
| − | | |
| − | The supported field types are '''Text, Password, Yes/No Checkboxes, Dropdown Menus, Radio Buttons & Text Areas'''
| |
| − | | |
| − | Below are examples of the available parameters for each field type. Provisioning modules support up to 24 options defined in this way.
| |
| − | | |
| − | <source lang="php">
| |
| − | $configarray = array(
| |
| − | "username" => array (
| |
| − | "FriendlyName" => "UserName",
| |
| − | "Type" => "text", # Text Box
| |
| − | "Size" => "25", # Defines the Field Width
| |
| − | "Description" => "Textbox",
| |
| − | "Default" => "Example",
| |
| − | ),
| |
| − | "password" => array (
| |
| − | "FriendlyName" => "Password",
| |
| − | "Type" => "password", # Password Field
| |
| − | "Size" => "25", # Defines the Field Width
| |
| − | "Description" => "Password",
| |
| − | "Default" => "Example",
| |
| − | ),
| |
| − | "usessl" => array (
| |
| − | "FriendlyName" => "Enable SSL",
| |
| − | "Type" => "yesno", # Yes/No Checkbox
| |
| − | "Description" => "Tick to use secure connections",
| |
| − | ),
| |
| − | "package" => array (
| |
| − | "FriendlyName" => "Package Name",
| |
| − | "Type" => "dropdown", # Dropdown Choice of Options
| |
| − | "Options" => "Starter,Advanced,Ultimate",
| |
| − | "Description" => "Sample Dropdown",
| |
| − | "Default" => "Advanced",
| |
| − | ),
| |
| − | "disk" => array (
| |
| − | "FriendlyName" => "Disk Space",
| |
| − | "Type" => "radio", # Radio Selection of Options
| |
| − | "Options" => "100MB,200MB,300MB",
| |
| − | "Description" => "Radio Options Demo",
| |
| − | "Default" => "200MB",
| |
| − | ),
| |
| − | "comments" => array (
| |
| − | "FriendlyName" => "Notes",
| |
| − | "Type" => "textarea", # Textarea
| |
| − | "Rows" => "3", # Number of Rows
| |
| − | "Cols" => "50", # Number of Columns
| |
| − | "Description" => "Description goes here",
| |
| − | "Default" => "Enter notes here",
| |
| − | ),
| |
| − | );
| |
| − | return $configarray;
| |
| − | </source>
| |
| − | | |
| − | ==Supported Functions==
| |
| − | | |
| − | What follows here is a brief overview of all the possible functions that a product provisioning module in WHMCS can contain. All functions within a module are optional and can be omitted from the module if they don’t apply. Remember, within the code itself, all functions are prefixed with the module filename, followed by an underscore, and then the function name as shown in bold in these descriptions.
| |
| − | | |
| − | *'''CreateAccount''' - This function is called when a new product is due to be provisioned. This can be invoked automatically by WHMCS upon checkout or payment for a new order, or manually by an admin user from the Products/Services tab under a clients profile within the admin area.
| |
| − | *'''SuspendAccount''' - This function is called when a suspension is requested. This is invoked automatically by WHMCS when a product becomes overdue on payment, or can be called manually by admin user.
| |
| − | *'''UnsuspendAccount''' - This function is called when an unsuspension is requested. This is invoked automatically upon payment of an overdue invoice for a product.
| |
| − | *'''TerminateAccount''' - This function is called when a termination is requested. This can be invoked automatically for long overdue products if enabled (auto termination is disabled by default in Setup > Automation Settings) or requested manually by an admin user.
| |
| − | *'''Renew''' - This function is called each time a renewal invoice for a product is paid.
| |
| − | *'''ChangePassword''' - This function is called when a client requests a password change from the client area. For this option to show up this function must be declared in the module, the status of the product must be active. Admins can also invoke this command from the admin area.
| |
| − | *'''ChangePackage''' - This function is used for upgrading and downgrading of products. This function will be called automatically when an upgrade or downgrade order placed by the client is paid for, or can be invoked manually by admin users from the product management pages. This same function is called for upgrades and downgrades of both products and configurable options.
| |
| − | *'''ClientArea''' - This function can be used to define module specific client area output. It accepts a return of HTML for display on the product details page of the client area. The output can alternatively be specified via a template file within the module folder named “clientarea.tpl” to allow for end user customisation. This function is discussed in more detail later on in the docs.
| |
| − | *'''AdminArea''' - This function is used to define HTML code to be displayed within the admin area server configuration page (Setup > Servers) and is commonly used to provide an automated shortcut/login link to the server control panel being integrated with.
| |
| − | *'''LoginLink''' - This function can be used to define HTML code used to link specifically to the customers account within a servers control panel. It is displayed on the product management page within the admin area if defined and must be an HTML output or link (no forms).
| |
| − | *'''ClientAreaCustomButtonArray''' - This function can be used to define custom functions that your module supports that customers are allowed to invoke and run from the client area. These functions can perform actions or product page output in the clientarea. Some example usages for this are to provide product management pages, bandwidth reporting pages, etc…
| |
| − | *'''ClientAreaAllowedFunctions''' - Similar to the above, this function can be used to define custom functions that customers are allowed to invoke themselves, but are not shown as buttons by default (ie. your custom client area output will invoke them)
| |
| − | | |
| − | *'''AdminCustomButtonArray''' - This function can be used to define custom functions that your module supports, similar to the above, but that admin users are allowed to run. This can contain more functions than the client area is allowed.
| |
| − | *'''UsageUpdate''' - This function is used to perform a daily import of the disk and bandwidth usage for accounts from a server. The data imported is then used to display the usage stats both within the client and admin areas of WHMCS, and also in disk and bandwidth overage billing calculations if enabled for a product.
| |
| − | *'''AdminServicesTabFields''' - This function can be used to define additional fields and output to be displayed on the admin product management pages.
| |
| − | *'''AdminServicesTabFieldsSave''' - This function is used in conjunction with the above to handle the values submitted in any custom fields when a save request is submitted.
| |
| − | | |
| − | ==Module Parameters==
| |
| − | | |
| − | The module parameters are the data/values passed into each function when called. Every module function is passed the same parameters. These variables provide information about the specific product/service the module command is being invoked for, along with the settings from the product itself as defined in the product configuration.
| |
| − | | |
| − | <table width="100%" cellspacing="1" bgcolor="#cccccc">
| |
| − | <tr bgcolor="#efefef"><td>Var Name</td><td>Description</td></tr>
| |
| − | <tr bgcolor="#ffffff"><td>serviceid</td><td>the unique ID of the service<br />Database Field: tblhosting.id</td></tr>
| |
| − | <tr bgcolor="#ffffff"><td>pid</td><td>the product ID that the service is assigned to<br />Database Field: tblproducts.id</td></tr>
| |
| − | <tr bgcolor="#ffffff"><td>serverid</td><td>the server ID that the service is assigned to<br />Database Field: tblservers.id</td></tr>
| |
| − | <tr bgcolor="#ffffff"><td>domain</td><td>the domain entered by the customer when ordering<br />Database Field: tblhosting.domain</td></tr>
| |
| − | <tr bgcolor="#ffffff"><td>username</td><td>the username generated for the service (defaults to first 8 letters of
| |
| − | the domain)<br />Database Field: tblhosting.username</td></tr>
| |
| − | <tr bgcolor="#ffffff"><td>password</td><td>the password generate for the service (10 char randomly generated on first creation consisting of letters & numbers, both upper & lowercase)<br />Database Field: tblhosting.password</td></tr>
| |
| − | <tr bgcolor="#ffffff"><td>producttype</td><td>the product type which can be one of sharedhosting, reselleraccount,
| |
| − | server or other</td></tr>
| |
| − | <tr bgcolor="#ffffff"><td>moduletype</td><td>the module name being called (will match filename of module)</td></tr>
| |
| − | <tr bgcolor="#ffffff"><td>configoptionX</td><td>with X being from 1 to 24, these fields contain all the module settings
| |
| − | for the product in the order defined in the ConfigOptions function of the module</td></tr>
| |
| − | <tr bgcolor="#ffffff"><td>clientsdetails</td><td>This variable contains a sub-array of all the clients details for the client
| |
| − | who owns the service in question. This contains things like firstname, lastname, email, address1, country, etc…</td></tr>
| |
| − | <tr bgcolor="#ffffff"><td>customfields</td><td>this variable contains a sub-array of all the custom fields defined for
| |
| − | the product, with the key being the custom field name - $params[‘customfields’][‘Field Name’]</td></tr>
| |
| − | <tr bgcolor="#ffffff"><td>configoptions</td><td>This variable contains a sub-array of all the configurable options
| |
| − | defined for the product, again with the key being the option name in this case - $params[‘configoption’][‘Option Name Here’]</td></tr>
| |
| − | <tr bgcolor="#ffffff"><td>server</td><td>true/false to define if the product is assigned to a server</td></tr>
| |
| − | <tr bgcolor="#ffffff"><td>serverip</td><td>the IP Address of the selected server</td></tr>
| |
| − | <tr bgcolor="#ffffff"><td>serverhostname</td><td>the Hostname of the selected server</td></tr>
| |
| − | <tr bgcolor="#ffffff"><td>serverusername</td><td>the Username of the selected server</td></tr>
| |
| − | <tr bgcolor="#ffffff"><td>serverpassword</td><td>the Password of the selected server</td></tr>
| |
| − | <tr bgcolor="#ffffff"><td>serveraccesshash</td><td>the Access Hash of the selected server</td></tr>
| |
| − | <tr bgcolor="#ffffff"><td>serversecure</td><td>true/false to define if Use SSL is enabled in the Server Configuration</td></tr>
| |
| − | </table>
| |
| − | | |
| − | ===Config Options===
| |
| − | | |
| − | Config options (not to be confused with Configurable Options) are the module's settings, defined in the ConfigOptions function of the module, and set on a per product basis. These are supplied as a numbered list, so the first option would be $params[‘configoption1’] , the second $params[‘configoption2’], etc… The order is defined by the order in which you specify the options in the ConfigOptions function of the module.
| |
| − | | |
| − | ===Custom Fields & Configurable Options===
| |
| − | | |
| − | The values from any custom fields & configurable options are loaded and passed into modules as parameters so that they can be easily used. They are passed as an array with the key being the name of the field or option.
| |
| − | | |
| − | For example if you created a custom field called “Username”, then that would be referenced using $params[‘customfields’][‘Username’] Similarly if you created a configurable option named “Disk Space”, then that would be referenced using $params[‘configoptions’][‘Disk Space’]
| |
| − | | |
| − | ==Core Module Functions==
| |
| − | | |
| − | The core module functions are the '''Create, Suspend, Unsuspend, Terminate, Renew, ChangePassword''' and '''ChangePackage''' functions.
| |
| − | | |
| − | These 7 functions all operate in a very similar manner. They can all be invoked both manually and automatically, and they are all expected to return either a success or error response.
| |
| − | | |
| − | ===Response Handling===
| |
| − | | |
| − | Each one of these functions after performing the actions they are required to, must either return a success message or error response.
| |
| − | | |
| − | For a successful result the code must actually return the word “success” to end the function. If WHMCS receives that it will know that the function completed in full as intended and continue on that basis.
| |
| − | | |
| − | However, should the function fail, what you return should be a user understandable error message, as it will be displayed directly to staff users.
| |
| − | | |
| − | ===Action Events===
| |
| − | | |
| − | When a function is successful, there are various actions that are performed as follows:
| |
| − | | |
| − | *'''CreateAccount''' - Changes status to Active + Sends Product Welcome Email
| |
| − | *'''SuspendAccount''' - Changes status to Suspended
| |
| − | *'''UnsuspendAccount''' - UnsuspendAccount
| |
| − | *'''TerminateAccount''' - Changes status to Terminated
| |
| − | *'''ChangePassword''' - Updates password in database
| |
| − | | |
| − | In addition to the above actions, admin users are given a confirmation of successful functions completing, and errors in the case of them failing. If the functions were invoked automatically such as on payment of a new order, then that notification can be in the form of an email. And in the case of the ChangePassword function, any errors returned from that function are also displayed to end users within the client area also.
| |
| − | | |
| − | ==Single Sign-On==
| |
| − | | |
| − | Single sign-on can occur for a service or server.
| |
| − | | |
| − | Whichever method being used, the return is expected to be the same.
| |
| − | | |
| − | The return from either function should always be an array and contain
| |
| − | two keys of a possible three.
| |
| − | | |
| − | * success - This is a [[Glossary#Boolean|boolean]] value and should indicate success or failure
| |
| − | * redirectTo - This should be a fully formatted URL return from your SSO request
| |
| − | * errorMsg - Any appropriate error message to be displayed to whoever is making the request
| |
| − | ===Service Single Sign-On===
| |
| − | | |
| − | Service single sign-on is to allow admin and client users to login to the control panel of the service automatically.
| |
| − | | |
| − | <source lang="php">
| |
| − | /**
| |
| − | * Perform single sign-on for a given instance of a product/service.
| |
| − | *
| |
| − | * Called when single sign-on is requested for an instance of a product/service.
| |
| − | *
| |
| − | * When successful, returns a URL to which the user should be redirected.
| |
| − | *
| |
| − | * @param array $params common module parameters
| |
| − | *
| |
| − | * @see http://docs.whmcs.com/Provisioning_Module_SDK_Parameters
| |
| − | *
| |
| − | * @return array
| |
| − | */
| |
| − | function mymodule_ServiceSingleSignOn(array $params)
| |
| − | {
| |
| − | $return = array(
| |
| − | 'success' = false,
| |
| − | );
| |
| − | try {
| |
| − | /**
| |
| − | * all the service's single sign-on token retrieval function, using the
| |
| − | * values provided by WHMCS in `$params`.
| |
| − | * The variables and response format would depend on your server API
| |
| − | */
| |
| − | | |
| − | $response = $formattedResponse = custom_call_to_server();
| |
| − | | |
| − | $return = array(
| |
| − | 'success' => true,
| |
| − | 'redirectTo' => $response['redirectUrl'],
| |
| − | );
| |
| − | } catch (Exception $e) {
| |
| − | $return['errorMsg'] = $e->getMessage();
| |
| − | $response = $e->getMessage();
| |
| − | $formattedResponse = $e->getTraceAsString();
| |
| − | }
| |
| − | | |
| − | /**
| |
| − | * Log any call to the server
| |
| − | */
| |
| − | logModuleCall(
| |
| − | 'provisioningmodule',
| |
| − | __FUNCTION__,
| |
| − | $params,
| |
| − | $response,
| |
| − | $formattedResponse,
| |
| − | array('username', 'password')
| |
| − | );
| |
| − | | |
| − | }
| |
| − | </source>
| |
| − | | |
| − | ===Server Single Sign-On===
| |
| − | | |
| − | Server single sign-on allows for Admin users to login to the associated server management panel (like WHM for cPanel) automatically.
| |
| − | <source lang="php">
| |
| − | /**
| |
| − | * Perform single sign-on for a server.
| |
| − | *
| |
| − | * Called when single sign-on is requested for a server assigned to the module.
| |
| − | *
| |
| − | * This differs from ServiceSingleSignOn in that it relates to a server
| |
| − | * instance within the admin area, as opposed to a single client instance of a
| |
| − | * product/service.
| |
| − | *
| |
| − | * When successful, returns a URL to which the user should be redirected to.
| |
| − | *
| |
| − | * @param array $params common module parameters
| |
| − | *
| |
| − | * @see http://docs.whmcs.com/Provisioning_Module_SDK_Parameters
| |
| − | *
| |
| − | * @return array
| |
| − | */
| |
| − | function mymodule_AdminSingleSignOn(array $params)
| |
| − | {
| |
| − | $return = array(
| |
| − | 'success' = false,
| |
| − | );
| |
| − | try {
| |
| − | /**
| |
| − | * all the service's single sign-on token retrieval function, using the
| |
| − | * values provided by WHMCS in `$params`.
| |
| − | * The variables and response format would depend on your server API
| |
| − | */
| |
| − | | |
| − | $response = $formattedResponse = custom_call_to_server();
| |
| − | | |
| − | $return = array(
| |
| − | 'success' => true,
| |
| − | 'redirectTo' => $response['redirectUrl'],
| |
| − | );
| |
| − | } catch (Exception $e) {
| |
| − | $return['errorMsg'] = $e->getMessage();
| |
| − | $response = $e->getMessage();
| |
| − | $formattedResponse = $e->getTraceAsString();
| |
| − | }
| |
| − | | |
| − | /**
| |
| − | * Log any call to the server
| |
| − | */
| |
| − | logModuleCall(
| |
| − | 'provisioningmodule',
| |
| − | __FUNCTION__,
| |
| − | $params,
| |
| − | $response,
| |
| − | $formattedResponse,
| |
| − | array('username', 'password')
| |
| − | );
| |
| − | | |
| − | }
| |
| − | </source>
| |
| − | | |
| − | ==The UsageUpdate Function==
| |
| − | | |
| − | The UsageUpdate function can be used to perform a daily import of the disk and bandwidth
| |
| − | usage for accounts from a server. The data imported is then used to display the usage stats
| |
| − | both within the client and admin areas of WHMCS, and also in disk and bandwidth overage
| |
| − | billing calculations if enabled for a product.
| |
| − | | |
| − | The UsageUpdate function is called by the daily cron if present in a module, for any active
| |
| − | and enabled server, on a per server basis (important: it is called per server not per product).
| |
| − | Therefore this can only be used if your module has a server created in WHMCS for it,
| |
| − | products alone do not invoke it.
| |
| − | | |
| − | The function is passed the id, ip, hostname, username/hash, & password variables and is
| |
| − | then expected to query the disk and bandwidth stats for all accounts on that server, and
| |
| − | update them within the database directly all in a single call for speed and efficiency. An
| |
| − | example of how to do this is included below.
| |
| − | | |
| − | <source lang="php">
| |
| − | function mymodule_UsageUpdate($params) {
| |
| − | | |
| − | $serverid = $params['serverid'];
| |
| − | $serverhostname = $params['serverhostname'];
| |
| − | $serverip = $params['serverip'];
| |
| − | $serverusername = $params['serverusername'];
| |
| − | $serverpassword = $params['serverpassword'];
| |
| − | $serveraccesshash = $params['serveraccesshash'];
| |
| − | $serversecure = $params['serversecure'];
| |
| − | | |
| − | # Run connection to retrieve usage for all domains/accounts on $serverid
| |
| − | | |
| − | # Now loop through results and update DB
| |
| − | | |
| − | foreach ($results AS $domain=>$values) {
| |
| − | update_query("tblhosting",array(
| |
| − | "diskused"=>$values['diskusage'],
| |
| − | "disklimit"=>$values['disklimit'],
| |
| − | "bwusage"=>$values['bwusage'],
| |
| − | "bwlimit"=>$values['bwlimit'],
| |
| − | "lastupdate"=>"now()",
| |
| − | ),array("server"=>$serverid,"domain"=>$values['domain']));
| |
| − | }
| |
| − | | |
| − | }
| |
| − | </source>
| |
| − | | |
| − | ==Custom Functions==
| |
| − | | |
| − | Custom functions allow you to define additional operations that can be performed using the module. The custom functions can perform actions, or define additional client area pages/output. Permissions can be granted for who can use each custom function, be it just clients, just admins, or both.
| |
| − | | |
| − | The naming convention for custom functions follows the same as any other function within a module so it must begin with the module filename, followed by an underscore, and then the custom function name.
| |
| − | | |
| − | The easiest way to demonstrate this is with an example so let’s take an example of a reboot & shutdown function in a VM/VPS system:
| |
| − | | |
| − | <source lang="php">
| |
| − | function template_reboot($params) {
| |
| − | | |
| − | # Code to perform reboot action goes here...
| |
| − | | |
| − | if ($successful) {
| |
| − | $result = "success";
| |
| − | } else {
| |
| − | $result = "Error Message Goes Here...";
| |
| − | }
| |
| − | return $result;
| |
| − | | |
| − | }
| |
| − | | |
| − | function template_shutdown($params) {
| |
| − | | |
| − | # Code to perform shutdown action goes here...
| |
| − | | |
| − | if ($successful) {
| |
| − | $result = "success";
| |
| − | } else {
| |
| − | $result = "Error Message Goes Here...";
| |
| − | }
| |
| − | return $result;
| |
| − | | |
| − | }
| |
| − | </source>
| |
| − | | |
| − | In the above you can see how the custom functions are defined, being passed all the same module parameters as all other functions, & returning either “success” for a success or an error message to indicate a failure. Now let’s say we wanted to allow clients to perform reboots, but only admin users to be able to perform a shutdown, here’s how we would define that:
| |
| − | | |
| − | <source lang="php">
| |
| − | function template_ClientAreaCustomButtonArray() {
| |
| − | $buttonarray = array(
| |
| − | "Reboot Server" => "reboot",
| |
| − | );
| |
| − | return $buttonarray;
| |
| − | }
| |
| − | | |
| − | function template_AdminCustomButtonArray() {
| |
| − | $buttonarray = array(
| |
| − | "Reboot Server" => "reboot",
| |
| − | "Shutdown Server" => "shutdown",
| |
| − | );
| |
| − | return $buttonarray;
| |
| − | }
| |
| − | </source>
| |
| − | | |
| − | What we are saying here is that clients are allowed perform the “reboot” function, but admins can perform both “reboot” and “shutdown”.
| |
| − | | |
| − | The key value of the array is what get’s displayed to admins/clients on the button or menu options for the commands. And the value is the custom function name excluding the modulename_ prefix.
| |
| − | | |
| − | If you want to provide clients with a custom button or way to invoke a function, then this can be done as follows within a .tpl file described in the previous Client Area Output section:
| |
| − | | |
| − | <form method="post" action="clientarea.php?action=productdetails">
| |
| − | <input type="hidden" name="id" value="{$serviceid}" />
| |
| − | <input type="hidden" name="modop" value="custom" />
| |
| − | <input type="hidden" name="a" value="reboot" />
| |
| − | <input type="submit" value="Reboot VPS Server" />
| |
| − | </form>
| |
| − | | |
| − | ==Client Area Output==
| |
| − | | |
| − | Another key function of a module is to give clients access to extra options and output within the client area. This can be done either on the product details page itself (using the ClientArea function of a module) or as a custom function/action described above.
| |
| − | | |
| − | ===Product Details Page Output===
| |
| − | | |
| − | Creating output to be displayed on the same page as the product details in the client area, it's simply a case of creating a template file named “clientarea.tpl” within your module folder. This template file will be processed as a Smarty template file as with all templates in WHMCS, and so can make use of smarty variables which will be the same module vars as are passed to every module function, as well as other smarty functions such as custom PHP code blocks and logic functions.
| |
| − | | |
| − | If you need something a little more advanced, such as being able to perform API calls and defining custom variables for use in the output, then you can define a ClientArea function within your custom module that can run any custom code required and then return an array defining both the template file to use, and any variables that template should have available in addition to the defaults. By returning different templatefile values based on values in the $_GET or $_POST array data, you can create multiple pages with different output and link between them from your custom output.
| |
| − | | |
| − | <source lang="php">
| |
| − | function mymodule_ClientArea($vars) {
| |
| − | return array(
| |
| − | 'templatefile' => 'clientarea',
| |
| − | 'vars' => array(
| |
| − | 'test1' => 'hello',
| |
| − | 'test2' => 'world',
| |
| − | ),
| |
| − | );
| |
| − | }
| |
| − | </source>
| |
| − | | |
| − | ===Custom Pages===
| |
| − | | |
| − | There may be situations where rather than output being displayed on the product details page below the general information for a product, you might want to have a completely custom page for it. And with WHMCS that is certainly possible. This is done by using custom functions as described earlier in this article, and from that function returning an array something like as follows:
| |
| − | | |
| − | <source lang="php">
| |
| − | function mymodule_mycustomfunction($vars) {
| |
| − | return array(
| |
| − | 'templatefile' => 'customfunc',
| |
| − | 'breadcrumb' => array(
| |
| − | 'stepurl.php?action=this&var=that' => 'Custom Function',
| |
| − | ),
| |
| − | 'vars' => array(
| |
| − | 'test1' => 'hello',
| |
| − | 'test2' => 'world',
| |
| − | ),
| |
| − | );
| |
| − | }
| |
| − | </source>
| |
| − | | |
| − | You then just need to authorize clients to use this custom function, and provide a link to it for them in the product details page output using the same methods as described earlier in the ‘’’ Custom Functions’’’ section of the docs.
| |
| − | | |
| − | ==Admin Services Tab==
| |
| − | | |
| − | Available in WHMCS V4.3 and later, the Admin Services Tab functions of a module allow you
| |
| − | to define additional fields that should appear on the product details page of the admin area for staff use. These can be used just for informational output, or for settings and values stored in cus-tom tables or remotely outside of WHMCS.
| |
| − | | |
| − | An example of what we use it for in the core WHMCS system is for our licensing addon
| |
| − | module, where the license specific fields of the allowed domains, IPs and Directory can then
| |
| − | be viewed and set from the product details view.
| |
| − | | |
| − | There are 2 functions relating to the services tab - AdminServicesTabFields and AdminServicesTab-FieldsSave. The first of these allows you to define the additional fields to output, and the latter (optionally) allows you to handle any input in them on submission/save.
| |
| − | | |
| − | So on to an example, below we show you how you could define 4 extra fields that would show an input field, dropdown, textarea and info only output as examples, and then update them in a cus-tom table of the database via the save event.
| |
| − | | |
| − | <source lang="php">
| |
| − | function mymodule_AdminServicesTabFields($params) {
| |
| − | | |
| − | $result = select_query("mod_customtable","",array("serviceid"=>$params['serviceid']));
| |
| − | $data = mysql_fetch_array($result);
| |
| − | $var1 = $data['var1'];
| |
| − | $var2 = $data['var2'];
| |
| − | $var3 = $data['var3'];
| |
| − | $var4 = $data['var4'];
| |
| − | | |
| − | $fieldsarray = array(
| |
| − | 'Field 1' => '<input type="text" name="modulefields[0]" size="30" value="'.$var1.'" />',
| |
| − | 'Field 2' => '<select name="modulefields[1]"><option>Val1</option</select>',
| |
| − | 'Field 3' => '<textarea name="modulefields[2]" rows="2" cols="80">'.$var3.'</textarea>',
| |
| − | 'Field 4' => $var4, # Info Output Only
| |
| − | );
| |
| − | return $fieldsarray;
| |
| − | | |
| − | }
| |
| − | | |
| − | function mymodule_AdminServicesTabFieldsSave($params) {
| |
| − | update_query("mod_customtable",array(
| |
| − | "var1"=>$_POST['modulefields'][0],
| |
| − | "var2"=>$_POST['modulefields'][1],
| |
| − | "var3"=>$_POST['modulefields'][2],
| |
| − | ),array("serviceid"=>$params['serviceid']));
| |
| − | }
| |
| − | </source>
| |
| − | | |
| − | ==Module Logging==
| |
| − | | |
| − | To make reviewing and debugging module calls easier, WHMCS has a built in logging function that allows you to record the request and response strings for every call your module makes, in an easily accessible way via the WHMCS admin interface. If you ultimately plan to release your module publically, this also makes it easier for end users to troubleshoot and debug issues they experience using your module on their own, and for you to be able to debug issues they experience while using it.
| |
| − | | |
| − | The logging is not something that is enabled permenantly, to avoid logs growing uncontrollably and unecessarily, so it's something that needs to be enabled for the logging to actually happen. This is done in '''Utilities > Logs > Module Debug Log''' which is the same place as where the logs can be reviewed.
| |
| − | | |
| − | To utilise this functionality, you simply need to make a call as follows:
| |
| − | | |
| − | <source lang="php">
| |
| − | logModuleCall($module,$action,$requeststring,$responsedata,$processeddata,$replacevars);
| |
| − | </source>
| |
| − | | |
| − | *'''$module''' - This should be the name of your module, for example "cpanel", "plesk", "resellerclub", etc...
| |
| − | *'''$action''' - This should be the action being performed, ie. create, suspend, register, etc...
| |
| − | *'''$requeststring''' - This should be the variables being posted to the remote API. This can be in either '''string''' or '''array''' format.
| |
| − | *'''$responsedata''' - This is where you return the raw API response. This can be in either '''string''' or '''array''' format also.
| |
| − | *'''$processeddata''' - Similar to the above, but this can be used for a post processing API response, such as after conversion into a friendly format, an array for example
| |
| − | *'''$replacevars''' - This accepts an array of strings to replace, so for example you might want to pass the username and password for the API into this function, which would then be replaced with *'s wherever they appear in either the request or response strings for extra security
| |
| − | | |
| − | ==App Store==
| |
| − | WHMCS offers an app store to which your completed module can be submitted. The listings are displayed under the Addons tab within the administration area and online at http://www.whmcs.com/appstore . This is a great way to make WHMCS users aware of your module.
| |
| − | | |
| − | In order to submit a listing you'll need a login for whmcs.com/members, if you do not have one please [https://www.whmcs.com/members/submitticket.php?step=2&deptid=5 Contact Us]. Once logged in, visit the app store page at the above URL and click the "Submit your Addon" link. We aim to review submissions in 1-2 weeks.
| |
| − | | |
| − | | |
| − | {{Developer_Links}}
| |