Development Guides Home

Guide to cPanel Plugins in the Paper Lantern theme

Introduction

Note:

This document only applies to plugin development in the Paper Lantern theme. To use plugins in the Jupiter theme, read our Guide to cPanel Plugins in the Jupiter Theme documentation.


cPanel plugins add new functionality to the cPanel interface. Third-party developers can add features to the cPanel Home interface that link to new cPanel interfaces or to other files or locations. For information about WHM plugins, read our Guide to WHM Plugins documentation.

Note:

Make certain that your applications respect user privacy. We strongly recommend that you anonymize any data that you collect for analysis. For more information about how cPanel, L.L.C. handles private data, read our cPanel Analytics documentation.


Plugin Development workflow

This section describes how to create and install your plugins for the cPanel interface.

How to create your plugin

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

Note:

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


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

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 represents paper_lantern or another theme on the server.
  • Access these files from https://example.com:2083/frontend/theme/filename, where:

    • example.com represents the domain or IP address.
    • theme represents paper_lantern or another theme on the server.
    • filename represents the interface file's name.

For example, if you create a custom Support interface in the 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
Note:

Additional resources to help you match custom interfaces to the cPanel interface exist in our experimental User Interface Style Guide.


How to install your plugin

  1. Add the plugin to the cPanel interface. For the Paper Lantern theme, this requires that you create an install.json file.
  2. Write a plugin installation script.
  3. Optional: 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. However, the install_plugin script supports .tar.gz, .bzip, and .zip files, and uncompressed directories.
  4. Use the /usr/local/cpanel/scripts/install_plugin script to install the plugin.

    • Note: The /usr/local/cpanel/scripts/install_plugin script extracts plugin files for you but does not move the files to the directories. Instead, your installation script must perform this action.

Installation scripts

Write any 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. Use the /usr/local/cpanel/scripts/install_plugin script to install the plugin.
  5. Remove any installation files that remain.

The install_plugin script

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.


cPanel & WHM version 11.44 introduced the install_plugin script, which you can use to install a plugin to a theme.

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

/usr/local/cpanel/scripts/install_plugin plugin_file --theme theme_name

In this command, plugin_file represents the compressed plugin installation file (a .tar.gz, .bzip, or .zip file or an uncompressed directory), and theme_name represents paper_lantern or another theme on the server.

When you run this script consider the following information:

  • The script only installs the plugin to one theme. To install the plugin to a second theme, you must run the script again with the correct options.
  • If you do not specify the --theme option and a theme, the script attempts to install the plugin to the default interface with the install.json method. If you do not specify a theme and the compressed plugin file does not contain an install.json file, the installation will fail.
  • The /usr/local/cpanel/scripts/install_plugin script extracts plugin files for you, but does not move the files to the directories. Instead, your installation script must perform this action.

Plugin Development Guides