This is the documentation for LemonStand V1, which has been discontinued. You can learn more and upgrade your store here.

LemonStand Version 1 Has Been Discontinued

This documentation is for LemonStand Version 1. LemonStand is now offered as a cloud-based eCommerce platform.
You can try the new LemonStand and learn about upgrading here.

AJAX-driven single-page checkout

This section describes the implementation of the single-page checkout process. This implementation involves a single page, with checkout steps loaded one by one using the AJAX requests. Please note that there are other ways of implementing the checkout process, which allows more customization of the process flow. You can read about other methods of implementing the checkout process in the Checkout Pages section.

The default checkout process consists of the following steps:

  • Customer billing address information
  • Customer shipping address information
  • Shipping method selection
  • Payment method selection
  • Order review

The checkout page consists of a single page and the 6 partials – one partial for each step, and one common partial, responsible for rendering a specific partial depending on a current checkout step. Each step partial contains a form for gathering corresponding information. For better understanding of the single-page Checkout implementation we recommend you to check how the Checkout page is organized in LemonStand Demo store.

Creating the checkout page

Start with creating a new page and specify a title and page URL for it, for example Checkout and /checkout correspondingly. Click the Action page and select the shop:checkout action in the drop-down list.

The shop:checkout action handles AJAX events occurring on the page (for example Next button clicks) and supplies a number of variables which values could be displayed on the page. The following variables are available on each checkout step:

  • $billing_info – an object variable of class Shop_CheckoutAddressInfo. Represents a billing address information of a current customer.
  • $shipping_info – the same as $billing_info, but represents a shipping address.
  • $shipping_method – a PHP object variable with fields $id, $quote and $name. Represents a preferred shipping method of a current customer.
  • $payment_method – a PHP object variable with fields $id and $name. Represents a preferred payment method of a current customer.
  • $checkout_step – a string variable representing a current checkout step code. The variable could have one of the following values: 'billing_info', 'shipping_info', 'shipping_method', 'payment_method', 'review'. Depending on a value of this variable a specific checkout step (partial) is rendered on the Checkout page.
  • $discount - estimated cart discount. You can display this value during the checkout process.
  • $cart_total - cart total value (subtotal).
  • $estimated_total - an estimated total value. This value is calculated on each step of the checkout process, taking into account price rules and known information about the customer.
  • $estimated_tax - an estimated tax value. This value is calculated on each step of the checkout process, taking into account price rules (defined on the Shop/Discounts page) and known information about the customer. The tax value includes the sales tax and shipping taxes.

Also, depending on a current checkout process step, additional variables become available.

Variables, available on the billing_info step

  • $countries – a list of countries to fill the Billing Country drop-down list
  • $states – a list of states to fill the Billing State drop-down list

Variables, available on the shipping_info step

  • $countries – a list of countries to fill the Shipping Country drop-down list
  • $states – a list of states to fill the Shipping State drop-down list

Variables, available on the shipping_method step

  • $shipping_options – a list of available shipping options

Variables, available on the payment_method step

  • $payment_methods – a list of available payment methods
  • $goods_tax – a value of a goods tax
  • $subtotal – order subtotal sum
  • $shipping_quote – a shipping quote value
  • $shipping_tax – a shipping tax value

The following code demonstrates an example of the Checkout page content.

<h2>Check Out</h2>
<? if (Shop_Cart::get_item_total_num() != 0): ?>
  <div id="checkout_page">
    <? $this->render_partial('checkout_partial') ?>
  </div>
<? else: ?>
  <p>Your shopping cart is empty.</p>
<? endif ?>
<h2>Check Out</h2>
{% if method('Shop_Cart', 'get_item_total_num') != 0 %}
  <div id="checkout_page">
    {{ render_partial('checkout_partial') }}
  </div>
{% else %}
  <p>Your shopping cart is empty.</p>
{% endif %}

First, the code checks whether any items are in the shopping cart, using the get_item_total_num method of the Shop_Cart object. If the shopping cart is empty, a message is displayed instead of the Billing Information form. If the shopping cart is not empty the code outputs a DIV element with specific ID attribute value. This DIV contains a partial, corresponding a specific checkout process step. The content of the DIV element is updated using AJAX each time a user clicks the Next button. The value of the ID attribute could be anything, but you should specify the same ID value in AJAX requests.

The partial rendered in the example (checkout_partial) is a helper container partial which renders a specific checkout step partial depending on a current checkout step.

Creating a checkout container partial

The checkout container partial, named checkout_partial in the page code example above, acts as a container for one of the checkout step partials. The following code demonstrate how to render a specific partial depending on a current checkout step.

<?= open_form() ?>
  <?
  switch ($checkout_step)
  {
    case 'billing_info': $this->render_partial('shop:checkout_billing_info'); break;
    case 'shipping_info': $this->render_partial('shop:checkout_shipping_info'); break;
    case 'shipping_method': $this->render_partial('shop:checkout_shipping_method'); break;
    case 'payment_method': $this->render_partial('shop:checkout_payment_method'); break;
    case 'review': $this->render_partial('shop:checkout_review'); break;
  }
  ?>
</form>
{{ open_form() }}
  {% if checkout_step == 'billing_info' %}
    {{ render_partial('shop:checkout_billing_info') }}
  {% elseif checkout_step == 'shipping_info' %}
    {{ render_partial('shop:checkout_shipping_info') }}
  {% elseif checkout_step == 'shipping_method' %}
    {{ render_partial('shop:checkout_shipping_method') }}
  {% elseif checkout_step == 'payment_method' %}
    {{ render_partial('shop:checkout_payment_method') }}
  {% elseif checkout_step == 'review' %}
    {{ render_partial('shop:checkout_review') }}
  {% elseif checkout_step == 'pay' %}
    {{ render_partial('shop:checkout_pay') }}
  {% endif %}
{{ close_form() }}

The HTML FORM element is needed because the checkout page contains forms for gathering information. The switch control structure inspects a current value of the $checkout_step variable and renders a corresponding partial. Partials in the example code have descriptive names which we will use from now on in this documentation. You can use other names for your partials.

Navigating between checkout steps

To enable users to navigate between the checkout step, you can create a simple partial displaying links to the previous checkout steps. By previous we mean steps which have already been visited by a costumer. For example, if at the moment a visitor is on the Shipping Method checkout step, he must be able to return to the Shipping Information and Billing information checkout steps.

The simplest and most correct way to create the checkout steps navigation, is to create a separate step and render it in each checkout step. Start with creating a new partial and assign it some meaningful name, for example shop::checkout_progress. The following code snippet demonstrates a checkout steps navigation code we used in the LemonStand Demo store.

The code iterates over possible checkout steps and outputs a LI element for each step. Also, it checks whether a step is already visited by a customer, by examining the $checkout_step variable value. The code outputs a link only for visited steps.

The key element in the code above is the onclick event handler, which is assigned to the  visited step links. It sends an AJAX request to LemonStand, asking it to execute the on_action event handler and passing it a value of a step code in the move_to parameter.

Once you finished developing the navigation partial, you can render it in each checkout step partial, or a better way – you can render the navigation partial in the checkout partial container code. To render the navigation partial, use the following code:

You can place it on the top of the checkout partial container, before rendering a specific partial step.

Continue:

See also:

Next: Creating a Form for Billing Information
Previous: Checkout Process
Return to Checkout Process