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
file's dependencies section.
For example, this relationship could resemble this example of an
system theme and the
order form template:
In the example above*,
includes Bootstrap 4.5.2 and lists it in a
file so that its presence is detectable by WHMCS. In turn,
needs and will get Bootstrap 4 it from its parent theme and lists it in its
can receive Bootstrap from
, it's important to note that
can't get anything from
. So, if
didn't provide Bootstrap, you would either receive a warning (assuming both
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
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
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
file lets you specify properties for your theme or order form template.
defines the assets that are included and are usually indicated in system themes. Meanwhile,
lists the assets that an order form template requires from the system theme in order to operate.
Here's a look at a potential
file for a System Theme:
description: "My Company's Branding"
author: "Hosting Company, L.L.C."
If you don't specify something in the
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
files conflict, as they would if a system theme listed Bootstrap 3 in its
section and an order form template listed Bootstrap 4 under
If the two
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