Developer Documentation
Child pages
  • Guide to cPanel Interface Customization - UI Includes
Skip to end of metadata
Go to start of metadata

Guide to cPanel Interface Customization and Branding

Appkeys

Branding 

cPanel Style Development 

The styles.css File

Custom Icons and Logos

Apply Styles

Troubleshoot Custom Styles

jQuery

The Login Theme

Login Templates

Login Images

UI Includes

 

Introduction

UI includes add custom content to the header or footer of the cPanel interface. You can create UI includes for specific cPanel interfaces, or global UI includes that display on all of cPanel's interfaces. To add UI includes, create the desired Template Toolkit files in the appropriate directory on the server.

Directories

To add UI includes for all of a specific reseller's cPanel accounts, add files to the following directory, where username represents the reseller's username:

/home/username/var/cpanel/reseller/includes/

Note:

This directory does not exist by default. If it does not exist, create it. 

 

To add UI includes for every cPanel account on a server, add files to the following directory:

/var/cpanel/customizations/includes/

Note:

Only the root user can add global UI include files to the /var/cpanel/customizations/includes/ directory. 

Directory priority

Each time that a cPanel user loads one of cPanel's interfaces, the system displays the first available UI include file from the following directories:

  1. The /home/username/var/cpanel/reseller/includes/ directory, where username represents the reseller who owns that cPanel account.
  2. The /var/cpanel/customizations/includes/ directory.
  3. The /usr/local/cpanel/base/frontend/paper_lantern/includes/ directory, if it exists.

For example, if global_header.html.tt files exist in both the /home/username/var/cpanel/reseller/includes/ directory and the /var/cpanel/customizations/includes/ directory, the cPanel interface only displays the global_header.html.tt file from the /home/username/var/cpanel/reseller/includes/ directory.

Important:

We strongly recommend that you do not update files in the /usr/local/cpanel/base/frontend/paper_lantern/includes/ directory. If you modify these files, future updates to cPanel & WHM may overwrite your changes.

Template Toolkit filenames

Important:

  • UI include files can contain HTML and Template Toolkit. For more information, read our Guide to Template Toolkit documentation.
  • cPanel's File Manager interface (cPanel >> Home >> Files >> File Manager) does not display global or individual includes.
  • cPanel's Home interface uses three additional includes in the right sidebar. For more information, read our Home interface includes section.

Global include files

Global include files override the header or footer of every cPanel interface:

  • The global_header.html.tt file appears immediately below the main cPanel navigation at the top of the interface.

  • The global_footer.html.tt file appears immediately above the main footer navigation bar at the bottom of the interface.

    Note:

    In cPanel & WHM version 11.52 and later, the QuickLinks section of the navigation bar does not display by default. To use the global header include to add the QuickLinks section, read the QuickLinks section below.

 

Individual interface includes

Include files for individual interfaces display in a specific cPanel interface, as displayed in the diagram below:

  • The app_key_page_header.html.tt file, where app_key represents the interface's app_key value, displays immediately below the interface name at the top of the interface.
  • The app_key_page_footer.html.tt file, where app_key represents the interface's app_key value, displays immediately above the main footer navigation bar at the bottom of the interface.

Important:

The filename must include the interface's app_key value, an underscore (_), the string page, an underscore (_), the UI include position (header or footer), and the .html.tt extension. 

  • For example, to create a UI include header file for cPanel's Site Publisher interface (cPanel >> Home >> Domains >> Site Publisher), create the site_publisher_page_header.html.tt file in the appropriate directory.
  • For a complete list of app_key values for cPanel's interfaces, read our Guide to cPanel Interface Customization - Appkeys documentation.
  • Use home as an app_key value for cPanel's Home interface (Home).

  • Use dashboard as an app_key value for cPanel's Dashboard interface.

    Note:

    We removed cPanel's Dashboard interface in cPanel & WHM version 58. 

  • Use notification as an app_key value for cPanel's Notifications interface.
  • Use statistics as an app_key value for cPanel's Statistics interface.

Example

For example, to add a message to the header of cPanel's API Shell interface (cPanel >> Home >> Software >> API Shell) for all of a specific reseller's accounts, perform the following steps:

  1. Use SSH to log in to the server as either the root user or the desired reseller account.

  2. Navigate to the /home/username/var/cpanel/reseller/includes/ directory, where username represents the reseller's username.

    Note:

    This directory does not exist by default. Use the mkdir command to create this directory if it does not already exist on the server.

  3. Use your preferred text editor to create the api_shell_page_header.html.tt file and add the following contents:

    <div class="message">
   This message only appears in the API Shell interface!
</div>
<br/>

When you log in to cPanel as one of the accounts that that reseller owns, the message appears at the top of the interface:

cPanel's API Shell interface with a customized UI include header.

Individual interface includes

Include files for individual interfaces appear in a specific cPanel interface, as displayed in the diagram below:

  • The app_key_header.html.tt file, where app_key represents the interface's app_key value, displays immediately below the interface name at the top of the interface.
  • The app_key_footer.html.tt file, where app_key represents the interface's app_key value, displays immediately above the main footer navigation bar at the bottom of the interface.

Important:

