Development Guides Home >> Guide to cPanel Plugins in the Paper Lantern Theme

Guide to cPanel Plugins - Pluggable Statistics Modules

Introduction

Pluggable statistics modules can display custom statistics items in the cPanel interface.

Important:

We strongly recommend that you test this feature on any themes that you support (for example, Glass, Basic, Dark, Light, and Retro).


Module behavior

Before you create a custom statistics module, make certain that you understand how the system interacts with custom statistics modules:

  • If any item in a module fails, this function will not display any items from that module. However, failure in one module will not prevent the display of other modules.
  • Custom data modules execute on every cPanel Home interface page load.
    • The interface loads custom modules after the initial page load.
    • The system does not cache the data that custom modules poll.

The presence of the /var/cpanel/perl/Cpanel/ResourceUsage/Custom directory triggers each ResourceUsage call. Every time that a user loads or refreshes the cPanel Home interface, the system must open and list the contents of that directory. If no modules exist in the directory, you should delete the directory to avoid the extra disk load.

Create the custom module

To create a custom statistics module, create the /var/cpanel/perl/Cpanel/ResourceUsage/Custom/modulename.pm file, where modulename represents your new module's name.

Note:

Create a unique module name. The system can process multiple custom modules.


package Cpanel::ResourceUsage::Custom::modulename;

use strict;
use warnings;

# This feature expects each custom module to contain a "get_usages" function
# that returns an array of hashes, with each hash matching the parameters below:

sub get_usages {
    my ($username) = @_;

    return (
        {
            id          => '…',              #string, not displayed
            description => '…',              #string, displayed
            usage       => …,                #nonnegative integer
            maximum     => …,                #optional, nonnegative integer
            formatter   => 'format_bytes',   #optional; if defined, the value is passed through the specified formatter for display
            app         => '…',              #optional, to link to a cPanel interface
            before      => '…',              #optional, to display immediately before another entry
        },
        {
            id          => '…',                       #string, not displayed
            description => '…',                       #string, displayed
            usage       => …,                         #nonnegative integer
            maximum     => …,                         #optional, nonnegative integer
            formatter   => 'format_bytes_per_second', #optional; if defined, the value is passed through the specified formatter for display
            url         => '…',                       #optional, to link to a URL
            after       => '…',                       #optional, to display immediately after another entry
        },
        # insert any other modules here …
    );
}

1;

Parameters

Key Type Description Possible Values Example
id string Required The identifier. The system uses this value to determine the item display order. If you create two or more items with the same id value, the last item will display in the interface and this function will ignore the others. You must use a unique id value across all modules. ASCII, spaces, and the underscore (_) character. The system uses the following default ResourceUsage IDs:
  • disk_usage
  • cachedmysqldiskusage (MySQL® Disk Usage)
  • bandwidth
  • addon_domains
  • subdomains
  • aliases
  • email_accounts
  • mailing_lists
  • autoresponders
  • forwarders
  • email_filters
  • ftp_accounts
  • mysql_databases
Notes:
  • For each item, you can only use the before or the after keys, not both.
  • If you create a custom item that uses any of the above values for the id key, the custom item will replace the default item.
  • When you create a new item, you can enter the item's id value as a value for the before or after parameter.
new item id
description string Required The text to display to users in the interface. Note: This function converts all lowercase strings to start case (all words start with a capital letter). For example, a value of new custom stat will display New Custom Stat in the interface. ASCII, spaces , and the underscore ( _ ) character. new item description
usage integer Required The amount of the resource that the item uses. Note: Items whose usage values approach the maximum value display at the top of the statistics bar.
  • A positive integer.
  • 0
1
maximum integer The maximum value of the range for the item. The system defaults to unlimited and displays the infinity symbol () in the interface if any of the following conditions are true:
  • You do not include this key.
  • You do not supply a value.
  • You enter undef.
  • A positive integer.
  • 0

    Note: If you enter a string for the maximum key instead of an integer, the function will display NaN.
100
formatter string Applies units to the usage value based on the specified formatter. If you do not include this key, the system will not display any units to the user.
  • format_bytes — This function will convert the usage value into a storage format (for example, MB or GB).
  • format_bytes_per_second — This function will convert the usage value into a storage format per second (for example, 2048 displays 2 KB/s).
    Important: Any unrecognized value will cause an error.
format_bytes
app string A link that will redirect the user to a specific cPanel interface. If you do not include this key, the item will not include a link. A valid app key in the specified format. For a list of available app keys, use WHM API 1's get_users_links function. Backups_Home
url string A link that will redirect the user to a valid domain. If you do not include this key, the item does not include a link. A valid URL. Warning: The URL must contain the https:// or http:// protocol. https://www.example.com
before string Display this item before another item. Note: For each item, you can only use the before or the after key, not both. If you do not supply a value for or include this key, this feature will display these keys after all others. A valid ResourceUsage or custom item's ID. This value must exactly match the ResourceUsage item's id value or your custom item's id value. Otherwise, the system inserts the item at the default location. disk_usage
after string Display this item after another item. Note: For each item, you can only use the before or the after key, not both. If you do not supply a value for or include this key, this feature will display these keys after all others. A valid ResourceUsage or custom item's id. This value must exactly match the ResourceUsage item's id value or your custom item's id value. Otherwise, the system inserts the item at the default location. cachedmysqldiskusage