DotAdmin User Guide

The Checkout Template

The Checkout Template.

dotAdmin's checkout process is used to collect customer contact and address details prior to taking a credit card payment. The first thing we need to establish is whether the customer has a shopping cart with products in it. The template responds to this with a choice of mark-up from either BLOCK {allowed} or BLOCK {denied}

<!-- BLOCK {allowed} -->
  Take customer contact and address details.
<!-- /BLOCK {allowed} -->

<!-- BLOCK {denied} -->
  Inform the customer that the shopping cart is empty.
<!-- /BLOCK {denied} -->

BLOCK allowed is shown when the cart contains something, otherwise, BLOCK denied is used.

The checkout template can be thought of as being two templates in one. The checkout process involves displaying form fields to the customer to complete and submit, and then asking the customer to confirm that these details are correct before proceeding to make a credit card payment.

The two stages of the checkout are marked by a pair of conditional instructions, IF {page1} and IF {page2}. Page 1 displays the form, and Page 2 displays the information in plain text for the customer to confirm.

Of course if the customer makes any mistakes when filling in the form, we will display error messages and show the form again

<!-- IF {page1} -->
  Show form fields to collect customer contact and address details,
  show error messages if the form was not completed correctly.
<!-- /IF {page1} -->

<!-- IF {page2} -->
  Confirm details and generate hidden fields to pass the order
  information to the payment process.
<!-- /IF {page2} -->

How the page1 and page2 conditions are used.

Note: If the submitted form contains errors which must be corrected, the IF {page1} mark-up is still used. The checkout only proceeds to page 2 when the form has been completed correctly.

There are only two elements which are displayed on both page1 and page2. {literal cart}, which displays the contents of the shopping cart using the shopping cart template, and the form submit button.

Error Checking in {page1}

As is the custom with process templates, the first thing we do at the top of the page is report any errors the user made if the form has been submitted incorrectly. There template contains a handful of blocks used to output specific error messages, and they are shown in the code example below.

<!-- BLOCK {bad_email} -->
  <b>Bad Email Address:</b> The email address you supplied does not
  appear to be valid. Please try again.
<!-- /BLOCK {bad_email} -->

<!-- BLOCK {missing_fields} -->
  <b>Missing Fields:</b> Some required fields were not filled in.
  Please complete all fields displayed in <b>bold type</b>.
<!-- /BLOCK {missing_fields} -->

<!-- BLOCK {missing_s_fields} -->
  <b>Missing Delivery Fields:</b> If you wish to ship your order
  to a location other than your billing address, please fill out
  all the fields in the Delivery section. Otherwise, leave all
  these fields blank.
<!-- /BLOCK {missing_s_fields} -->

<!-- BLOCK {tandc_unread} -->
  <b>Terms and Conditions:</b> Before we can take your order, you
  must agree to our <a href="/content/tandc" target="_blank">online
  store terms and conditions</a> by checking the relevant box at
  the foot of this page.
<!-- /BLOCK {tandc_unread} -->

Checkout error messages.

There is one other situation where a customer's details might require clarification: If the email address supplied in the checkout form is known to belong to a user, but the customer is not logged-in as that user.

In this case, we ask that the user logs in, or provides a different email address. This is handled by BLOCK {showlogin}, shown below.

<!-- BLOCK {showlogin} -->
<h1>Please Log In:</h1>
  <!-- IF {email_in_use} -->
    <p><b>Email In Use</b>: The email address you provided below
    ({email_in_use}) belongs to a registered user of this site.
    Please log in using the form below to verify that you are this
    user. Otherwise, please provide an alternative email address.
    </p>
  <!-- /IF {email_in_use} -->
  <!-- IF {login_failed} -->
    <p><b>Login failed</b>: The username and password you supplied
    were not recognised. Please try again:</p>
    <p><a href="/content/recover_pwd/">
      Forgotten your password
    </a>?</p>
  <!-- /IF {login_failed} -->

  <form method="POST" action="/content/login">
  <input type="hidden" name="remember" value="1">
  <input type="hidden" name="nextpage" value="checkout">

  <label for="input_uname">Username:</label>
  <input type="text" name="input_uname" maxlength="12">
  <label for="input_pword">Password:</label>
  <input type="password" name="input_pword">

  <input type="submit" name="next" value="next">
  </form>
<!-- /BLOCK {showlogin} -->

Asking a customer who entered a reserved email address to log-in.

Differences Between {page1} and {page2}

Aside from the error-checking discussed above, the main differences between page 1 and page 2 involve the form fields.

The first difference is the form's action. In page 1, the form is sent back to the checkout procedure for error checking. In page 2, the form has been completed successfully, so submitting the form will continue on to the payment process:

<!-- IF {page1} -->
  <form method="POST" action="/content/checkout">
<!-- /IF {page1} -->

<!-- IF {page2} -->
  <form method="POST" action="{payment_url}">
<!-- IF {page2} -->

The two form actions in the checkout template.

The second major difference is that page 1 requires form fields to collect contact and address details, whereas page 2 simply repeats them in plain text for the customer to confirm. As you might expect, this is done with the same conditional instructions.

<label for "f_name">First Name or Initial</label>

<!-- IF {page1} -->
  <input type="text" name="f_name" value="{f_name}" />
<!-- /IF {page1} -->
<!-- IF {page2} -->{f_name}<!-- /IF {page2} -->

<label for "l_name">Last Name</label></td>

<!-- IF {page1} -->
  <input type="text" name="l_name" value="{l_name}" />
<!-- /IF {page1} -->
<!-- IF {page2} -->{l_name}<!-- /IF {page2} -->

<!-- And so on... -->

Swapping between collecting and outputting customer details in the checkout template.

The final important difference is in the hidden fields used in these two pages. Page 1 contains hidden fields to tell the checkout which fields must be completed by the customer. The hidden fields in Page 2 contain information about the order to be sent to the payment process.

<!-- IF {page1} -->
  <input type="hidden" name="required"
    value="f_name, l_name, email, b_street, b_town, b_postcode,
    b_destination">
  <input type="hidden" name="s_required"
    value="s_name, s_street, s_town, s_postcode, s_destination">
<!-- /IF {page1} -->

<!-- IF {page2} -->
  <!-- BLOCK {hidden} -->
    <input type="hidden" name="{name}" value="{literal value}">
  <!-- /BLOCK {hidden} -->
<!-- /IF {page2} -->

Hidden fields in the checkout template.

Note that the “s_required” field lists the fields required in the shipping section of the template. These fields only become required if one of the shipping fields is filled-in, otherwise, the billing address is used as the delivery address.

The hidden fields for page 2 are filled-in by the system using a repeating block. This allows the flexibility to provide a choice of payment service providers (PSPs) without having to edit the template for each one.

BLOCK {billing} and BLOCK {shipping}

These two blocks are used to generate a list of valid countries or regions for the customer to select from in the billing and shipping address sections of the template. They work in much the same way as the shipping selector in the shopping cart template.

An inner block (BLOCK {options}) is repeated to create an option for each country or region, and a condition (IF {b_selected} or IF {s_selected}) is used to pre-select the customer's choice on subequent pages if the customer has already made a selection.

The only difference between the Billing block and the Shipping block is the name of the form fields used and the names of the placeholders. Below is an example of the Billing block.

<!-- BLOCK {billing} -->

  <!-- IF {page1} -->
    <select class="ship_dd" name="b_destination">
    <option value="">Choose Destination</option>

    <!-- BLOCK {options} -->

      <!-- IF {b_selected} -->
        <option value="{destination}" selected="selected">
          {destination}
        </option>
      <!-- /IF {b_selected} -->

      <!-- ELSE -->
        <option value="{destination}">{destination}</option>
      <!-- /ELSE -->

    <!-- /BLOCK {options} -->

    </select>
  <!-- /IF {page1} -->

  <!-- IF {page2} -->{b_destination}<!-- /IF {page2} -->

<!-- /BLOCK {billing} -->

Creating a list of destinations for the customer to choose from.

Note: Again, the {page1} and {page2} conditions are used within the block to switch between outputting the form field and simply reporting the chosen value.

BLOCK {showdeliver}

Because the alternate delivery address details are optional (if the fields are not completed, the billing address is used as the delivery address), the delivery address fields are contained within BLOCK {showdeliver} to allow us to show or hide them.

If the customer completes the checkout form without providing a delivery address, any mark-up contained within this block is not displayed on page 2, because there is no reason to report back to the customer that the fields were left blank.

BLOCK {testmode}

This block is only used when the store is operating in test mode. For payment providers who allow you to select whether a test order will be successful or not (such as WorldPay), this block offers a means to switch between the two. This block is only displayed on page 2 of the checkout, in order to pass the testmode value to the payment process along with all the hidden fields.

<!-- BLOCK {testmode} -->
  <label for="{varname}">Test Transaction (pass or fail?)</label>

  <select class="ship_dd" name="{varname}">
    <option value="{pass}">pass</option>
    <option value="{fail}">fail</option>
  </select>
<!-- /BLOCK {testmode} -->

BLOCK testmode is used only when the payment process is being tested.

Below is a summary of all template instructions used in the checkout template.