The filename must include the interface's app_key value, an underscore (_), the string page, an underscore (_), the UI include position (header or footer), and the .html.tt extension. 

  • For example, to create a UI include header file for cPanel's Email Accounts interface (cPanel >> Home >> Email >> Email Accounts), create the accounts_page_header.html.tt file in the appropriate directory.
  • For a complete list of app_key values for cPanel's interfaces, read our Guide to cPanel Interface Customization - Appkeys documentation.
  • Use home as the app_key value for cPanel's Home interface (Home).

Example

For example, to add a message to the header of cPanel's API Shell interface (cPanel >> Home >> Software >> API Shell) for all of a specific reseller's accounts, perform the following steps:

  1. Use SSH to log in to the server as either the root user or the desired reseller account.

  2. Navigate to the /home/username/var/cpanel/reseller/includes/ directory, where username represents the reseller's username.

    Note:

    This directory does not exist by default. Use the mkdir command to create this directory if it does not already exist on the server. 

     

  3. Use your preferred text editor to create the api_shell_page_header.html.tt file and add the following contents:

    <div class="message">
   This message only appears in the API Shell interface!
</div>
<br/>

When you log in to cPanel as one of the accounts that that reseller owns, the message appears at the top of the interface:

cPanel's API Shell interface with a customized UI include header.

Home interface includes

The cPanel Home interface allows you to use three additional include files to display information in the cPanel sidebar as the following diagram demonstrates:

  • above_general_information.html.tt — The cPanel Home interface displays this information above the General Information section of the sidebar.
  • above_stats_bar.html.tt — The cPanel Home interface displays this information above the Statistics section of the sidebar.
  • below_stats_bar.html.tt — The cPanel Home interface displays this information below the Statistics section of the sidebar.

To add the QuickLinks section to the cPanel interface, add the following code to the global_header.html.tt file:

<nav id="quickLinks" class="navbar navbar-default navbar-subnav" role="navigation">
  <div class="container">
     <ul class="nav navbar-nav">
         <li>
            <a id="lnkQuickHome" href="[% CPANEL.CPVAR.dprefix %]index.html">
            [%- locale.maketext("Home") -%]
            </a>
         </li>
         [%- IF CPANEL.feature("sitepublisher") %]
         <li>
            <a id="lnkQuickDomains" href="[% CPANEL.CPVAR.dprefix %]site_publisher/index.html">
            [%- locale.maketext("Site Publisher") -%]
            </a>
         </li>
         [%- END -%]
         [%- IF CPANEL.feature("addondomains") %]
         <li>
            <a id="lnkQuickDomains" href="[% CPANEL.CPVAR.dprefix %]addon/index.html">
            [%- locale.maketext("Addon Domains") -%]
            </a>
         </li>
         [%- END -%]
         [%- IF CPANEL.feature("filemanager") %]
         <li>
            <a id="lnkQuickFilemgr" href="[% CPANEL.CPVAR.dprefix %]filemanager/index.html?showhidden=1&dir=/public_html"
target="_blank" >
            [%- locale.maketext("File Manager") -%]
            </a>
         </li>
         [%- END -%]
         [%- IF CPANEL.feature("popaccts") %]
         <li>
            <a id="lnkQuickEmail" href="[% CPANEL.CPVAR.dprefix %]mail/pops.html">
            [%- locale.maketext("Email") -%]
            </a>
         </li>
         [%- END %]
     </ul>
  </div>
</nav> 

To add the QuickLinks section to the cPanel interface, add the following code to the global_header.html.tt file:

<nav id="quickLinks" class="navbar navbar-default navbar-subnav" role="navigation">
  <div class="container">
     <ul class="nav navbar-nav">
         <li>
            <a id="lnkQuickHome" href="[% CPANEL.CPVAR.dprefix %]index.html">
            [%- locale.maketext("Home") -%]
            </a>
         </li>
         [%- IF CPANEL.feature("addondomains") %]
         <li>
            <a id="lnkQuickDomains" href="[% CPANEL.CPVAR.dprefix %]addon/index.html">
            [%- locale.maketext("Addon Domains") -%]
            </a>
         </li>
         [%- END -%]
         [%- IF CPANEL.feature("filemanager") %]
         <li>
            <a id="lnkQuickFilemgr" href="[% CPANEL.CPVAR.dprefix %]filemanager/index.html?showhidden=1&dir=/public_html"
target="_blank" >
            [%- locale.maketext("File Manager") -%]
            </a>
         </li>
         [%- END -%]
         [%- IF CPANEL.feature("popaccts") %]
         <li>
            <a id="lnkQuickEmail" href="[% CPANEL.CPVAR.dprefix %]mail/pops.html">
            [%- locale.maketext("Email") -%]
            </a>
         </li>
         [%- END %]
     </ul>
  </div>
</nav> 

 

 


cPanel Interface Customization 

Compatible with:

  • cPanel 11.46+
  • Paper Lantern (the default cPanel theme) only.

Warning:

Do not use this documentation to attempt to apply customizations to cPanel's deprecated x3 theme.

Related Documentation

cPanel, WebHost Manager, and WHM are registered trademarks of cPanel, Inc. for providing its computer software that facilitates the management and configuration of Internet web servers. ®2018 All rights reserved.