Knowledgebase

Overview

You can brand your users' cPanel interfaces with your custom logos and images to convey your company's brand message. Your changes are stored as a style in the cPanel system.

A style has a distinctive appearance, but also retains the same underlying functionality as the default cPanel interface.

Important concepts

Style — Also known as a skin, the style contains the graphics that determine the appearance of a user's cPanel interface.

Theme — In cPanel software, the theme is the larger, skeletal framework to which the style, or skin, is applied.

 Warning: Do not edit an existing theme. If you do this, your changes will be overwritten the next time cPanel updates. Instead, create a new theme with your desired changes.

Styles

Styles are available to resellers. If the web host allows it, resellers may create or use their own styles to reflect their company's brands.

Custom styles reside in the /home/$reseller/cpanelbranding/$theme/$style file.

 Note: In this example:

• $reseller represents the reseller's home directory.
• $theme represents the theme for which you have created a style. (For example x3.)
• $style represents the name that you have given your style.

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

The cPanel Branding Editor

Resellers and root users can use the cPanel Branding Editor to customize their styles.

For more information on how to use the Branding Editor, read our Branding Editor documentation.

The Branding Editor interface is typically sufficient for most resellers' branding needs.

The top of the Branding Editor interface.

Apply styles to multiple accounts

1. Locate the style that you wish to apply to your accounts.
2. Click Apply to All Accounts

This method eliminates the need for you to download, then re-upload, the style to all of your resellers' accounts.

Copy styles to another server

The Branding Editor allows you to:

1. Download your style to your desktop as a file.
2. Upload the theme to another server.

 
The Download/delete branding style interface.

 
The Upload a new branding style interface.

Edit Style Sheet

Cascading Style Sheets (CSS) govern the appearance of web pages. Because the cPanel interface is a series of web pages, you can use CSS on the cPanel interface as you would on a typical web page.

If you wish modify the CSS for a cPanel style, use the Branding Editor's Edit Style Sheet feature.

 
The Edit Style Sheet screen.

Edit HTML pages

This feature allows you to customize the appearance of your users' cPanel interfaces. If you wish for the cPanel interface to mimic the appearance of your website, you can edit HTML pages

 
The bottom of the Edit HTML Pages interface.

You can use API2 calls to allow components of the graphical interface to indirectly interact with the cPanel source code. For more information, read our Branding Editor documentation.

These API functions reference files that are stored in a particular style's path, and then include the appropriate HTML content in the page. For example:

• <cpanel Branding="image(cp)"> — Checks for the image file cp that ends in .gif, .png, or .jpg.
• <cpanel Branding="text(supportinfo)"> — Includes the text stored within supportinfo.txt. You can insert HTML code here.

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 can cache these files into arbitrary textured images (sprites). This will significantly improve performance.

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

Edit preview images

Preview images are not generated automatically. To create preview images, use the Edit Preview Images feature.

This feature allows you to upload screen captures of your theme. These screen captures will appear to users in the main Branding Editor screen, so they can see what their cPanel interface will look like before they select a style.

This is especially useful if you intend to distribute your styles.

Force resellers to use your style

This is useful if your style reflects branding that would not be offered in other styles.

To force resellers to use your style:

1. To apply your style to all users, select the Apply to All Accounts option in the Branding Editor.
2. Select the Apply to all resellers' accounts as well checkbox in the resulting pop-up window.
3. Click Submit.
4. Remove the ability for resellers to use the Change Style option. 

Plugins

A cPanel plugin is a custom application that you can link directly from your users' cPanel interfaces.

After you generate the installation file, follow the steps in our How to Install Plugins documentation.

Why Plugins are preferred

Plugins are style- and theme-independent. As a result, your plugin will be available whether you use a theme bundled with cPanel & WHM, or a third-party theme.

This theme independence also means that your Plugins will likely function without maintenance for several years.

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 their users from becoming confused.

How to disable specific webmail clients

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:

• To hide Roudcube — #roundcube_cell {display:none;}
• To hide SquirrelMail — #sqmail_cell{display:none;}
• To hide Horde — #horde_cell{display:none;}

Custom login themes

You can edit the screens your customers see before they log in to cPanel, WHM, or webmail. These screens are known as the login themes. The default themes are:

• 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

To create your own theme, perform the following steps:

1. Run the mkdir /usr/local/cpanel/base/unprotected/mycpanel command to create a new directory called /usr/local/cpanel/base/unprotected/mycpanel
2. Run the following command to copy the new directory to the /usr/local/cpanel/base/unprotected/cpanel/ directory:

   cp -pR /usr/local/cpanel/base/unprotected/cpanel /usr/local/cpanel/base/unprotected/mycpanel

3. Edit the themes that you wish to customize.

 Important: In your custom login theme directory, you will need to edit the header and footer files.

To display your custom login theme, select a value for the Default login theme setting in WHM's Tweak Settings interface. This value defaults to cpanel.

 Important: Your custom login theme will not be the default login interface unless you disable HTTP authentication in Tweak Settings. However, HTTP authentication is considered to be more secure than the alternative cookie-based authentication.

Headers and footers

The header and footer files, like the login pages named 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 page.

• The header provides all of the code that comes before the login message. The header filenames are:
  • header.html — cPanel login.
  • header_webmaild.html — webmail login.
  • header_whostmgrd.html — WHM login.
• The footer provides all the code that comes after the login message. The footer filenames are:
  • footer.html — cPanel login.
  • footer_webmaild.html — webmail login.
  • footer_whostmgrd.html — WHM login.

Custom CSS and images

To edit the login theme's CSS, edit the style.css file in your login theme's directory.

To place custom images in your login theme, place them in the /unprotected/images file.

The logout page

The appearance of the log out page is also governed by the login theme.

 Note: If you wish to redirect your users to another URL at log out, you do not need to create a custom theme. You can configure this through the Logout redirection URL option in Tweak Settings.

Deploy a custom login theme across multiple servers

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