Development Guides Home >> Quickstart Development Guide

Tutorial - Add a Link to the cPanel Interface

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).

• 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 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.

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.svg file.
• Line 10 specifies that this icon will appear as part of the custom_support_group group.
• 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 https://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" : "https://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" : "https://support.example.com"
   },
   {
      "icon" : "knowledgebase.svg",
      "group_id" : "custom_support_group",
      "order" : 10002,
      "name" : "Support Knowledge Base",
      "type" : "link",
      "id" : "support_kb",
      "uri" : "https://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.json
• knowledgebase.svg
• supportcontact.svg

To compress these files into a .tar.gz file, run the following command:

tar -cvzf supporticons.tar.gz supporticons/*

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

Jupiter

To install the icons, run the following command:

/usr/local/cpanel/scripts/install_plugin supporticons.tar.gz --theme jupiter

If the installation succeeds, the script returns the following output:

Installing to jupiter
Cleaning up temporary directories
Running sprite_generator
Plugin installed ok

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: