Child pages
  • Guide to Testing Custom Code - Styles
Skip to end of metadata
Go to start of metadata

Introduction

This guide explains the basics of how to troubleshoot issues with cPanel styles. This document lists appropriate test steps for most custom code, and helpful information to troubleshoot common problems. Make certain that you evaluate the testing requirements of your own code, and allow its functionality to determine the appropriate steps. 

Warning:

cPanel Technical Support cannot always assist third-party developers with problems that relate to custom code. For this reason, always test your projects thoroughly before you attempt to use them on production servers. 

Testing steps


Note:

Because the testing requirements of custom code differ, this document begins with the assumption that you have already discovered problems. 

Check to ensure that the accounts possess the correct permissions.

The cPanel interface uses account permissions and ownership to determine the available styles for each cPanel user.

  • All cPanel accounts on the server can access the root user's styles, which must exist in the /var/cpanel/customizations/styled directory.
  • Only cPanel accounts that a specific reseller owns can view that reseller's styles, which must exist in the /var/cpanel/reseller/styled directory, where reseller represents the reseller's username.

Note:

When you upload styles via WHM's Customization interface (WHM >> Home >> cPanel >> Customization), the system uploads the style to the correct directory for the authenticated user.

For example, if the bob reseller uploads the stylish style via the WHM interface, the system automatically stores it in the /var/cpanel/bob/styled/stylish directory.

 


 

Check to ensure that you applied the style.

Unless you set a style as the global default style, or as the default style for a reseller, the style will not display by default. Check to ensure that you have properly applied the style to the account that you wish to view it in.

  • For more information about how to apply the style as the default style, read our Customization and Guide to cPanel Interface Customization - Apply Styles documentation.
  • To apply a style to a specific account through the cPanel interface, perform the following steps:

    1. Log in to cPanel as the desired user. 
    2. Navigate to cPanel's Change Style interface (cPanel >> Home >> Preferences >> Change Style ).
    3. Click Apply for the desired style.
  • To apply a style to a specific account through the command line, perform the following steps:

    1. Log in to the server via SSH as the desired user. 
    2. Run the following command, where username represents the cPanel account's username, and path_to_style represents the absolute path to the style that you wish to apply:

      ln -s path_to_style /home/username/var/cpanel/styled/current_style

      For example, to apply the /var/cpanel/customizations/styled/mystyle style for the username user, run the following command:

      ln -s /var/cpanel/customizations/styled/mystyle /home/username/var/cpanel/styled/current_style

 


 

Troubleshoot common issues

Errors when you attempt to upload a style.


Problem:

When you attempt to upload a style in WHM's Customization interface (WHM >> Home >> cPanel >> Customization ), the interface returns an error and does not upload the style.

Solution:

This problem occurs when WHM detects a problem with the style that you attempted to upload.

  • Make certain that the style file that you attempt to upload is a valid .tar.gz tarball file.
  • Make certain that the style's files exist within a directory within the style tarball.
  • Make certain that the style tarball contains either a styles.css file or a styles.min.css file.

For more information about all of these requirements, read our Guide to cPanel Interface Customization - cPanel Style Development documentation.

One or more style files will not load after manual upload.


Problem:

After you upload a style via the command line, the style does not function properly.

Solution:

Many problems may occur if the style's file permissions are not correct. Check to ensure that the style directory, subdirectories, and files all use 755 permissions.

Preview image does not display.


Problem:

A style that should contain a preview image displays the cPanel-provided filler preview image instead in cPanel's Change Style interface (WHM >> Home >> Preferences >> Change Style).

Solution:

This problem generally occurs due to bad file permissions or file types:

  • Check to ensure that the preview image file uses 755 permissions.
  • Check to ensure that the preview image file is a .svg or .png image file.