Adding Icons and Groups to cPanel Interfaces

cPanel 11 and the x3 theme provided the ability to dynamically add icons and groups of icons in the cPanel interface. New groups and icons can be created to appear on a per-server or per-reseller basis.

Note: We strongly recommend using our utility for generating these icons, this utility does not offer the same flexibility as editting dynamic UI files directly

Introduction

The system works from dynamicui files that can be added in a variety of locations:

• Per-server — /usr/local/cpanel/base/frontend/$theme/dynamicui/dynamicui_$var.conf
  • In the example above, you will need to replace the following variables with their actual value:
    • $theme — The theme for which you are making the modification. In most cases, this value should be x3.
    • $var.conf — the name of the dynamic UI file, this should always be prefixed with dynamicui_
• Per-reseller — $resellerhomedir/cpanelbranding/$theme/dynamicui.conf
  • In the example above, you will need to replace the following variables with their actual value:
    • $resellerhomedir — The reseller's home directory corresponding to the reseller's interface you wish to modify.
    • $theme — The theme for which you are making the modification. In most cases, this value should be x3.

These can also be placed for various branding packages on the server:

• Per-server — /usr/local/cpanel/base/frontend/$theme/branding/$brandpkg/dynamicui.conf
  
• Per-reseller — $resellerhomedir/cpanelbranding/$theme/$brandingpkg/dynamicui.conf

dynamicui files are loaded in the following order:

• /usr/local/cpanel/base/frontend/$theme/dynamicui.conf
  
