Back to Blog Posts

Theme and Template Compatibility

By Sarah / December 11th, 2020

Alongside the new parent/child themes, WHMCS 8.1 introduces the ability to define dependencies and provided assets for system themes and order form templates. Themes control the look and feel of user interfaces in WHMCS, with separate themes for the Client Area and Admin Area. Order form templates control the way the products and cart appear when your customers make purchases. Customizing them lets you provide a unique experience for your customers by matching your company's branding in the WHMCS Client Area.

New in WHMCS 8.1, WHMCS can determine the compatibility of System Themes and the Order Form Templates you choose. This takes a lot of the guesswork out of developing customizations, and helps to ensure that you can easily tell which order form template dependencies can be fulfilled by what a certain system theme provides. Much of this functionality also applies to parent/child relationships, but the relationship between system themes and order form templates is where we expect this to be most useful.

Specifying Dependencies in Themes and Order Form Templates
An order form template's dependencies can't be fulfilled unless they are supplied by the selected system theme. As long as the asset is available in the system theme, however, the order form template will work as expected. For ease of reference, the system theme's shareable assets can be listed in its theme.yaml file's provides section. Similarly, order form templates can list the assets they require in their theme.yaml file's dependencies section.

For example, this relationship could resemble this example of an example-theme system theme and the order-form order form template:

In the example above*, example-theme includes Bootstrap 4.5.2 and lists it in a theme.yaml file so that its presence is detectable by WHMCS. In turn, order-form needs and will get Bootstrap 4 it from its parent theme and lists it in its theme.yaml file. While order-form can receive Bootstrap from example-theme, it's important to note that example-theme can't get anything from order-form. So, if example-theme didn't provide Bootstrap, you would either receive a warning (assuming both theme.yaml files explicitly showed the incompatibility) or the order form template would not function correctly. Keep reading for more about WHMCS's new compatibility checks.

* Please note that the examples above are not full theme.yaml files and would need additional content, as in our Developer Documentation, to become fully functional.

Order form template developers will already be familiar with the theme.yaml system that we implemented in WHMCS 6.1. The new system is a more sophisticated version of that, expanded to support compatibility checks and apply to themes. In WHMCS 8.1 and later, the theme.yaml file lets you specify properties for your theme or order form template. provides defines the assets that are included and are usually indicated in system themes. Meanwhile, dependencies lists the assets that an order form template requires from the system theme in order to operate.

Here's a look at a potential theme.yaml file for a System Theme:
name: "Example"
description: "My Company's Branding"
author: "Hosting Company, L.L.C."
   parent: twenty-one
   jquery: 1.12
   fontawesome: 5
   bootstrap: 4.5.2

Compatibility Checks
If you don't specify something in the theme.yaml file, like a list of dependencies, WHMCS assumes compatibility. This ensures that older themes and order form templates don't need updates to keep working after the upgrade to WHMCS 8.1. WHMCS only detects incompatibility if the two involved theme.yaml files conflict, as they would if a system theme listed Bootstrap 3 in its provides section and an order form template listed Bootstrap 4 under dependencies.

If the two theme.yaml files indicate that there's an incompatibility, WHMCS will display a warning when you select a System Theme from Configuration > System Settings > General Settings in the General tab. At that point, your settings will be adjusted to use a compatible order form template instead. This prevents incompatibilities from directly impacting your customers without your knowledge, and we hope it will make you feel more secure in using your customizations.

Existing system themes and order forms
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 the same way when you upgrade to WHMCS 8.1. If you have time for updates, though, we recommend making sure to add these sections during new development, since they can help find incompatibilities and save you time troubleshooting your order form templates.

Ready to try the new system? You can find more information on developing custom themes in our Developer Documentation.

Liked this article? Share it