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:

Create the install.json file.
Add one or more groups to the install.json file.
Add one or more features to the install.json file.
Add one or more Account Enhancements to the install.json file.
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 icons are only supported as of cPanel & WHM version 102.	`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 `.svg`files. 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. In cPanel & WHM versions 98 and 100, icons will not display.	`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. Note: We added this parameter in cPanel & WHM version 76. 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: