Page tree

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Table of Contents
excludeTutorials
stylenone

Introduction

This document explains how to create a module that displays custom statistics (items) in cPanel's Home interface. 

Create the custom module

Create a new module

Create a new /var/cpanel/perl/Cpanel/ResourceUsage/Custom/modulename.pm file where modulename represents your new module's name and add the following contents:

Note
titleNote:

Create a unique module name.


Code Block
languageperl
linenumberstrue
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

KeyTypeDescriptionPossible ValuesExample
id

string

 

The identifier. The system uses this value to determine the item display order.

Required

  • ASCII, the space (), and the underscore (_) characters.
new item id

description

string

 

What to display to users in the interface.

Note
titleNote:

This function coverts all lower-case 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.

Required

  • ASCII, the space (), and the underscore (_) characters.
new item description
usage

integer

 

The amount of the resource that the item uses.

Required

  • A positive integer.
  • 0
1
maximuminteger

The maximum value of the range for the item.

If you do not include this key, you do not supply a value, or if you enter undef, the system defaults to unlimited and displays the infinity symbol in the interface ( ).

  • A positive integer.
  • 0.
100
formatterstring

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).
Warning
titleImportant:

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 does not include a link.

A valid app key in the specified format. For a list of available app keys, run the WHM API 1 function get_users_links.

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
titleWarning:

The URL must contain the https:// or http:// protocol.


https://www.example.com
beforestring

Display this item before another item.

Note
titleNote:

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.

Warning
titleImportant:

This value must exactly match the ResourceUsage item's id or your custom item's id value. Otherwise, the system inserts the item at the default location.


disk_usage

afterstring

Display this item after another item.

Note
titleNote:

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 .

Warning
titleImportant:

This value must exactly match the ResourceUsage item's id or your custom item's id value. Otherwise, the system inserts the item at the default location.

 

 

cachedmysqldiskusage

ResourceUsage id
Anchor
ListOfStats
ListOfStats

Enter one the following values for either the before or after parameter to customize the sort order:

Note
titleNotes:
  • For each item, you can only use the before or the after key, not both.
  • If you create a custom item that uses any of the following 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 as a value for the before or after parameter.
  • disk_usage
  • cachedmysqldiskusage (MySQL® Disk Usage).
  • bandwidth
  • addon_domains
  • subdomains
  • aliases
  • email_accounts
  • mailing_lists
  • autoresponders
  • forwarders
  • email_filters
  • ftp_accounts
  • mysql_databases

Additional Information

Consider the following information when you design a custom module:

CatergoryNotes
Sort Order
  • The value of the before or after parameter must exactly match the ResourceUsage item’s id or your custom item's id value. This function sorts custom items to the bottom of the statistics bar if this value doesn’t match another item’s id.
  • Items whose usage value approaches the maximum value display at the top of the statistics bar.

Speed implications
  • The presence of the /var/cpanel/perl/Cpanel/ResourceUsage/Custom directory triggers each ResourceUsage API to call. Every time a user loads or refreshes the cPanel Home interface, this function 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.
  • Custom data modules execute on every cPanel Home interface page load. The system does not cache the data that custom modules poll. You can implement such a solution to improve load times.
Errors to avoid
  • If any item in a module fails, this function will not display any items from that module.
  • A failure in one module will not prevent the display of other modules.
  • If you create two or more items with the same id, the last item will display in the interface and this function will ignore the rest.
  • The id parameter must be unique across all modules.
Other considerations
  • The interface loads the information after the initial page load.
  • This function can process multiple modules.
  • If you enter a string for the maximum key instead of an integer, the function will display NaN.
  • We strongly recommend that you test this feature on any themes that you support (for example, Basic, Dark, Light, and Retro).