Development Guides Home >> Quickstart Development Guide

Tutorial - Create a New cPanel Interface

Introduction

This tutorial uses Template Toolkit to create a new cPanel interface.

The examples below use the Jupiter theme's master template, which creates new interfaces that integrate seamlessly with the look and feel of the main cPanel interface.

For help creating a new cPanel interface in PHP, read our Create a New cPanel Interface in PHP tutorial.

Create a Template Toolkit file with the Jupiter header and footer

To begin, create a new Template Toolkit file. This file must use the .html.tt file extension.

Use Template Toolkit's WRAPPER directive to add Jupiter's header and footer to the template file.

[% WRAPPER '_assets/master.html.tt' -%]
[% END %]

Add the interface's header and image

Add the app_key attribute to the WRAPPER directive. The app_key value must match the interface's file value in the dynamicui.conf file.

[% WRAPPER '_assets/master.html.tt'
    app_key = 'backup'               # The file value from the dynamicui.conf file.
-%]
[% END %]

Add the interface's title

Add the page_title attribute to the WRAPPER directive. You can set any string as the page_title value. If no value is provided, the page title defaults to the item_desc value in the dynamicui.conf file.

[% WRAPPER '_assets/master.html.tt'
    app_key = 'backup'               # The file value from the dynamicui.conf file.
    page_title = "Cloud Backup"      # The page title.
-%]
[% END %]

Add stylesheets

Add the page_stylesheets attribute to the WRAPPER directive. Use this attribute to apply one or more CSS stylesheets to the interface.

Enter the CSS files' paths relative to the /usr/local/cpanel/base/frontend/jupiter/ directory.

[% WRAPPER '_assets/master.html.tt'
    app_key = 'backup'               # The file value from the dynamicui.conf file.
    page_title = "Cloud Backup"      # The page title.
    page_stylesheets = [             # CSS files.
        'backup/cloud_backup.css',   # Path relative to the /usr/local/cpanel/base/frontend/jupiter/ directory.
        'backup/controller_styles.css'
    ]
-%]
[% END %]

Add scripts

Add the page_scripts attribute to the WRAPPER directive. Use this attribute to call one or more scripts that will run when the interface loads.

Enter the scripts' paths relative to the /usr/local/cpanel/base/frontend/jupiter/ directory.

[% WRAPPER '_assets/master.html.tt'
    app_key = 'backup'               # The file value from the dynamicui.conf file.
    page_title = "Cloud Backup"      # The page title.
    page_stylesheets = [             # CSS files.
        'backup/cloud_backup.css',   # Path relative to the /usr/local/cpanel/base/frontend/jupiter/ directory.
        'backup/controller_styles.css'
    ]
    page_scripts = [                 # Scripts.
        'custom/example.js',         # Path relative to the /usr/local/cpanel/base/frontend/jupiter/ directory.
    ]
-%]
[% END %]

Add CSS styles

Use this attribute to add page-specific CSS styles using the Template Toolkit's BLOCK directive.

The example below:

Adds a css_block style.
Processes the css_code_block style.

