Development Guides Home >> Guide to cPanel Plugins

Guide to cPanel Plugins - Add Plugins to Legacy cPanel Versions

Introduction

cPanel & WHM version 11.42 and earlier requires you to manually add items to the dynamicui files. The dynamicui files contain information for each icon in the cPanel Home interface. When you add a plugin manually, the plugin will only be available in x3.

Warning:

This documentation describes how to add plugins to the deprecated x3 theme in cPanel & WHM version 11.42 and earlier.


We strongly recommend that you use the Paper Lantern theme and its install.json method to add items to the dynamicui files. The steps in this document will not function for the Paper Lantern theme or for cPanel & WHM version 11.44 and later.

Add dynamicui entries manually

To add a plugin directly to the dynamicui files, perform the following steps:

  1. Write one or more group dynamicui file entries.
  2. Write one or more icon dynamicui file entries.
  3. Add the entries to the appropriate group's dynamicui_*.conf file.
  4. For example, add the Support group's entry, and the entries for any Support group icons, to the /usr/local/cpanel/base/frontend/x3/dynamicui/dynamicui_support.conf file.
  5. Save icon image files to the /usr/local/cpanel/base/frontend/theme/branding/ directory, where theme is x3.
  6. Icon files must use the .png, .gif, or .jpg file formats. We strongly recommend that you use .png files.
  7. Icons must be 32x32 pixels.
  8. Run the /usr/local/cpanel/bin/rebuild_sprites command to rebuild the cPanel interface's sprite map.

Add groups

Each group entry in a dynamicui file will resemble the following example:

groupdesc=>Support,group=>support_menu,grouporder=>-10,description=>Group for support icons
Note:

Entries in dynamicui files cannot include line breaks. We strongly recommend that you localize any strings that you add to dynamicui files.


The dynamicui file entries include the following data, in the key=>value format:

Key Type Description Possible values Example
description string Required The group's description in the deprecated x3 theme's Branding Editor interface (cPanel >> Home >> Preferences >> Branding Editor). Group for support icons
group string Required The group name. Individual icon entries use this name with the group_ prefix. A string value. support_menu
groupdesc string Required The name of the group, as it will display in the cPanel interface. Support
grouporder integer Required The group's order in the cPanel interface. An integer that represents the order in which the group displays. Note: Groups with a lower grouporder value display first. 10

Add icons

Each icon entry in a dynamicui file will resemble the following example:

itemdesc=>Support,itemorder=>-100,group=>group_pref,url=>http://support.example.com,description=>support link,imgtype=>icon,subtype=>img,type=>image,file=>support,height=>32,width=>32
Note:

Entries in dynamicui files cannot include line breaks. We strongly recommend that you localize any strings that you add to dynamicui files.


The dynamicui file entries include the following data, in the key=>value format:

Key Type Description Possible values Example
itemdesc string Required The name of the item, as it will display in the cPanel interface. Support
itemorder integer Required The item's order in the cPanel interface. An integer that represents the order in which the item displays. Note: Items with a lower itemorder value will display first. -100
group string Required The icon group in which the item will appear. The prefix group_ and a valid group name. Note: Group entries include the group name, without the group_ prefix, as the group key's value. group_pref
url string Required The location to which the item links. A valid URL. http://support.example.com/
description string Required The item's description in the deprecated x3 theme's Branding Editor interface (cPanel >> Home >> Preferences >> Branding Editor). support link
if string A conditional value that checks configuration settings to determine whether the item displays. This key is useful to limit access to an item. One or more cPanel variable. !$CONF{'skipawstats'} $CPDATA{'FEATURE-AWSTATS'}
searchtext string A list of keywords for the item. support
feature string A feature that the user must have access to in order for the item to display. A valid feature name. support
acontent string Additional attributes to include in the item's <a> HTML tag. One or more valid HTML attributes. target="_blank"
onclick string JavaScript to execute when a user clicks on the item's link. Valid JavaScript code. show_optionselect('leechprotect'); return false;
module string A module that must exist in the /usr/local/cpanel/Cpanel/directory for the item to appear. A valid module name. ImageManager
touch string A touch file that must exist in the /var/cpanel/dynamicui/directory for the item to appear. Note: This key is only available in cPanel & WHM version 11.40 and later. A valid filename. filename
imgtype string The icon type. Important: You must set this value to icon. icon
subtype string The icon subtype. Important: You must set this value to img. img
type string The item type. Important: You must set this value to image. image
file string The icon file name. The icon's filename relative to the /usr/local/cpanel/base/frontend/x3/branding directory, without a file extension. support
height integer The icon's height. A positive integer that represents the icon's height, in pixels. Remember: You must set this value to 32. 32
width integer The icon's width. A positive integer that represents the icon's width, in pixels. Remember: You must set this value to 32. 3