Revision as of 13:25, 22 September 2015

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 locations 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 - 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.