Latest revision as of 20:53, 26 April 2022

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 information on Order Form templates and functionality, see Standard Order Form Templates.
• For details of deprecated and discontinued order form templates, see Discontinued Order Form Templates.

Configuring the Order Form Template

You can set Order Form templates in two locations.

• The Ordering tab at Configuration () > System Settings > General Settings or, prior to WHMCS 8.0, Setup > General Settings. This defines the system default order form template. By default, this is Standard Cart.
• The product group at Configuration () > System Settings > Products/Services or, prior to WHMCS 8.0, Setup > Products/Services. To set this, create or edit a 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 order form template or product group order form template. This will last for the duration of the user's visit.

To do this, use a URL that resembles http://www.example.com/whmcs/?carttpl=xxxxx. In this URL, xxxxx is the name of the order form template directory.

For more information, see Linking to WHMCS.

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:

• adddomain.tpl — Begins the process for domain registration-only orders (WHMCS 8.0 and earlier).
• addons.tpl — Lists the addons a user can order for their existing packages when they log in.
• domain-renewals.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.
• checkout.tpl — Displays checkout page where visitors enter their contact and payment details.
• common.tpl — Includes CSS elements specific to the order pages.
• complete.tpl — Displays at the end of the checkout process.
• configureproduct.tpl — Configures the product before adding it to the cart (for example, the billing cycle, configurable options, or custom fields).
• configuredomains.tpl — Chooses domain addons, complete custom field requirements, and custom nameservers.
• domainregister.tpl — Domain searching and suggestions.
• domaintransfer.tpl — Domain transfers eligibility check and EPP code provision.
• error.tpl — An error page that's specific to the cart process.
• fraudcheck.tpl — Displayed if the client fails a fraud check.
• linkedaccounts.tpl — Includes any activated Social Sign-In Integrations.
• login.tpl — Displays the login page for existing users (WHMCS 8.0 and earlier).
• marketconnect-promo.tpl — Promotes MarketConnect products when the client views the cart (WHMCS 7.6 and later).
• ordersummary.tpl — Displays cart contents and product total summaries during the order process.
• products.tpl — Lists product categories and products.
• sidebar-categories.tpl — A sidebar that lists group or contextual product information.
• sidebar-categories-collapsed.tpl — The sidebar-categories.tpl sidebar, collapsed for a smaller viewport.
• viewcart.tpl — Displays cart contents, tax estimators, and promotion code applicators.

Creating a Custom Order Form Template

To create a custom order form template:

1. Choose a name. The first step is to create a custom folder to store the custom order form template files. This ensures they are not overwritten or lost when upgrading. Names must be alphanumeric, all lowercase, and may use underscores.
2. Decide how to create your order form template. If you are running WHMCS 6.1 and later, we recommend using the parent relationships method (see below). For earlier versions of WHMCS, copy all the order form 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 template 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 of the template files. Only create the pages that need customisation. The remaining order form templates will then load from the parent order form when you define them.

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

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

Creating a New Template based on a Parent

After creation of a custom order form template, you must specify the parent order form template. To do this, create a YAML file within the new directory. Name the YAML file theme.yaml and include the following code:

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. You can activate it in the Ordering tab at Configuration () > System Settings > General Settings or, prior to WHMCS 8.0, Setup > General Settings. You can also now select the custom Order Form template name within the configuration area for a specific product group.

If you want to customize a step in the ordering process, follow these steps:

1. Identify the order form template file that controls the step you want to customize.
2. Copy that order form template file from the defined parent order form template to the new directory.
3. Make the desired changes to the copy within the custom order form template directory.
4. Enable the new order form template. The custom order form template will load the step that has had customization. Other steps will load from the parent order form template. Usually, the parent order form template is the system default in the Ordering tab at Configuration () > System Settings > General Settings or, prior to WHMCS 8.0, Setup > General Settings.

Then, select the custom order form template in the necessary product groups in Configuration () > System Settings > Products/Services or, prior to WHMCS 8.0, Setup > Products/Services > Products/Services.

Third Party Order Conversion/Affiliate Tracking

After checkout and payment, a client will see the Order Completed page. The complete.tpl file in the active order form template directory controls this. 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}