WHMCS 8.1 introduces a powerful new functionality for Client Area themes and Order Form templates that allows for parent-child relationships. Themes control the look and feel of the Client Area interfaces in WHMCS. Customizing them lets you provide a seamless experience for your customers by matching your company's branding in the WHMCS Client Area. Order Form templates, on the other hand, control the way the products and cart appear when your customers make purchases.

Our new and expanded system for parent-child relationships allows you to apply customisations by only overriding the template files you wish to change. This drastically reduces the number of files that you need to create for a custom template. This, in turn, makes it easier to track, maintain, and manage your custom templates during updates, minimizing the amount of time you spend on both initial development and updates. That's why we're making child themes the recommended method to customize WHMCS's Client Area in WHMCS 8.1 and later.

Parent themes include files, dependencies, or other assets that child themes can use without the need to duplicate them. WHMCS 8.0 and earlier included a simpler concept of inheritance that was limited to order forms. Now, we've expanded it to themes, including providing inheritance for CSS and JavaScript files. This means that you could update a theme or order form with as little as a theme.yaml file and the CSS or JavaScript file you want to update, no .tpl files involved.

You can create very simple child themes for many purposes. For example, you could add a site tracker to the footer of a default theme using only the footer.tpl file and a theme.yaml file, or you could pair contact.tpl with a theme.yaml file to provide additional contact information to users. Once you're using your new system theme or order form in the WHMCS interface, WHMCS will use the files in your custom template, if they exist, and then pull the remaining files from the parent theme, creating the final look and feel of your Client Area. This drastic reduction in customized files will save frontend developers time, both during development and when maintaining the theme and upgrading to new WHMCS versions.

For child themes, all you need is a new directory, a theme.yaml file, and copies of the files you want to customize or override.

It's easy to make a child theme. Just follow these steps:

1. Start by creating a new directory within the templates directory. The directory name can only contain lowercase letters, numbers, hyphens, and underscores.

2. Create a theme.yaml file. This will indicate that the theme is a child theme by specifying the parent theme to use. For example:

The theme.yaml file has many options, but it must contain, at minimum, the theme name (to display in the interface) and the parent theme's directory name.

3. Create a css/custom.css file. If you plan to make any CSS-related changes, you will need to create this file. If you won't be touching any CSS, you can skip this step. For example, to customize the background color in the Client Area, you could add these lines to a newly-created css/custom.css file:


4. Make your customizations. We recommend copying the necessary files from the parent theme if you're using an existing file. For example, to update the footer, copy footer.tpl from the parent theme into your new theme's directory.

With just those few changes, your theme will be ready to preview and then start using. You can preview themes by appending ?systpl=theme-name to the URL for your Client Area, making sure, of course, to replace theme-name with your theme's directory name.

In the WHMCS interface, you can select your default theme at Configuration > System Settings > General Settings in the General tab. The list of themes in the System Theme menu will automatically include the two WHMCS-shipped default themes (Six and Twenty-One) as well as any custom themes that you've saved to the templates directory.

WHMCS will automatically check for any incompatibilities between your selected theme and the order form templates you use, ensuring a good experience for your customers. If there are incompatibilities, the WHMCS interface will display a warning in the interface and will update your settings to use a compatible order form template. Compatibility checks will only find incompatibilities, however, if the theme developer made use of the new theme dependencies feature.

If you already have an existing theme or order form in place, there's no special update required for continued use beyond the usual maintenance for changed template files in the version. It will keep working as though nothing has changed when you upgrade to WHMCS 8.1. If you have time for updates, though, leveraging these changes could save you time and effort later in maintaining your customizations.

Ready to try the new system? You can find more information on developing custom themes, including new Smarty functions and code examples, in our Developer Documentation.