Revision as of 21:03, 29 April 2020

Introduction

Order Form Templates define the look and feel of the shopping cart process.

Built-in Order Form Templates

WHMCS ships with several order form templates.

For details of deprecated and discontinued order form templates, see Discontinued 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 Standard Cart.

There is also an option to configure an Order Form template on a per-product group basis. To do this, navigate to 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. It will also define the styling 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 using a crafted URL. An order form template that you create 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 like http://www.yourdomain.com/whmcs/?carttpl=xxxxx. In this URL, xxxxx is the name of the template directory.

Template Files

Order Form templates exist in the /templates/orderforms/ directory. Each subdirectory is a different order form template. Within those directories, you will find the following files:

• products.tpl — Lists product categories and products.
• adddomain.tpl — Begins the process for domain registration-only orders.
• addons.tpl — Lists the addons a user can order for their existing packages when they log in.
• domainrenewals.tpl — Lists domains in the client's account. This can also allow for domain renewals to in advance.
• configureproductdomain.tpl — Allows domain selection for domains for a specific product.
• domainoptions.tpl — For some templates, displays domain availability check results.
• configureproduct.tpl — Configures the product before adding it to the cart (for example, thebilling cycle, configurable options, or custom fields).
• configuredomains.tpl — Chooses domain addons, complete custom field requirements, and custom nameservers.
• ordersummary.tpl — Displays cart contents and product total summaries during the order process.
• viewcart.tpl — Displays cart contents and the checkout process.
• login.tpl — Displays the login page for existing users.
• complete.tpl — Displays 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 you are 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. You can then use these 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 you define them.

By leveraging this functionality, a developer can create templates that are simple and easy to maintain. The system updates any changes to template files that aren't customised when you upgrade.

For 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 use 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. Make the desired changes to the copy within the custom template directory.
4. 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, in Setup > General Settings > Ordering tab.

Selection of the custom template would then occur in the necessary product groups in 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. The complete.tpl file in the active order template folder controls this. For example, this could occur if a third party conversion tracking or affiliate system needs to execute JavaScript after checkout.

This file contains an {if $ispaid}{/if} section, as in the example below. Code inside those tags runs once a customer pays for an order. 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}