- Created by Documentation, last modified on Dec 17, 2018
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:
- The
/home/username/var/cpanel/reseller/includes/
directory, whereusername
represents the reseller who owns that cPanel account. - The
/var/cpanel/customizations/includes/
directory. - 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, whereapp_key
represents the interface'sapp_key
value, displays immediately below the interface name at the top of the interface. - The
app_key_page_footer.html.tt
file, whereapp_key
represents the interface'sapp_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 anapp_key
value for cPanel's Home interface (Home). Use
dashboard
as anapp_key
value for cPanel's Dashboard interface.Note:
We removed cPanel's Dashboard interface in cPanel & WHM version 58.
- Use
notification
as anapp_key
value for cPanel's Notifications interface. - Use
statistics
as anapp_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:
- Use SSH to log in to the server as either the
root
user or the desired reseller account. Navigate to the
/home/username/var/cpanel/reseller/includes/
directory, whereusername
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.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, whereapp_key
represents the interface'sapp_key
value, displays immediately below the interface name at the top of the interface. - The
app_key_footer.html.tt
file, whereapp_key
represents the interface'sapp_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 theapp_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:
- Use SSH to log in to the server as either the
root
user or the desired reseller account. Navigate to the
/home/username/var/cpanel/reseller/includes/
directory, whereusername
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.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.
QuickLinks
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
-
Page:Tutorial - Customize the WHM User Interface with CSS — This tutorial customizes the appearance of a WHM interface theme.
-
Page:cPanel API 1 Functions - Branding::file — This function searches for a file within a theme and returns its URL.
-
Page:cPanel API 1 Functions - Branding::setupdirs — This function creates an account's
/cpanelbranding
directory and subdirectories, and sets its permissions. -
Page:cPanel API 1 Functions - Branding::image — This function displays a branding image's URL.
-
Page:cPanel API 1 Functions - Branding::killimg — This function removes an image from a branding package.