Order Form Templating
Contents
Introduction
Order Form Templates define the look and feel of the shopping cart process.
Built-in Order Form Templates
WHMCS ships with a number of built-in order form templates. More information on these and the functionality of each can be found in the Standard Order Form Templates documentation.
Configuring the Order Form Template
There are two places where Order Form templates can be configured.
The first is in Setup > General Settings > Ordering. This defines the system default order form template directory. By default, this is set to Standard Cart.
You can also configure an Order Form template on a per product group basis. This can be done in Setup > Products/Services > Create/Edit Product Group. By selecting an Order Form template here, it will override the system default any time that product group is viewed within the client area, as well as define the styling used for the product configuration part of the order process for products and bundles within that group.
Dynamic Order Form Switching
You can also specify an order form "on the fly" using a specially crafted url. Any order form template you specify using this method takes precedence over any system or product group default order form template settings, and will last for the duration of the users visit.
To do this you use a URL such as http://www.yourdomain.com/whmcs/?carttpl=xxxxx where xxxxx is the name of the template directory. See Linking to WHMCS for further information.
Template Files
Order Form templates are located in the /templates/orderforms/ directory. Each sub-directory is a different order form template. Within those directories, you will find the following files.
The names and what each of them controls is provided below.
- products.tpl - Lists product categories and products
- adddomain.tpl - First step for domain registration only orders
- addons.tpl - Lists the addons a user can order for their existing packages when logged in
- domainrenewals.tpl - Lists domains in the clients account and allows for renewals to be ordered in advance
- configureproductdomain.tpl - Domain selection for domains attached to a product
- domainoptions.tpl - Used by some templates to display domain availability check results
- configureproduct.tpl - Configure the product before adding to the cart eg. billing cycle, configurable options, custom fields
- configuredomains.tpl - Choose domain addons, complete custom field requirements & custom nameservers
- ordersummary.tpl - Used to display cart contents and product total summaries during order process
- viewcart.tpl - Showing cart contents & checkout process
- login.tpl - Used for login for existing users
- complete.tpl - This page is showed at the end of the checkout process
Creating a Custom Order Form Template
So you want to create your own order form template. Nice!
Step 1: Choose a name - As always, the first step is to create a custom folder to store your custom templates files in so that they are not overwritten or lost when upgrading. Names must be alphanumeric, all lowercase and you may use underscores.
Step 2: Decide how you will create your template - if running 6.1 and later, we recommend using the parent relationships method (see below). For any earlier versions of WHMCS however, or simply if you prefer, you will need to copy all of the template files from one of the existing order form template folders to use as a starting point for your custom order form process.
Parent Relationships
In an effort to make upgrading and maintaining order form customisations easier, Order Form templates support the concept of parent/child relationships. What this allows is to create a template that inherits template files from another template. When a template file is not defined in a given template, and a parent relationship is defined, then the template is automatically loaded from the parent template.
By leveraging this functionality, you can create templates that are simpler and easier to maintain and keep up-to-date as any changes made to template files that you haven't customised, and that exist only within the parent order form template, are automatically updated any time you upgrade.
This is most simply illustrated by way of an example:
The Standard Cart order form template is the parent order form for the Premium Comparison order form template. Therefore since the Premium Comparison consists of only a products.tpl template file, all other steps of the order process for products and groups assigned to that order form template use the templates and design/styling as provided by the Standard Cart.
Creating a New Template based on a Parent
Once you have created a new template directory with your desired name, to define a parent relationship, you need to create a YAML file within the new template directory you just created that specifies the parent template it is based upon. This yaml file should be named theme.yaml' and include the following content:
In the above example, "standard_cart" is the name of the parent template we're using.
At this stage your new order form template is ready to be used and can be activated and used either via the Ordering tab of General Settings, or by selecting the custom order form template name within the configuration area for a specific product group.
Now let's look at how we would customise a step of the order process.
- Begin by identifying the name of the template file that controls the step of the process you want to customise (see the list above).
- Next, copy that template file from the defined parent template to your new template directory
- Now make your desired changes to the copy of the template within your custom template directory
- Finally enable your new order form to see it in action and you will find the step you customised is loaded from your custom template directory, while all other steps are loaded from and act as per the parent.