Introduction

This tutorial uses Template Toolkit to create a new WHM interface.
 The examples below use WHM's master template, which creates new interfaces that integrate seamlessly with the look and feel of the main WHM interface. 

This tutorial requires cPanel & WHM version 64 or later. Earlier versions of cPanel & WHM are not compatible with this tutorial.

Create a new WHM interface


Create a Template Toolkit file with the correct USE statements.

To begin, create a new Template Toolkit file. Generally, this file uses the .tmpl file extension.

  • Lines 2 and 3 use Template Toolkit's USE directive to load the Whostmgr and JSON modules, respectively.
  • WHM interfaces require these modules in order to load properly.
[%
USE Whostmgr;
USE JSON;
%]

 


 

Add correct handling for right-to-left locales.

By default, cPanel & WHM displays interfaces correctly for left-to-right locales.

If your plugin will support multiple locales, we strongly recommend that you configure the interface to correctly display right-to-left and left-to-right locales.

[%
USE Whostmgr;
USE JSON;

IF locale.get_html_dir_attr() == 'rtl';
SET rtl_bootstrap = Whostmgr.find_file_url('/3rdparty/bootstrap-rtl/optimized/dist/css/bootstrap-rtl.min.css');
END;
%]

 


 

 

Add WHM's wrappers.

Use Template Toolkit's WRAPPER directive to apply WHM's master template, title, and theme to the template file.

  • Line 9 uses the WRAPPER directive to set WHM's master template file.
  • Line 10 sets the interface's header text and localizes it. Use the header value to set the name at the top of the interface.
  • Line 11 applies WHM's Bootstrap theme.
[%
USE Whostmgr;
USE JSON;
 
IF locale.get_html_dir_attr() == 'rtl';
SET rtl_bootstrap = Whostmgr.find_file_url('/3rdparty/bootstrap-rtl/optimized/dist/css/bootstrap-rtl.min.css');
END;

WRAPPER 'master_templates/master.tmpl'
    header = locale.maketext("Example Plugin")
    theme='bootstrap';
%]

[% END %]

You can use additional flags to customize the way in which you include the master template, or the individual header and footer files. For more information and a full list of flags, read our Guide to WHM Plugins - Interfaces documentation.

 


 

Add stylesheets.

Add stylesheets to customize the appearance of your interface.

  • Line 9 uses Template Toolkit's SET directive to set the list of stylesheets.
  • Line 10 adds the rtl_bootstrap stylesheet, which you set in Step 2.
  • Line 11 adds the /libraries/fontawesome/css/font-awesome.min.css stylesheet, which allows your interface to load Font Awesome icons.
  • Line 16 adds this list of stylesheets to the WRAPPER directive.

Enter the CSS files' paths relative to the /docroot/ directory. 

[%
USE Whostmgr;
USE JSON;

IF locale.get_html_dir_attr() == 'rtl';
SET rtl_bootstrap = Whostmgr.find_file_url('/3rdparty/bootstrap-rtl/optimized/dist/css/bootstrap-rtl.min.css');
END;

SET styleSheets = [
    rtl_bootstrap,
    '/libraries/fontawesome/css/font-awesome.min.css'
    ];
 
WRAPPER 'master_templates/master.tmpl'
    header = locale.maketext("Example Plugin")
    stylesheets = styleSheets,
    theme='bootstrap';
%]

[% END %]

 


 

Add interface contents.

Add the contents of your plugin's interfaces. These contents may use any combination of Template Toolkit and other web languages.

[%
USE Whostmgr;
USE JSON;

IF locale.get_html_dir_attr() == 'rtl';
SET rtl_bootstrap = Whostmgr.find_file_url('/3rdparty/bootstrap-rtl/optimized/dist/css/bootstrap-rtl.min.css');
END;

SET styleSheets = [
    rtl_bootstrap,
    '/libraries/fontawesome/css/font-awesome.min.css'
    ];

WRAPPER 'master_templates/master.tmpl'
    header = locale.maketext("WHM Example Plugin")
    stylesheets = styleSheets,
    theme='bootstrap';
%]

<div class="callout callout-info">
Interface contents go here.
</div>

[% END %]