Child pages
  • Guide to cPanel Plugins - Add Plugins to Version 11.44 and Later
Skip to end of metadata
Go to start of metadata

Introduction

Warning:

You must use this method when you install plugins to the Paper Lantern theme.

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

Note:

You can also create a cPanel plugin with WHM's cPanel Plugin File Generator interface (WHM >> Home >> Development >> cPanel Plugin File Generator).

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 icons to the install.json file.
  4. Include the complete install.json file in your compressed installation file.

Note:

When you use the install.json file method, you must use the install_plugin script to add your plugin to the cPanel interface. 

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.

Add groups

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

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

Use the following parameters to configure groups: 

ParameterTypeDescriptionPossible valuesExample
namestring

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
orderinteger

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
typestring

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 groups, this value must be group.

group
idstring

Required

The group's internal name.

In dynamicui files, this parameter becomes the group key.

A string value.

 

my_plugins
implementsstring

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 icons

Icon 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" : "http://support.example.com"
       "target" : "_blank"
    },

Use the following parameters to configure each icon:

ParameterTypeDescriptionPossible valuesExample
iconstring

Required

The icon file name.

In dynamicui files, this parameter becomes the file key.

The icon's filename and file extension.

Notes:

  • In cPanel & WHM version 11.44 through 58, Paper Lantern only supports .png files.
  • In cPanel & WHM version 60 and later, Paper Lantern icons support either .png or .svg files.
  • In cPanel & WHM version 60 and later, 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
namestring

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
orderinteger

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
typestring

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 icons, this value must be link.

link
idstring

Required

The item's internal name.

A string value.

Note:

This value can only contain letters, numbers, hyphens (-), and underscores (_).

plugin_one
uristring

Required

The location to which the item links.

In dynamicui files, this parameter becomes the url key.

A valid URL.

http://support.example.com
group_idstring

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
targetstring

Specifies where in the browser to open the plugin.

Note:

This parameter is only available in cPanel & WHM version 11.50 and later.  

A valid HTML target value or frame name. _blank
featuremanagerstring

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
featurestring

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
descriptionstring

The plugin's description.

This parameter defaults to the name parameter's value.

A string value.A test plugin.

 

Add icons to an existing group

You can also add plugin icons to groups that already exist in Paper Lantern. Use the following group names to add an icon to an existing group: 

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

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:

[
    {
       "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",
       "uri" : "http://example.com/plugin1",
	   "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",
       "uri" : "http://example.com/plugin2",
	   "featuremanager" : 1,
	   "feature" : "plugin_two",
	   "description" : "Plugin Two"
    }
] 

Create a plugin interface for the Paper Lantern theme 

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