Development Guides Home >> Guide to cPanel Plugins

Guide to cPanel Plugins - Add Plugins

Introduction

Note:
  • You must use this method when you install plugins.
  • You can also create a cPanel plugin with WHM's cPanel Plugin File Generator interface ( WHM >> Home >> Development >> cPanel Plugin File Generator )

cPanel & WHM uses an install.json file to add groups and features. This file passes information to cPanel's dynamicui files when you install your plugin. While you can also add items directly to Jupiter's dynamicui files, we strongly recommend that you use the install.json file method.

The install.json file

To create an install.json file for your plugin, perform the following steps:

  1. Create the install.json file.
  2. Add one or more groups to the install.json file.
  3. Add one or more features to the install.json file.
  4. Add one or more Account Enhancements to the install.json file.
  5. Include the complete install.json file in your compressed installation file .
Important:
  • When you use the install.json file method, you must use the install_plugin script to add your plugin to the cPanel interface.
  • 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.

Add groups

Group entries in install.json files appear similar to the following example:

{
   "name" : "Custom Group",
   "icon" : "group.svg"
   "order" : 11,
   "type" : "group",
   "id" : "my_plugins",
   "implements" : "Filemanager_home"
}

Use the following parameters to configure groups:

Parameter Type Description Possible values Example
name string Required
The name of the group, as it will display in the cPanel interface. In dynamicui files, this parameter becomes the groupdesc key.
A string value. Custom Group
icon string Required
The icon file name. In dynamicui files, this parameter becomes the file key.
The icon's filename and file extension.
Note:
  • Jupiter group icons must be a .svg file type.
  • Group icons must be 32x32 pixels.
group.svg
order integer Required
The group's order in the cPanel interface. In dynamicui files, this parameter becomes the grouporder key.
An integer that represents the order in which the group displays.
Note:
Groups with a lower order value display first.
11
type string Required
The item's type. This value determines whether the installation process converts the item into a group entry in the dynamicui files.
Important:
For groups, this value must be group.
group
id string Required
The group's internal name. In dynamicui files, this parameter becomes the group key.
A string value. my_plugins
key string A key to uniquely identify cPanel interfaces and their associated assets for the cPanel Analytics program. In dynamicui files, this parameter becomes the key key. A valid string. Generally, this value matches the item's file value. feature_name
implements string The app_key value that the create_user_session and get_users_links functions use when you register the plugin. The app_key value to override.
Note:
For a complete list of the variables to use for the app_key parameter, read our Guide to cPanel Interface Customization - Appkeys documentation.
FileManager_Home

Add features

Feature entries in install.json files appear similar to the following example:

{
   "icon" : "one.svg",
   "group_id" : "my_plugins",
   "order" : 10000,
   "name" : "Support",
   "type" : "link",
   "id" : "plugin_one",
   "uri" : "my_plugin_directory/index.live.pl",
   "target" : "_blank"
}

Use the following parameters to configure each feature:

Parameter Type Description Possible values Example
icon string Required
The icon file name. In dynamicui files, this parameter becomes the file key.
The icon's filename and file extension.
Note:
  • Jupiter icons support either .png or .svgfiles. We recommend that you upload one of each that uses same root filename (for example, file_manager.png and file_manager.svg). If the .svg file is not available, cPanel will use the .png file.
  • Icons must be 48x48 pixels.
one.svg
name string Required
The name of the item, as it will display in the cPanel interface. In dynamicui files, this parameter becomes the itemdesc key.
A valid string. Support
order integer Required
The item's order in the cPanel interface. In dynamicui files, this parameter becomes the itemorder key.
An integer that represents the order in which the item displays.
Note:
Items with a lower itemorder value display first.
10000
type string Required
The item's type. This value determines whether the installation process converts the item into a group entry or an icon entry in the dynamicui files.
Important:
For features, this value must be link.
link
id string Required
The item's internal name.
A string value. Note: This value can only contain letters, numbers, hyphens (-), and underscores (_). plugin_one
uri string Required
The location to which the item links. In dynamicui files, this parameter becomes the url key.
A valid URL or a filepath relative to the jupiter theme's directory.
Note:
Your filepath must end with live and one of the following suffixes:
  • live.pl
  • live.rb
  • live.py
  • live.cgi
  • live.php
my_plugin_directory/index.live.pl
group_id string Required
The group in which the item will appear. In dynamicui files, this parameter becomes the group key.
A valid group name.
  • In install.json files, this is the desired group's id value.
  • In dynamicui files, this is the desired group's group value.
my_plugins
target string Specifies where in the browser to open the plugin. A valid HTML target value or frame name. _blank
featuremanager integer Whether to register this item in WHM's Feature Manager interface (WHM >> Home >> Packages >> Feature Manager). This parameter defaults to 1.
  • 1 — Register this item in the Feature Manager interface.
  • 0 — Do not register this item in the Feature Manager interface.
1
feature string The plugin's name. This parameter defaults to the id parameter's value. A string value.
Note:
This value can only contain letters, numbers, hyphens (-), and underscores (_).
examplefeature
description string The plugin's description. This parameter defaults to the name parameter's value. A string value. A test plugin.
key string A key to uniquely identify cPanel interfaces and their associated assets for the cPanel Analytics program. In dynamicui files, this parameter becomes the key key. A valid string. Generally, this value matches the item's file value. feature_name

Add features to an existing group

You can also add plugin features to groups that already exist in Jupiter. Use the following group names to add a feature to an existing group:

  • files
  • databases
  • domains
  • email
  • metrics
  • security
  • software
  • advanced
  • preferences

Example

The following example file adds the My Group group to the cPanel interface, with icons that link to the Plugin One and Plugin Two interfaces:

[
    {
      "icon" : "group.svg"
       "order" : 11,
       "name" : "My Group",
       "type" : "group",
       "id" : "my_plugins"
    },
    {
       "icon" : "one.svg",
       "group_id" : "my_plugins",
       "order" : 1,
       "name" : "Plugin One",
       "type" : "link",
       "id" : "plugin_one",
       "key" : "feature_name",
       "uri" : "my_plugin_directory/index.live.pl",
       "featuremanager" : 1,
       "feature" : "examplefeature",
       "description" : "A test plugin."
    },
    {
       "icon" : "two.svg",
       "group_id" : "my_plugins",
       "order" : 2,
       "name" : "Plugin Two",
       "type" : "link",
       "id" : "plugin_two",
       "key" : "feature_name",
       "uri" : "my_plugin_directory/index.html.pl",
       "featuremanager" : 1,
       "feature" : "plugin_two",
       "description" : "Plugin Two"
    }
]

Add Account Enhancements

Account Enhancement entries in install.json files appear similar to the following example:

{
    "type": "account_enhancement",
    "name": "My Plugin Deluxe Edition",
    "id": "my-plugin-deluxe-edition",
    "plugin_id": "my_plugin"
}

Use the following parameters to configure each enhancement:

Parameter Type Description Possible values Example
name string Required
The name of the enhancement, as it will display in the cPanel interface.
A valid string. My Plugin Deluxe
type string Required
The item's type.
account_enhancement account_enhancement
id string Required
The ID of the enhancement.
A valid string. my-plugin-deluxe-edition
plugin_id string Required
The ID of the plugin that supports the enhancement. Should match the groups ID.
A valid string. my_plugin

Create a plugin interface

To create a plugin that integrates seamlessly with the Jupiter interface, read the following tutorials: