Addons for WHMCS

    Addon for advanced features

    User manual for the WHMCS Domain Management Tool
    MrDomain

    Download from Github

    1 Introduction

    This is the user manual for the MrDomain's Advanced features Addon for WHMCS.

    This software adds new capabilities to the WHMCS administration panel using the MrDomain's API, including:

    • Automatic domain syncing
    • Adding new TLDs to WHMCS
    • Managing existing domains and TLDs
    • Personalized email alerts for new TLDs and price changes
    • Domain suggestions for your customers
    • Whois proxy for checking domain availability

    1.1  Getting started

    The MrDomain's Domain Management Addon for WHMCS uses the MrDomain's API. You need to have a working API account.

    To activate the plugin you will need an API USername and API Password that you should have obtained from MrDomain's support team. For more information about the MrDomain's API, visit the online documentation.

    1.2 Available characteristics

    This addon allows to perform the following actions:

    • Update prices and configure existing TLDs in WHMCS
    • Add new TLDs supported by MrDomain but not yet configured in WHMCS
    • Update information and configuration of existing domains in WHMCS
    • Importing existing domains in the MrDomain account that are not yet created in WHMCS
    • Notify via email when new TLDs are added to MrDomain or there's a price change
    • Displaying domain suggestions when your customers look for domain availability
    • Perform a domain availability check through the MrDomain API

    The addon will also add a hook to WHMCS to update regularly prices and send notifications. You can learn more about WHMCS hooks on their documentation section.

    1.3 Disclaimer

    HMCS is a registered trademark of WHMCS Ltd.. MrDomain isn't part or is otherwise affialiated to WHMCS Ltd.. You can get more information on WHMCS Software on its official website.

    2  Installation

    To install the Addon, download the ZIP from our Github repository. Once download, unzip it and you will end up with a folder named dondominio. Upload the folder to your addons directory on your WHMCS installation, usually /path/to/whmcs/modules/addons/.

    Once the folder is uploaded, access the WHMCS administration panel and go to the addon configuration screen, on Settings > Addon modules. Locate an addon named DonDominio Manager Addon and click on the Enable button. Once activated, click on Configure and adjust the roles that will be able to use the Addon (usually, Full Administrator).

    Addons

    If the module was enabled correctly, now you should be able to configure and use it.

    2.1 Minimum configuration

    To start using the module, first it needs to be configured. The minimum required configuration is your MrDomain API details (username and password). To enter your API credentials, access Addons > DonDominio Manager Addon.

    Addons

    Since you have not yet configured the addon, the only screen you'll be able to access is the settings screen. In this screen, fill the following fields:

    API Username: Write in your API username
    API Password: Write in your API password

    Then, click Save changes and the addon will be activated. It may take a few seconds to activate it while the addon builds the internal TLD cache. Once finished, you will be able to access all other options.

    Addons

    2.2 Uninstallation

    To remove the addon, first go to Settings > Addon modules and locate DonDominio in the list. Click on the Disable button. All information stored in the database will be lost, except for the created TLDs and domains (and all associated settings).

    To completely delete the addon from your WHMCS installation, go to /path/to/whmcs/modules/addons, locate a dondominio folder and delete it.

    2.3 Multi-language support

    The addon is available both in English and Spanish. It will automatically change depending on the language selected on your WHMCS administration panel. If you choose a different language from those two, the addon will default to English. For more information on language settings for WHMCS, check the documentation.

    3 Module: Price update

    The Price update module allows you to update the prices for your TLDs using the information available on MrDomain's API.

    Addons

    3.1 Price update

    Heads up In order to update prices, the TLDs must be configured to use MrDomain as registrar. See the Change registrar function in this same module for more information, and the WHMCS Registrar Plugin documentation for more information.

    To use the Price update function, first select all the TLDs you want to update and then click on Update prices. The addon will apply to all selected TLDs the latest prices downloaded from the MrDomain's API, taking into account price increases defined in the Settings.

    3.2  Change registrar

    In order to manage a TLD using this addon, it must be configured to work with the WHMCS Registrar Plugin from MrDomain. Select all the TLDs you want to use with this plugin and click Change registrar to DonDominio. They will be automatically configured to use the plugin from that moment.

    Heads up Any other registrar plugin you were using with those TLDs (if applicable) will be disabled for all those TLDs.

    3.3 Manual price adjustment

    You can manually adjust prices for TLDs instead of using the API prices in conjunction with the price modifications defined on the Settings screen. Click on the Editar icon to access the manual prices screen.

    On this new screen, you'll find the following options:

    Do not update prices automatically for this TLD Enable this option to make the automatic price adjustment tool ignore this TLD.

    *Enable individual settings Enable this option to manually adjust prices for this TLD instead of using the regular system.

    Register increase A registration price increase to be applied to the regular registration price for this TLD. The registration price is obtained via the MrDomain's API, and you can choose to apply it as a Fixed increase (adding this quantity to the price on MrDomain), as a % (adding a percent to the price on MrDomain), or rather Disable it and set the price directly as you entered it in this field (ignoring all other prices, increases, and so on).

    Transfer increase and Renewal increase Both work like Register increase explained above, but for transfers and renewals, respectively.

    To save the settings, click on Save changes.

    When prices are updated for this TLD (automatically or manually) the settings entered in this screen will take effect.

    4 Module: Available TLDs

    The Available TLDs module allows you to create new TLDs supported by the MrDomain's API but not yet created in WHMCS.

    When creating a new TLD, the most recent prices obtained from MrDomain's API will be used, and the WHMCS Registrar Plugin from MrDomain will be automatically enabled for it.

    Addons

    4.1 Filters

    This module has filters available to narrow the number of TLDs displayed on the list. Click on Filter/Search at the beggining of the list and enter all or part of a TLD name to restrict the list to that search.

    4.2 Adding TLDs

    Select one or more TLDs you want to add to your WHMCS installation and click on Add to WHMCS to create them automatically. The new TLDs will have the latest prices obtained from the MrDomain's API (taking into account modifications defined in Settings) and will be configured to use the WHMCS Registrar Plugin from MrDomain.

    Once added, the TLDs will be available to your customers to select them and register and transfer domains.

    Alternatively, you can click on the Añadir icon to add that specific TLD.

    5 Module: Domain Management

    The Domain Management module allows you to check and update information from domains already registered on your WHMCS installation. It will also allow you to configure those domains to use the WHMCS Registrar Plugin from MrDomain.

    Addons

    5.1 Filters

    This module has filters available to search in the list. Click on Filter/Search to narrow the search using one of the following fields: Domain name, TLD, Registrar and Status.

    5.2 Registrar change

    Select one or more domains from the list and click on Switch registrar to DonDominio to configure those domains to use the WHMCS Registrar Plugin from MrDomain.

    5.3 Update information

    Heads up
    In order for the addon to be able to update the information of a domain it must be first configured to use the WHMCS Registrar Plugin fromMrDomain.

    Select one or more domains from the list and click on Update information from DonDominio to update the domain information according to the information available through the MrDomain's API. The information updated will be the domain status and its expiration date.

    Alternatively, you can click on the Sincronizar icon to update that domain's information.

    5.4 Contacts

    You can perform contacts mass changes from this screen using a MrDomain Contact ID.

    MrDomain Contact IDs The MrDomain Contact IDs are special codes that identify domain contacts inside MrDomain accounts. They are something similar to AAA-00000 and you can find them on the MrDomain administration panel.

    To see your Contact IDs, go to your MrDomain administration panel on https://www.mrdomain.com and then click on Admin at the top left, then on Tools and finally on Contacts. On the list that will appear, you will find each Contact ID under the column Contact ID. This is the code that you need to write on the corresponding field.

    Select one or more domains that you want to modify, write the Contact ID in the DonDominio Contact ID field and then click on one of the following buttons:

    • Update owner contact: This will update the owner contact for the domains using the Contact ID you provided.
    • Update admin contact: This will update the admin contact for the domains using the Contact ID you provided.
    • Update tech contact: This will update the tech contact for the domains using the Contact ID you provided.
    • Update billing contact: This will update the billing contact for the domains using the Contact ID you provided.

    Heads up This change may take several minutes when applied to a large amount of domains at once.

    6 Module: Import domains

    The Import domains module allows you to import existing domains on your MrDomain account to your WHMCS installation. The imported domains will be created using all the information available about them on the MrDomain's API and will be assigned to the customer of your choice.

    At the right side of each domain you will find an status indicator. NOT IMPORTED means that domain is not yet created on WHMCS, and IMPORTED means that the domain already exists (and can't be imported again).

    To update domain information for already imported domains, use the Domain Management screen.

    Addons

    6.1 Import

    Select one or more domains from the list, choose a customer from the dropbox and click the Import to WHMCS and assign to selected customer button. The domains will be copied to your WHMCS database and assigned to that customer as it was registered normally.

    Select domains that are already imported will be ignored.

    7 Module: Domain suggestions

    This module allows to add suggestions for other domain names to the domain availability check built in WHMCS, using the MrDomain API.

    7.1 Integration

    By default, this module is built to work with the default template from WHMCS 6.x. To use it with older versions, other templates, or your custom template, you will need to adapt some HTML and JavaScript code that is required by the module to work.

    7.1.1 Adjusting your HTML

    First, access your addon folder. Inside you will find folder named suggests that contains a template.php file. In this file there's the HTML required by the module to display suggestions. You may modify this file to match your current template. You may use any HTML for this, just remember a couple of rules:

    • Use \" instead of " to avoid syntax errors
    • Do not add other PHP code to this file to avoid problems
    • Do not alter or add tags
    Tags

    The HTML code has tags to add the information via JavaScript. This HTML is built using Moustache, an HTML templating system for JavaScript. All tags look {{like_this}}, with two leading brackets, a single-word name, and followed by two closing brackets.

    The tags available are these:

    Tag Definition
    {{#suggestions}} The Array containing the suggestions
    {{price.currency_prefix}} Prefix for the currency used (for example, $)
    {{price.1Y}} & more Price for a 1-year registration. Goes from 1Y to 10Y.
    {{price.currency_suffix}} Suffix for the currency used (for example, USD)
    {{domain}} Suggested domain name
    {{/suggestions}} End of suggestions loop

    7.1.2 Adjusting your JavaScript

    You may need to alter the JavaScript that makes this work. In order to do this, you will need to edit the suggests.js file. The part that you will want to modify is the following one:

    $( document ).ready( function( e )
    {
        var events = $._data( $('#frmDomainChecker')[0], 'events' );
    
        $._data( $('#frmDomainChecker')[0], 'cache', events.submit[0].handler);
    
        events.submit = null;
    
        var events = $._data( $('#frmDomainChecker')[0], 'events' );
    
        $( "#frmDomainChecker" ).submit( function( e )
        {
            e.preventDefault();
    
            loadSuggestions( e );
        });
    
        var suggestions = $( "<div></div>", { id: "suggestionResults", html: "" });
    
        $( "#stepResults" ).after( suggestions );
    
        loadSuggestions( null );
    });

    This is the part that hooks the action to the domain check form and prepares the container for the suggestions result. By default, the form's ID is frmDomainChecker, and the results will be added in a DIV after stepResults. You will need to adjust these two IDs if your template names them differently. You can also place the results in a different place by altering the following code:

    var suggestions = $( "<div></div>", { id: "suggestionResults", html: "" });
    
    $( "#stepResults" ).after( suggestions );

    Just make sure that a DIV with ID suggestionResults exists somewhere in your HTML code and you're good to go.

    You should not need to edit the following section:

    function loadSuggestions( e )
    {   
        var search = $( "#inputDomain" ).val();
        var captcha_code = $( "#inputCaptcha" ).val();
    
        if( !search || captcha_code.trim().length == 0 ){
            return false;
        }
    
        jQuery("#btnCheckAvailability").html('<i class="fa fa-spinner fa-spin"></i>');
    
        $.ajax({
            url: "modules/addons/dondominio/suggests/suggests.php",
            method: "post",
            data: "text=" + search + "&captcha=" + $( "#inputCaptcha" ).val(),
            dataType: "json",
            success: function( data ){
                var table = ich.suggestions_template({
                    suggestions: data
                });
    
                $( "#suggestionResults" ).html( table );
    
                if( e != null ){
                    var org_submit = $._data( $('#frmDomainChecker')[0], 'cache' );
    
                    org_submit( e );
                }else{
                    jQuery("#btnCheckAvailability").html(langSearch);
                }
            }
        });
    }

    This is the function that requests the suggestions in JSON format and process them. If you need to alter the way the results are processed, you are free to modify this section. Just make sure you don't skip this step:

    var table = ich.suggestions_template({
        suggestions: data
    });

    This is the code that generates the table (using the HTML template previously edited) and puts the suggestions in place. The table variable will contain a DOM object (HTML) that you can add or inject wherever you need. By default, it's going on the suggestionResults DIV:

    $( "#suggestionResults" ).html( table );

    Finally, this bit of code puts a nice "loading" gif on the submit button:

    jQuery("#btnCheckAvailability").html('<i class="fa fa-spinner fa-spin"></i>');

    This is done for the default template on WHMCS 6.x. If you use another loading indicator, feel free to modify this bit to display it at that point.

    8 Module: Whois Proxy

    This module is comprised of two parts that allow to set up a simple whois proxy locally to perform domain availability checks from WHMCS (also known as "Whois lookup").

    Please take into account that his module *does not allow to check whois information about a domain, only to report the availability of a domain to be registered.

    Whois

    8.1 Set up

    The module has several options that you may modify:

    Permissions
    If you see a message informing you that the whoisservers.php file does not have writing permissions, you will need to change the permissions of this file to allow the web server to modify it. Otherwise, you'll need to change its contents manually.

    Access control
    Due to the high demand that usually this kind of services have and the limited amount of API calls you can perform, it's recommended to restrict outside access to the proxy using the IP filters or another type of protection of your choice. Access the Settings section of the addon and configure access control for the Whois Proxy before continuing.

    Backup
    The addon has a built-in import/export option designed to make backups of your whoisservers.php file. We heavily recommend doing a backup of this file before making any changes. A bad configuration in this file may render WHMCS unable to perform domain availability checks for domain registrations and transfers.

    Click the button Change to MrDomain to configure each TLD automatically. Your whoisservers.php will be modified so WHMCS uses the MrDomain API to check domains in those TLDs from that moment on. You don't need to make any other changes.

    8.2 Manual set up for WHMCS 6

    If your web server is unable to write to the whoisservers.php file, you will need to change it manually. To do so, browse to your /path/to/whmcs/includes/ folder and edit the file with your preferred editor.

    Search in the file the TLD or TLDs you want to configure. They should look like this:

    .me.uk|whois.nic.uk|No match

    Change it to look like this:

    .me.uk|http://www.yourwhmcsdomain.com/modules/addons/dondominio/whois/whoisproxy.php?domain=|DDAVAILABLE

    Where http://www.yourwhmcsdomain.com/ is the domain to access your WHMCS frontend. You may make this change on as many TLDs as you need.

    8.3 Manual set up for WHMCS 7

    The file in WHMCS 7 for whois servers has been changed to a JSON file and is stored in a different location than its WHMCS 6 counterpart.

    You'll find it in /path/to/whmcs/resources/domains/ with the name dist.whois.json.

    If you want to configure manually a whois server in this file, you'll need to find the correct entry for the TLD you want to modify and adjust it.

    An entry looks like this in the file:

    [
    ...
    {
        "extensions": ".com,.net,.es,.com.es,.nom.es,.gob.es,.edu.es",
        "uri": "socket://whois.crsnic.net",
        "available": "No match for"
    },
    ...
    ]

    Adjust the "uri" and "available" fields, like this:

    [
    ...
    {
        "extensions": ".com,.net,.es,.com.es,.nom.es,.gob.es,.edu.es",
        "uri": "http://www.yourwhmcsdomain.com/modules/addons/dondominio/whois/whoisproxy.php?domain=",
        "available": "DDAVAILABLE"
    },
    ...
    ]

    Where http://www.yourwhmcsdomain.com/ is the domain to access your WHMCS frontend. You may make this change on as many TLDs as you need.

    9 Module: Settings

    The Settings module allows you to configure behaviours and functionalities from the addon.

    The settings are divided under tabs for easier use.ç

    9.1 DonDominio's API

    API

    Field Values Description
    API Username Text Your API Username
    API Password Text Your API Password

    9.2 Price adjustment

    Price

    Field Values Description
    Update prices in WHMCS when they change/Yes/No When there's a price change in
    MrDomain, also update TLD prices in WHMCS
    Registration increase Number Quantity (fixed or %) to add to TLD prices when
    changing registration prices in WHMCS.
    Transfer increase Number Quantity (fixed or %) to add to TLD prices when
    changing transfer prices in WHMCS.
    Renewal increase Number Quantity (fixed or %) to add to TLD prices when
    changing renewal prices in WHMCS.

    9.3 Automatic notifications

    Notifications

    Field Values Description
    Enable notifications Yes/No\Enable or disable notfications on the module
    globally
    Email for notifications Email The Email address that will receive the
    notifications. If left blank, no notifications will be sent.
    Enabled notifications N/A The multiple kinds of notifications available.
    Enable the ones you want to receive notifications for.
    Watch/Ignorelist N/A Watch/Ignorelist feature.

    To use the Watch/Ignorelist feature, first select one of the available modes:

    • Do not use Watch/Ignorelist: The feature will be disabled.
    • Watch only these TLDs: Receive notifications only for selected TLDs.
    • Ignore these TLDs: Do not receive notifications for selected TLDs.

    Then, select one or more TLDs from the left list (Available TLDs) and click >> to move them to the right list (Selected TLDs). To remove a TLD from the selected list, select it and click <<.

    9.4 Cache status

    Cache

    This addon stores some information on the local database (also known as cache). This screen displays information from the cache currently stored in the database.

    • Last update: Last time prices were downloaded from the MrDomain's API.
    • TLDs in cache: Number of TLDs stored on the cache and supported by the MrDomain's API.
    • Rebuild cache: Check this checkbox and click on Save changes to empty the current cache and redownload all the prices from the MrDomain's API again.

    9.5 Domain Suggestions

    Suggests

    • Enable domain suggestions: Check to enable this feature
    • Language: Select the language that will be used to generate the suggestions
    • TLDs: Select which TLDs will be used to generate the suggestions

    9.6 Whois Proxy

    Whois

    • WHMCS Domain: The URL that leads to your WHMCS frontend
    • Allowed IP Address: One or more IP addresses, separated by semi colons, that are allowed to use the Whois Proxy