• /usr/local/cpanel/base/frontend/$theme/dynamicui/*dynamicui*.conf
  
• $resellerhomedir/cpanelbranding/$theme/dynamicui.conf
  
• /usr/local/cpanel/base/frontend/$theme/$brandingpkg/dynamicui.conf
  
• $resellerhomedir/cpanelbranding/$theme/$brandingpkg/dynamicui.conf
  

If any of these files contains a file key with the same name as a file key in a previously loaded dynamicui file, the previous file key will be overwritten.

An example of a dynamicui.conf file can be found in the following location:

• /usr/local/cpanel/base/frontend/x3/dynamicui.conf

Note: This is the configuration file that is responsible for generating the default cPanel interface. Edits will be overwritten by updates.

Adding Items to the cPanel Interface

In the cPanel interface, items function as links to particular features, such as Email Accounts or File Manager. In order to add an item to the cPanel interface, you will need to add a line in the dynamicui_$var.conf or dynamicui.conf file that describes the link to the custom feature you are adding. It should resemble the following:

description=>$LANG{'Webmail'},if=>!$ENV{'CPRESELLER'},feature=>webmail,file=>
webemail,group=>mail,height=>32,imgtype=>icon,itemdesc=>$LANG{'ASIWebmail'},
subtype=>img,type=>image,url=>webmaillogin.html,width=>32,itemorder=>2,searchtext=>
$LANG{'webmail-searchtxt'}

Note: The data should not contain line breaks. For display purposes, the example above may be wrapped.

As you can see from the example above, this line is a comma-separated list of key pairs that use => to associate keys and values. To view a list of required key pairs, click here. here to hide.

Key	Type	Value	Example
itemdesc	string	The name of the item as it would appear in the cPanel interface. Note: ExpVar Values are acceptable here.	Support
itemorder	integer	Describes the location of the item in the cPanel interface. Note: The lower the number, the higher up on the screen the item will appear. Negative values are acceptable	10000
group	string	The icon group in which the item will appear.	group_pref
url	string	The path to which the item will link.	http://support.example.com
description	string	The item description displayed in the Branding Editor. Note: ExpVar Values are acceptable here.	support link
if optional	string	A conditional that allows you to check configuration settings and determine whether or not the item should appear to the user. This key is useful for access control. Note: ExpVar Values are acceptable here	!$CONF{'skipawstats'} $CPDATA{'FEATURE-AWSTATS'}
searchtext optional	string	Additional keywords used with the x3 theme's Quick Find feature. Note: ExpVar Values are acceptable here	support
feature optional	string	Name of a feature the account must have access to in order for the item to be displayed.	support
acontent optional	string	Additional attributes to include in the item's <a> HTML tag.	target="_blank"
onclick optional	string	Any Javascript that should execute when the item's link is clicked.	show_optionselect('leechprotect'); return false;
module optional	string	Specifies a module in /usr/local/cpanel/Cpanel/ without which the item will not appear.	ImageManager

Example

If you wanted to add an icon that linked to http://support.example.com, you would need to add the following lines to the appropriate .conf file:

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

dynamicui files are processed on a per-line basis, meaning that the file would need to have the line breaks stripped to resemble the following:

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

Note: The data should not contain line breaks. For display purposes, the example above may be wrapped.

Because this item links to a support feature, you would need to make these edits in the following file:

• /usr/local/cpanel/base/frontend/x3/dynamicui/dynamicui_support.conf

You will need to provide the icon for the feature's link in the following location:

• /usr/local/cpanel/base/frontend/x3/branding/support.png
  Note: The only supported file formats are .png, .gif, and .jpg. .png is recommended.

Once the icon has been placed in /usr/local/cpanel/base/frontend/x3/branding/ you will need to run the following script by typing its path on the command line:

• /usr/local/cpanel/bin/rebuild_sprites

This will rebuild the sprite map used by cPanel, completing the installation process.

Adding Groups to the x3 Interface

In the cPanel interface, groups refer to groups of icons that link to similar features, such as the Mail or Domains sections.

Adding a group to an x3 interface requires a few keys and associated values. For a list of required key pairs, click here. here to hide.

Key	Type	Value	Example
groupdesc	string	The name of the group as it should appear in the cPanel interface. Note: ExpVar Values are acceptable here.	Custom Group
group	string	The name of the group as used for associated icons. Note: This name does not include the group_ prefix.	pref
grouporder	integer	A weight indicating where the group should appear in the cPanel theme. Note: The lower the number, the higher up on the screen the group will appear. Negative values are acceptable.	1
description	string	The group description which will appear in the x3 Branding Editor. ExpVar Values are acceptable here.	Custom Group

Remember: At this time, there are no themes that display group icons; however, it is very possible that group icons will be used in the future.

To add an icon to your group, you will need to use the same system of paired keys and values. For a list of required key pairs, click here. here to hide.

Key	Type	Value	Example
imgtype	string	Always set this key to icon.	icon
subtype	string	Always set this key to img.	img
type	string	Always set this key to image.	image
file	string	The name of the icon file, which should reside in /usr/local/cpanel/base/frontend/$theme/branding/ Note: This value should not include the file extension.	support
height	integer	The height of the icon. Note: When using the x3 theme, always set this value to 32.	32
width	integer	The width of the icon. Note: When using the x3 theme, always set this value to 32.	32

Example

To add a group of icons to the cPanel interface, you will need to add the following to a dynamicui file:

groupdesc=>Support,
description=>Grouping for support icons,
grouporder=>-10,
group=>support_menu,
imgtype=>icon,
subtype=>img,
type=>image,
file=>support,
height=>32,
width=>32

dynamicui files are processed on a per-line basis, meaning that the file would need to have the new lines stripped to resemble the following:

groupdesc=>Support,description=>Grouping for support icons,grouporder=>-10,group=>
support_menu,imgtype=>icon,subtype=>img,type=>image,file=>support,height=>32,
width=>32,

Note: The data should not contain line breaks. For display purposes, the example above may be wrapped.

After completing this process, your group should appear in the cPanel interface.

Removing Icons or Groups from the cPanel Interface

At times, you may need to hide an icon or group from a reseller's users, or users within a particular branding package. You can do this by creating an entry within a dynamicui file loaded after the one that creates the icon or group you wish to hide. This new entry contains a "skipobj" key with "1" as a value. For example:

file=>filemanager,skipobj=>1