- Created by Documentation, last modified on Sep 18, 2018
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, 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.
Notes:
- Create a unique module name.
- The system can process multiple custom modules.
Your custom module's contents should resemble the following example:
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.
| ASCII, spaces, and the underscore ( Click to view a list of system id values... The system uses the following default
Notes:
| new item id |
| string
| Required The text to display to users in the interface. Note: This function coverts all lowercase strings to start case (all words start with a capital letter). For example, a value of | ASCII, spaces, and the underscore ( | new item description |
usage | integer
| Required The amount of the resource that the item uses. Note: Items whose |
| 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 (
|
Note: If you enter a string for the | 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. |
Important: Any unrecognized value will cause an error. |
|
app | string | A link that will redirect the user to a specific cPanel interface. If you do not include this key, the item does not include a link. | A valid app key in the specified format. For a list of available app keys, run WHM API 1's |
|
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://www.example.com
|
before | string | Display this item before another item. Note: For each item, you can only use the If you do not supply a value for or include this key, this feature will display these keys after all others. | A valid This value must exactly match the |
|
after | string | Display this item after another item. Note: For each item, you can only use the If you do not supply a value for or include this key, this feature will display these keys after all others. | A valid This value must exactly match the |
|
cPanel Plugins
About cPanel Plugins
- cPanel plugins add custom features to the cPanel interface.
- Each cPanel theme has different requirements for cPanel plugins.
Compatible with:
- cPanel 11.32+
Related Documentation
-
Page:Guide to cPanel Plugins - The dynamicui Files — cPanel's Home interface uses the
dynamicui
file system to display icons and groups. -
Page:Guide to cPanel Plugins - Add Plugins to Legacy cPanel Versions — cPanel & WHM version 11.42 and earlier requires you to manually add items to the
dynamicui
files. -
Page:Guide to cPanel Variables — The LiveAPI system and
dynamicui
files can access cPanel's global variables. -
Page:Tutorial - Create a New Paper Lantern Interface in PHP — This tutorial uses PHP to create a new cPanel interface for the Paper Lantern theme.
-
Page:Tutorial - Add a Link to the cPanel Interface — This tutorial adds an icon that links to an external location to the cPanel interface.