Revision as of 15:41, 4 January 2016

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 order form templates.

Configuring the Order Form Template

Definition of Order Form templates can occur in two locations.

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.

There is also an option to configure an Order Form template on a per product group basis. Done in Setup > Products/Services > Create/Edit Product Group. Selecting an Order Form template here, will override the system default when viewing that product group in the client area. As well, it will 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 crafted URL. An order form template you specify using this method takes precedence over the system or product group order form template. This will last for the duration of the users visit.

To do this, use an URL such as http://www.yourdomain.com/whmcs/?carttpl=xxxxx. In this URL, xxxxx is the name of the template directory.

Template Files

The location for Order Form templates are the /templates/orderforms/ directory. Each sub-directory is a different order form template. Within those directories, you will find the following files.

The template name, and what each of them controls is 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. Can also allow for domain renewals to 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 - Shown 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 - 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 an order form that inherits template files from another directory, eliminating the need to create a custom copy of all twelve template files. Only the pages you wish to customise need be created, the rest will then automatically be loaded from the parent order form when defined.

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.

1. Begin by identifying the name of the template file that controls the step of the process you want to customise (see the list above).
2. Next, copy that template file from the defined parent template to your new template directory
3. Now make your desired changes to the copy of the template within your custom template directory
4. 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.
   1. Typically the parent template would be the system default (Setup > General Settings > Ordering tab).
   2. Your custom template would then be selected on the product groups for which it to be used (Setup > Products/Services > Products/Services > Edit Group).

Third Party Order Conversion/Affiliate Tracking

When checkout is completed and the customer makes payment for their order, they get returned to the order completed page. This page is controlled by the complete.tpl template file in your active order template folder. So if you want to use a third party order conversion tracking or affiliate system and need to execute javascript after checkout, then you will need to insert code into this file.

This file contains an {if $ispaid}{/if} section as below so you can put code either inside those tags so that it only runs once an order has been paid for, or outside them so it runs regardless of payment status.

{if $ispaid}
Enter any HTML code which needs to be displayed once a user has
completed the checkout  of their order here - for example
conversion tracking and affiliate tracking scripts
{/if}

You can use variables including {$orderid} {$ordernumber} and {$amount} where necessary to fill in order details.