Page tree
Skip to end of metadata
Go to start of metadata

For cPanel & WHM version 11.52

Overview

 

This document provides information for web hosts who wish to brand their users' cPanel interfaces and require more features than cPanel's Branding Editor interface (Home >> Preferences >> Branding Editor) offers.

You can brand your users' cPanel interfaces with your custom logos and images to convey your company's brand message. The system stores your changes to the cPanel default themes as styles. A style has a distinctive appearance, but retains the same functionality as the default cPanel interface.


Plugins

A cPanel plugin is a custom application that you can link directly from your users' cPanel interfaces. Plugins are style- and theme-independent. As a result, your plugin is available whether you use a cPanel-provided theme or a third-party theme.

To create a plugin for x3, use WHM's x3 Plugin File Generator interface (Home >> Development >> x3 Plugin File Generator).

After you generate the installation file, follow the steps in our Guide to cPanel Plugins documentation.

Themes

In cPanel & WHM software, the theme is the larger, skeletal framework to which the system applies the style.

We recommend that you use the x theme for WHM, the x3 or paper_lantern themes for cPanel, and the x3mail theme for Webmail.

Styles

The style, also known as a skin, contains the graphics that determine the appearance of a user's cPanel interface. Web hosts may also allow resellers to create or use their own styles to reflect their company's brands.

Styles are theme-specific. For example, if you create a style for the x3 theme or paper_lantern theme, it will not work on a third-party theme.

Note:

The location of each style file uses the following format:

/home/reseller/cpanelbranding/theme/style

In this example:

  • reseller is the reseller's username.
  • theme is the theme for which you created a style (for example, x3).
  • style is the name of your style.

To customize a Paper Lantern style, follow the directions in our Tutorial - Create a Custom cPanel Style documentation.

Use cPanel API 2's Branding module to use includes for images and text

You can use cPanel API 2 cPanel API 2's Branding module functions or UAPI's Branding module functions to allow components of the graphical interface to indirectly interact with the cPanel source code. These API functions reference files in a particular style's path, and then include the appropriate HTML content in the page.

When you place these files in the style's directory and call them with cPanel Template Toolkit tags ( <cptt Branding>), cPanel caches these files into arbitrary textured images, or sprites. This significantly improves performance.

Warning:

  • cPanel API 2 and UAPI functions that use Template Toolkit tags vary widely in code syntax and in their output. For more information, read our cPanel Template Toolkit documentation.
  • We strongly recommend that you do not directly link to existing images on your website.

Change or remove features from cPanel

Some hosting providers, such as those who offer inexpensive hosting with limited features, prefer to charge their users for certain functions. For other web hosts, the technical limitations of their unique setups require them to remove certain functions to prevent user confusion.

To remove features, use WHM's Feature Manager interface (Home >> Packages >> Feature Manager).

Disable a webmail client

The cPanel webmail interface inherits the CSS of the user's cPanel account.

To disable a particular webmail application for your users, add the following code to the appropriate style's Edit style-sheet page:

Webmail clientCode to add
Roundcube
#roundcube_cell{display:none;}
SquirrelMail
#sqmail_cell{display:none;}
Horde
#horde_cell{display:none;}

Login themes

You can edit the interface that your customers see when they log in to cPanel, WHM, or Webmail. These interfaces are the login themes.

Notes:

  • The login theme also governs the appearance of the logout interface.
  • To redirect your users to another URL after they log out, you do not need to create a custom theme. Instead, use the Logout redirection URL setting in the Redirection section of WHM's Tweak Settings interface (Home >> Server Configuration >> Tweak Settings).

The following files contain the default login themes:

ServiceDefault login theme file
cPanel /usr/local/cpanel/base/unprotected/cpanel/login_cpaneld.html
WHM /usr/local/cpanel/base/unprotected/cpanel/login_whostmgrd.html
Webmail/usr/local/cpanel/base/unprotected/cpanel/login_webmaild.html

Create a custom login theme

To create your own theme, perform the following steps:

  1. Run the following command to clone the default login theme and create the new mycpanel theme:

    cp -pR /usr/local/cpanel/base/unprotected/cpanel /usr/local/cpanel/base/unprotected/mycpanel
  2. Edit the themes to customize.

    • For more information about how to edit login headers and footers, read the Headers and footers section below.
    • To edit the login theme's CSS style, edit the style.css file in your login theme's directory.
    • To use custom images in your login theme, place them in the /unprotected/images file.
  3. To display your custom login theme, select a value for the Default login theme setting in the Display section of WHM's Tweak Settings interface (Home >> Server Configuration >> Tweak Settings). This value defaults to cpanel.

    Important:

    To deploy a custom login theme across multiple cPanel & WHM servers, copy the files to each of your servers. Then, set each server's login theme in WHM's Tweak Settings interface.

Headers and footers

The header and footer files reside in your custom theme's directory. These files wrap code around the login message, and provide the overall theme of the Login interface.

Note:

The header file provides all of the code before the login message, while the footer file provides all of the code after the login message.

The following table lists the location of the files for each service:

ServiceHeader file locationFooter file location
cPanel header.html footer.html
Webmail header_webmaild.html
footer_webmaild.html
WHMheader_whostmgrd.html footer_whostmgrd.html

 

Additional resources

  • YUI — cPanel & WHM uses the Yahoo! User Interface library to power the Ajax components of the graphical cPanel interface. It is useful to understand YUI if you wish to add Ajax functionality to cPanel.
  • Quickstart Development Guide — Learn about cPanel & WHM's API functions.