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

This document is for a previous release of cPanel & WHM. To view our latest documentation, visit our Home page.

For cPanel & WHM 11.46

Overview

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

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, use WHM's  cPanel Plugin File Generator  interface (Home >> Development >> cPanel Plugin File Generator).

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

Themes

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

Styles

Also known as a skin, the style contains the graphics that determine the appearance of a user's cPanel interface. If the web host allows it, resellers may 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, 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 home directory.
  • theme is the theme for which you created a style (for example, x3).
  • style is the name of your style.

Call cPanel API 2 in a style to use includes for images and text

You can use cPanel API 2 calls 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.

The main reason to use these tags is performance. When you place these files in the style's directory and call them with <cpanel Branding> tags, cPanel caches these files into arbitrary textured images (sprites). This significantly improves performance.

Warning:

We strongly recommend that you use <cpanel Branding> tags. Do not directly link to existing images on your website.

Examples

The following example checks for the cp image file that ends in the .gif.png, or .jpg file extension.

<cpanel Branding="image(cp)">

The following example includes text in the supportinfo.txt file. The supportinfo.txt file could also include HTML.

<cpanel Branding="text(supportinfo)">

Change or remove functionality 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.

If you wish to remove functions, 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.

If you wish 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 known as the login themes.

Notes:

  • The login theme also governs the appearance of the logout interface.
  • If you wish 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 that you wish 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, like the login theme files in the section above, reside in the directory for your custom theme. 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 the APIs that you can use with cPanel & WHM.