Knowledgebase

Introduction

cPanel plugins add new functionality to the cPanel interface. Third-party developers can add icons to the cPanel Home interface that link to new cPanel interfaces or to other files or locations.

Plugin development workflow

When you create a cPanel plugin, we recommend that you use the following workflow:

1. Create your custom application (the plugin's backend code).

2. Create the plugin's interfaces.

   Note:

   In cPanel & WHM version 54 and later, if your custom interfaces require jQuery, you must include that code in require() blocks. For more information, read our Guide to cPanel Interface Customization - jQuerydocumentation. 

3. Add the plugin to the cPanel interface.

   For plugins on servers that run cPanel & WHM version 11.42 and earlier, write a plugin installation script.

   • For the x3 theme, add items directly to the dynamicui files.

   • For the Paper Lantern theme, create an install.json file.
5. Compress your plugin for distribution.
   • The compressed file contains the application source files, the plugin registration file, and the installation script. 
   • We recommend that you compress your plugin as a tarball ( .tar.gz ) file.

6. For plugins on servers that run cPanel & WHM version 11.44 and later, use the /usr/local/cpanel/scripts/install_plugin script to install the plugin.

   Note:

   The /usr/local/cpanel/scripts/install_plugin script does not extract plugin files for you. Instead, your installation script must perform this action. 

Plugin files

cPanel interfaces can include HTML, Template Toolkit, PHP, or CGI files. 

• Store plugin interface files in the /usr/local/cpanel/base/frontend/theme/ directory, where theme is x3 or paper_lantern.
• Access these files from https://example.com:2083/frontend/theme/filename , where example.com is the domain or IP address, theme is x3 or paper_lantern, and filename is the interface file's name.

For example, if you create a custom Support interface in a customsupport.html file, use the following locations:

• Store the file in the following location on the server:/usr/local/cpanel/base/frontend/paper_lantern/customsupport.html
• Access this file at the following URL: https://example.com:2083/frontend/paper_lantern/customsupport.html

Installation scripts

Write plugin installation scripts in your preferred programming language.

Plugin installation scripts must perform the following functions:

1. Verify that the system is compatible with the plugin. For example, confirm that the server uses a compatible version of cPanel & WHM.

2. Use the wget or curl commands to download the compressed plugin file.
3. Extract the compressed file's contents to the appropriate locations.

4. Perform the necessary tasks to add the plugin to the cPanel Home interface.

5. Remove any installation files that remain.

The install_plugin script

cPanel & WHM version 11.44 introduced the install_plugin script, which eliminates the need for custom installation scripts.

To use this script to install a plugin to cPanel, run the following command:

In this command, example.tar.gz is the compressed plugin installation file, and theme_name is the cPanel theme to install to (x3 or Paper Lantern).