Advanced Branding for Login Pages

For cPanel *For cPanel & WHM 11.36 WHM 11.38*

The login themes use 2 applications, login and resetpass. Both of these applications access a parent template (main.tmpl and resetpass.tmpl, respectively), which in turn load sub-templates.

Important: All of the variables and functions listed in this document are global functions and variables. This is because Template::Toolkit does not allow scoping.

The login application

In the login application, the main.tmpl template is called on each page. The sub-templates are included into main.tmpl based on the value of the page_to_show parameter. These functions are only available in templates that use main.tmpl. You cannot access these functions and variables via resetpass.tmpl.

The resetpass application

In the resetpass application, the resetpass.tmpl template is loaded for each HTTP session. From there, the page_to_show parameter loads the sub-template to use.

Whenever the resetpass application sends a confirmation email, the resetpass-email.tmpl and resetpass-email-html.tmpl templates are used.

Globals

Global	Type	Description
locale	Cpanel::Locale hash object instance	This object corresponds to the locale that results from the logic described in the How is the user’s browser locale determined? section. Its methods and properties give values appropriate for the given locale. For example, in English, locale.numf('1000') will display 1,000, while in German it will show 1.000.
MagicRevision()	function	The MagicRevision() function is a caching system. A MagicRevision URL has a file's modification time embedded in the URL path. cpsrvd recognizes this path and removes it, serving the file as it was cached by the browser rather than re-loading the image from the disk, so long as no modification was made to the file. Using this function will improve load times for users and will decrease the system's disk I/O.
get_theme_url()	function	This function looks for requested files in /usr/local/cpanel/base/unprotected/ and /usr/local/cpanel/base/unprotected/$themename/ and serves the first match it finds. It will match against the file name requested with and without the application name. For example, if logo.png is requested, the function will also attempt to find logo_whostmgr.png. Note: This function does not pass values through MagicRevision(). You should pass URLs for page resources through the MagicRevision() function before they are printed on the page. For example: <img src="[% MagicRevision( get_theme_url('logo.png') ) %]" alt="logo">

How the user's browser locale is determined

cPanel & WHM 11.32 introduced a localized login screen that allows users to select a locale for their session on login. Several factors determine the locale that the user sees when logging in.

This section describes how the locale is determined whenever the user attempts to log into cPanel, WHM, or webmail.

1. The locale query string parameter, contained within the URL, receives the highest priority when determining the locale the user should see.
   • For example, https://example.com:2083/login?locale=ru would set the Russian locale on the login screen. This value will also set the session_locale cookie for the entire session, overriding the account's configured locale.
   • Note: session_locale cookies are valid for 1 year.
2. If the user's browser has already set the session_locale cookie, the login screen will use the specified locale at the login screen and during the application session.
3. If neither of the values above are configured and the browser sends the Accept-Language header, the login system will use the first valid locale that corresponds to the value of the Accept-Language header.
   • Note: Not all browsers allow this variable.
4. If no parameters above are configured, the login system will use the locale configured by the server_locale variable in /var/cpanel/cpanel.config. You can set server_locale using WHM Tweak Settings interface under the System tab.
5. If none of the conditions above are met, the login system will use the U.S. English locale by default.