Child pages
  • Guide to cPanel Plugins - Add Plugins to Version 11.44 and Later

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Introduction

Warning
titleWarning:

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


Excerpt

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
titleNote:

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
titleNote:

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

Include Page
LIB:_InstallPluginRoot
LIB:_InstallPluginRoot

Anchor
groups
groups
Add groups

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

Code Block
languagetext
linenumberstrue
    {
       "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
titleNote:

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.


Warning
titleImportant:

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
keystring

A key to uniquely identify cPanel interfaces and their associated assets for the cPanel Analytics program.

Note
titleNote:

We added this parameter in cPanel & WHM version 78.

In dynamicui files, this parameter becomes the key key.

A valid string.

Generally, this value matches the item's file value.

feature_name
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
titleNote:

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

Anchor
icons
icons
Add icons

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

Code Block
languagetext
linenumberstrue
    {
       "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 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.

Note
titleNotes:
  • 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
titleNote:

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.


Warning
titleImportant:

For icons, this value must be link.


link
idstring

Required

The item's internal name.

A string value.

Note
titleNote:

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 or a filepath relative to the paper_lantern theme's directory.


my_plugin_directory/index.live.pl
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
titleNote:

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
titleNote:

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

A key to uniquely identify cPanel interfaces and their associated assets for the cPanel Analytics program.

Note
titleNote:

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

Anchor
example
example
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:

Code Block
languagetext
linenumberstrue
[
    {
       "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"
    }
] 

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: