Revision as of 03:35, 19 September 2017

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

Step 1: Choose a name. The first step is to create a custom folder to store the custom templates files. This so that they are not overwritten or lost when upgrading. Names must be alphanumeric, all lowercase and may use underscores.

Step 2: Decide how to create your template. If running 6.1 and later, we recommend using the parent relationships method (see below). For earlier versions of WHMCS (or if you prefer), copy all the template files from an existing order form template folder. These can then be used as a starting point for the custom order form.

Parent Relationships

To make upgrading and maintaining order form customisations easier, Order Form templates support parent/child relationships. This allows an order form that inherits template files from another directory. It will end the need to create a custom copy of all twelve template files. Only create the pages that need customisation. The remaining templates will then load from the parent order form when defined.

By leveraging this functionality, a developer can create templates that are simple and easy to maintain. Because, any changes made to template files that aren't customised, update on upgrade.

This is best illustrated by way of an example:

The Standard Cart order form template is the parent for the Premium Comparison template. Premium Comparison consists only of a products.tpl template file. So, all other steps of the order process utilise templates and design from the Standard Cart.

Creating a New Template based on a Parent

After creation of a custom order form template, WHMCS needs to know the parent template. Create a YAML file within the new directory to do this. Name the YAML file theme.yaml and include the following:

config:
    parent: standard_cart

In the above example, "standard_cart" is the name of the parent template we're using.

At this stage the new order form template is ready. Activation via the Ordering tab of General Settings is possible. Selection of the custom order form template name within the configuration area for a specific product group is also possible. 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 a developer will customise. See the list above for help.
2. Copy that template file from the defined parent template to the new template directory.
3. Now make the desired changes to the copy within the custom template directory.
4. Finally enable the new order form to see it in action. The custom order form will load the step that has had customisation. Other steps will load from the parent order form template.
   • Usually, the parent template would be the system default. (Setup > General Settings > Ordering tab).
   • Selection of the custom template would then occur on the product groups required. (Setup > Products/Services > Products/Services > Edit Group).

Third Party Order Conversion/Affiliate Tracking

On checkout completion, and after customer payment, a client will see the Order Completed Page. Controlled by the complete.tpl file in the active order template folder. An example use is if a third party conversion tracking or affiliate system needs to execute any javascript after checkout.

This file contains an {if $ispaid}{/if} section as below. Code inside those tags runs once an order is paid. Code outside 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}