Advanced Guide to Branding the cPanel Interface

One way to convey your company's brand messaging and encourage brand loyalty is to brand your users' cPanel interfaces with your custom logos and images. Your custom branding changes are stored as a style in the cPanel system.

A style may have a distinctive appearance, but it retains the same underlying functionality as the default cPanel interface.

This document provides helpful information for web hosts interested in branding their users' cPanel interfaces.

Important concepts

Style: Also known as a skin, the style contains the graphics that determine the look and feel of a user's cPanel interface.

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

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

Styles

Styles are available to resellers. If the web host allows it, a reseller may create or use his or her own style to reflect his or her company's brand.

Custom styles reside in /home/$reseller/cpanelbranding/$theme/$style

• $reseller — The reseller's home directory.
• $theme — The theme you have created a style for. Usually, this will be x3.
• $style — The name you have given your style.

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

Theme managers (such as the Universal Theme Manager in WHM) cannot edit styles; they only allow you to edit the style's underlying theme.

The cPanel Branding Editor

Resellers and root users can use the cPanel Branding Editor to customize their styles. We have written detailed instructions for using the Branding Editor? .

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

The top of the Branding Editor screen.

Copy styles to multiple accounts

Copying your styles to /usr/local/cpanel/base/frontend/$theme/branding/$style/ will make the style available to all accounts on the server, where $theme is the theme the style is designed for (typically x3) and $style is the name of your style.

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

Using the Branding Editor, you can:

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

The "Download/delete branding style" screen.

The "Upload a new branding style" option.

Alternatively, you can simply copy the file to another server via SSH.

Edit style-sheet

CSS, or cascading style sheets, govern the appearance of web pages. Since the cPanel interface is merely a series of web pages, you can use CSS on the cPanel interface as you would on a typical web page.

The Branding Editor's Edit Style-sheet feature allows you to modify the CSS of the cPanel style.

The "Edit Style Sheet" screen.

It may be difficult to determine which CSS code you need to edit. In this case, the Firefox plugin Firebug is a very useful tool to help you find the CSS code you wish to edit. You can download Firebug at http://getfirebug.com/.

Tip: How individual resellers can disable specific webmail clients

The cPanel webmail interface inherits the CSS of the user's cPanel account. Thus, if you wish to disable a particular webmail application for your users, you can do so by adding 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;}

Edit HTML pages

This feature allows you to substantially customize the appearance of your users' cPanel interfaces. By editing HTML pages, you can transform the cPanel interface to mimic the appearance of your website. All of these pages can contain calls to the cPanel & WHM APIs.

The bottom of the "Edit HTML Pages" screen.

API1 and API2 allow components of the graphical interface (including styles) to indirectly interact with the cPanel source code. Customizing API calls from the Branding Editor can substantially modify the appearance of the cPanel interface.

For example, these API functions reference files stored in the path of a particular style, and then include the appropriate HTML content into the page.

• <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 sprites, significantly improving performance.

We strongly recommend using <cpanel Branding> tags rather than directly linking to existing images on your website.

Edit preview images

Preview images are not generated automatically. You must use the Edit Preview Images feature to create them.

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

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

Forcing 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. Apply your style to all users by using the Apply to All Accounts option in the Branding Editor.
2. Click 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. You can do this using the Feature Manager in WHM.

Plugins

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

Creating a Plugin is very simple, thanks to our Install File Generator. .

Once you've generated the installation file, be sure to follow the instructions in our documentation on installing Plugins.

Why Plugins are preferred

Plug-ins 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 your Plugins are likely to continue functioning without maintenance for years to come.

Changing or removing functionality from cPanel

Some hosting providers, such as those offering inexpensive hosting with limited features, prefer to charge their users for certain functions. For other web hosts, the technical limitations of their unique setup requires them to remove certain functions to prevent their users from becoming confused.

If you wish to remove functions, you can do so in the WHM Feature Manager. Please see our instructions on creating and editing feature lists using the Feature Manager.

The WHM Feature Manager.

Custom login themes

You can edit the screens your customers see before logging into 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, simply copy the cpanel directory (/usr/local/cpanel/base/unprotected/cpanel/) to a new directory, such as /usr/local/cpanel/base/unprotected/mycpanel. From there, you may edit themes as desired.

Important: You will need to edit the header and footer files in your custom login theme directory as well.

Once you have edited your login theme, you can set it to display using the Tweak Settings interface. Locate the option that reads:

The login theme to display for cPanel Login.

In the text box, type the name of the directory that holds your custom login theme (such as, continuing the example above, mycpanel).

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. While cookie-based authentication is considered secure, it is not as secure as HTTP authentication. Please weigh this security consideration against your need for a custom login theme.

Headers and footers

The header and footer files, like the login pages named above, reside in the directory for your custom theme. These files serve to wrap code around the login message, and provide the overall theming of the Login page.

• The header provides all 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

You can edit the login theme's CSS by editing the style.css page in your login theme's directory.

You can also place custom images in your login theme, by placing them in /unprotected/images.

The logout page

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

Note: If you simply wish to redirect your users to another URL at logout, you do not need to create a custom theme. You can configure this via the Tweak Settings option that reads:

Redirect user to the following URL upon logout of the cPanel interface.

Deploy a custom login theme across multiple servers

It is very simple to deploy a custom login theme across multiple cPanel & WHM servers. Simply copy the files to your other cPanel & WHM server(s). Then, set each server's login theme via Tweak Settings, as explained above.

Helpful resources

YUI — The Yahoo! User Interface library is the JavaScript library that cPanel & WHM uses to power the Ajax components of the graphical cPanel interface. Understanding YUI is useful if you wish to add Ajax functionality to cPanel.

cPanel API Basics — Here you will find documentation on cPanel's API1 and API2. Not all functions in the themes have been updated to API2, so there are some API1 functions remaining. You will recognize API2 functions since they are typically (but not always) of the format Module::function rather than Module="function..."