[% WRAPPER '_assets/master.html.tt'
    app_key = 'backup'               # The file value from the dynamicui.conf file.
    page_title = "Cloud Backup"      # The page title.
    page_stylesheets = [             # CSS files.
        'backup/cloud_backup.css',
        'backup/controller_styles.css'
    ]
    page_scripts = [                 # Scripts.
        'custom/example.js',
    ]
    page_styles = css_code_block     # Use the css_code_block style.
-%]
[% css_code_block = PROCESS css_block %]
[% BLOCK css_block %]
<style>
.help {
    padding: 10px;
}
</style>
[% END # css_block END %]
[% END # WRAPPER END %]

Add JavaScript

Add the page_js attribute to the WRAPPER directive. Use this attribute to apply a JavaScript block to your template.

The example below:

Adds the js_block script to the template.
Processes the js_code_block .

[% WRAPPER '_assets/master.html.tt'
    app_key = 'backup'               # The file value from the dynamicui.conf file.
    page_title = "Cloud Backup"      # The page title.
    page_stylesheets = [             # CSS files.
        'backup/cloud_backup.css',
        'backup/controller_styles.css'
    ]
    page_scripts = [                 # Scripts.
        'custom/example.js',
    ]
    page_styles = css_code_block     # Use the css_code_block style.
    page_js = js_code_block          # Use the js_code_block script.
-%]
[% css_code_block = PROCESS css_block %]
[% BLOCK css_block %]
<style>
.help {
    padding: 10px;
}
</style>
[% END # css_block END %]
[% js_code_block = PROCESS js_block %]
[% BLOCK js_block %]
<script type="text/javascript">
    # Javascript example.
    window.addEventListener('load', (event) => {
        console.log('page is fully loaded');
    });
</script>
[% END # js_block END %]
[% END # WRAPPER END %]

Disable legacy cPanel styles, scripts, and CJT scripts

Set the include_legacy_stylesheets, include_legacy_scripts, and include_cjt attributes in the WRAPPER directive to 0 to exclude cPanel's legacy styles, scripts, and CJT scripts from the template.

This ensures that your template uses Jupiter's functionality, rather than styles and scripts from our deprecated Paper Lantern theme.

[% WRAPPER '_assets/master.html.tt'
    app_key = 'backup'               # The file value from the dynamicui.conf file.
    page_title = "Cloud Backup"      # The page title.
    page_stylesheets = [             # CSS files.
        'backup/cloud_backup.css',
        'backup/controller_styles.css'
    ]
    page_scripts = [                 # Scripts.
        'custom/example.js',
    ]
    page_styles = css_code_block     # Use the css_code_block style.
    page_js = js_code_block          # Use the js_code_block script.
    include_legacy_stylesheets = 0   # Exclude legacy yui stylesheets.
    include_legacy_scripts = 0       # Exclude yui utilities and x3 optimized scripts.
    include_cjt = 0                  # Exclude legacy cjt scripts.
-%]
[% css_code_block = PROCESS css_block %]
[% BLOCK css_block %]
<style>
.help {
    padding: 10px;
}
</style>
[% END # css_block END %]
[% js_code_block = PROCESS js_block %]
[% BLOCK js_block %]
<script type="text/javascript">
    # Javascript example.
    window.addEventListener('load', (event) => {
        console.log('page is fully loaded');
    });
</script>
[% END # js_block END %]
[% END # WRAPPER END %]

Set the directory prefix cPanel variable

Set the CPANEL.CPVAR.dprefix variable. This ensures that links to other cPanel interfaces, search results from the cPanel interface's search menu, and certain menus function correctly.

[% WRAPPER '_assets/master.html.tt'
    app_key = 'backup'               # The file value from the dynamicui.conf file.
    page_title = "Cloud Backup"      # The page title.
    page_stylesheets = [             # CSS files.
        'backup/cloud_backup.css',
        'backup/controller_styles.css'
    ]
    page_scripts = [                 # Scripts.
        'custom/example.js',
    ]
    page_styles = css_code_block     # Use the css_code_block style.
    page_js = js_code_block          # Use the js_code_block script.
    include_legacy_stylesheets = 0   # Exclude legacy yui stylesheets.
    include_legacy_scripts = 0       # Exclude yui utilities and x3 optimized scripts.
    include_cjt = 0                  # Exclude legacy cjt scripts.
-%]
[% SET CPANEL.CPVAR.dprefix = "../" %]
[% css_code_block = PROCESS css_block %]
[% BLOCK css_block %]
<style>
.help {
    padding: 10px;
}
</style>
[% END # css_block END %]
[% js_code_block = PROCESS js_block %]
[% BLOCK js_block %]
<script type="text/javascript">
    # Javascript example.
    window.addEventListener('load', (event) => {
        console.log('page is fully loaded');
    });
</script>
[% END # js_block END %]
[% END # WRAPPER END %]