Introduction
This tutorial adds an icon that links to an external location to the cPanel interface. For the purposes of this tutorial, an "external location" is a location outside of cPanel & WHM (for example, a support or sales website).
Important:
To add icons to multiple themes, you must repeat steps 5 and 6 for each theme, and you must provide separate icons for each theme, in the appropriate sizes.
Notes:
- This tutorial is for servers that run cPanel & WHM version 11.44 or later.
- For a tutorial to create an authorized integration link, use our Create an Integration Link tutorial.
Add a link to the cPanel interface
Create an install.json file.
To begin, create a blank install.json file.
The cPanel interface uses this file to add icons and groups to cPanel's dynamicui.conf file system automatically.
Add a custom group to the install.json file.
Add the desired group information to the install.json file.
In this example:
- Line 3 sets the group's display name to
Support. This is the name that displays in the cPanel interface. - Line 4 sets the group's display order to
11. Groups with lower display orders display higher in the cPanel interface. - Line 5 sets the group's type. This value must always be
group. - Line 6 sets the group's internal name as
custom_support_group. This is the name that cPanel uses to associate a group with its icons.
[
{
"name" : "Support",
"order" : 11,
"type" : "group",
"id" : "custom_support_group"
}
]
Add an icon to the install.json file.
Add the desired icon and link information to the install.json file.
Note:
For the Paper Lantern theme, the image must be 48x48 pixels and image files must use the .png file format (cPanel & WHM version 58 and earlier) or .svg file format (cPanel & WHM version 60 and later).
In this example:
- Line 9 sets this icon as the
supportcontact.svgfile. - Line 10 specifies that this icon will appear as part of the
custom_support_groupgroup. - Line 11 sets the icon's order to
10000. Icons with a lower order appear first in their assigned groups. - Line 12 sets the icon's display name as
Contact Support. This text displays with the specified image in the cPanel interface. - Line 13 sets the icon's type. This value must be
link. - Line 14 sets the icon's internal name.
- Line 15 sets the link's URL. This link will direct cPanel users to
http://support.example.com.
[
{
"name" : "Support",
"order" : 11,
"type" : "group",
"id" : "custom_support_group"
},
{
"icon" : "supportcontact.svg",
"group_id" : "custom_support_group",
"order" : 10000,
"name" : "Contact Support",
"type" : "link",
"id" : "contact_support",
"uri" : "http://support.example.com"
}
]
Optional: Add more icons.
You can add multiple icons to the same group and install.json file. The example below adds a second icon, which links to an external knowledge base, to the custom_support_group group.
[
{
"name" : "Support",
"order" : 11,
"type" : "group",
"id" : "custom_support_group"
},
{
"icon" : "supportcontact.svg",
"group_id" : "custom_support_group",
"order" : 10000,
"name" : "Contact Support",
"type" : "link",
"id" : "contact_support",
"uri" : "http://support.example.com"
},
{
"icon" : "knowledgebase.svg",
"group_id" : "custom_support_group",
"order" : 10002,
"name" : "Support Knowledge Base",
"type" : "link",
"id" : "support_kb",
"uri" : "http://supportkb.example.com"
}
]
Compress the install.json file and icon files.
Create a directory that contains the install.json file, and the icon files for each icon.
For this tutorial's examples, this directory is the supporticons directory, which contains the following files:
install.jsonknowledgebase.svgsupportcontact.svg
To compress these files into a .tar.gz file, run the following command:
tar -cvzf supporticons.tar.gz supporticons/*
Note:
This command compresses all of the directory's contents. Before you run this command, make certain that the directory only contains the files that you wish to compress.
If the command succeeded, it returns the following output:
a supporticons/install.json a supporticons/knowledgebase.svg a supporticons/supportcontact.svg
Run the /usr/local/cpanel/scripts/install_plugin script to install the plugin.
Select a tab to view the correct command for that cPanel theme:
To install the icons to the Paper Lantern theme, run the following command:
/usr/local/cpanel/scripts/install_plugin supporticons.tar.gz --theme paper_lantern
If the installation succeeds, the script returns the following output:
Installing to paper_lantern Cleaning up temporary directories Running sprite_generator Plugin installed ok
Important:
Due to the permissions that the /usr/local/cpanel/scripts/install_plugin script requires in order to access the necessary files, only the root user can run this script successfully.
To install the icons to the deprecated x3 theme, run the following command:
/usr/local/cpanel/scripts/install_plugin supporticons.tar.gz --theme x3
If the installation succeeds, the script returns the following output:
Installing to x3 Cleaning up temporary directories Running sprite_generator Plugin installed ok
Important:
Due to the permissions that the /usr/local/cpanel/scripts/install_plugin script requires in order to access the necessary files, only the root user can run this script successfully.
View the new icons in the cPanel interface.
When users log in to the cPanel interface, the new icons will now display:
The new icons in the Paper Lantern theme.
Remember:
To add icons to multiple themes, you must repeat steps 5 and 6 for each theme, with the appropriate icon files and command.