LemonStand Version 1 - Creating a Form for Shipping Method

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.

Creating a Form for Shipping Method

The Shipping Method partial contains a form for selecting a suitable shipping method from the list of available methods. LemonStand prepares the list of available shipping methods basing on the shipping information provided by a customer on a Shipping Information checkout step. The list of available shipping methods is presented by the $shipping_options PHP variable supplied by LemonStand.

Start with creating a new partial. According to the code example in the Checkout Page partial, the name of the Billing Information partial should be shop:checkout_shipping_method. You can use any name for partials in your store.

The $shipping_options variable contains a list of available shipping options. Some shipping methods, like UPS, can provide multiple shipping options - for example UPS Express and UPS Standard. The code which displays the shipping option list must check the multi_option field of each object in the $shipping_options collection in order to create corresponding markup for single option and multi option payment methods.

The following code demonstrates an example of the Shipping Method partial code:

<h3>Shipping Method</h3>
<? if (count($shipping_options)): ?>
  <p>Please select shipping option.</p>
  <? foreach ($shipping_options as $option): ?>
    <? if ($option->multi_option): ?>
    
      <h5><?= h($option->name) ?></h5>
      
      <? if ($option->description): ?>
        <p><?= h($option->description) ?></p>
      <? endif ?>               

      <? foreach ($option->sub_options as $sub_option): ?>
        <input <?= radio_state($option->id == $shipping_method->id && $sub_option->id == $shipping_method->sub_option_id) ?> 
          id="<?= 'option'.$sub_option->id ?>" type="radio" name="shipping_option" value="<?= $sub_option->id ?>"/>
        <label for="<?= 'option'.$sub_option->id ?>">
  <?= h($sub_option->name) ?> - <strong><?= !$sub_option->is_free ? format_currency($sub_option->quote) : 'free!' ?></strong>
        </label><br/>
      <? endforeach ?>
      
    <? else: ?>
    
      <input <?= radio_state($option->id == $shipping_method->id) ?> id="<?= 'option'.$option->id ?>" 
        type="radio" name="shipping_option" value="<?= $option->id ?>"/>
      <label for="<?= 'option'.$option->id ?>">
  <strong><?= h($option->name) ?></strong> - <strong><?= !$option->is_free ? format_currency($option->quote) : 'free!' ?></strong>
        <? if ($option->description): ?>
          <br/><?= h($option->description) ?>
        <? endif ?>
      </label><br/>
      
    <? endif ?>
  <? endforeach ?>  
  <input type="hidden" name="checkout_step" value="<?= $checkout_step ?>"/>
  <input type="image" src="/resources/images/btn_next.gif" alt="Next" onclick="return $(this).getForm().sendRequest(
    'on_action', {update:{'checkout_page': 'checkout_partial'}})"/>
<? else: ?>
  <p>There are no shipping options available for your location.</p>
<? endif ?>

<h3>Shipping Method</h3>
{% if shipping_options %}
  <p>Please select shipping option.</p>
  
  {% for option in shipping_options %}
    {% if option.multi_option %}
      <h5>{{ option.name }}</h4>
        {% if option.description %}
          <p>{{ option.description }}</p>
        {% endif %}

        {% for sub_option in option.sub_options %}
          <input {{ radio_state(option.id == shipping_method.id and sub_option.id == shipping_method.sub_option_id) }}
            id="{{ 'option'~sub_option.id }}" type="radio" name="shipping_option" value="{{ sub_option.id }}"/>
          <label for="{{ 'option'~sub_option.id }}">
            {{ sub_option.name }} - <strong>{{ not sub_option.is_free ? sub_option.quote|currency : 'free' }}</strong>
          </label><br/>
        {% endfor %}
      {% else %}
        <input {{ radio_state(option.id == shipping_method.id) }} id="{{ 'option'~option.id }}" type="radio" name="shipping_option" value="{{ option.id }}"/>
        <label for="{{ 'option'~option.id }}">
          <strong>{{ option.name }}</strong> - <strong>{{ not option.is_free ? option.quote|currency : 'free' }}</strong>
            {% if option.description %}
              <br/>{{ option.description }}
            {% endif %}
          </label><br/>
      {% endif %}
  {% endfor %}
  
  <input type="hidden" name="checkout_step" value="{{ checkout_step }}"/>
  <input type="image" src="/resources/images/btn_next.gif" alt="Next" onclick="return $(this).getForm().sendRequest(
    'on_action', {update:{'checkout_page': 'checkout_partial'}})"/>
{% else %}
  <p>There are no shipping options available for your location.</p>
{% endif %}

The code checks whether the $shipping_options array contains any shipping options. If there are no shipping options available, the corresponding message is displayed. Otherwise, the foreach PHP loop is used for iterating over the list of shipping options. For each shipping option the code outputs a label and a radio button control. For multiple option shipping method, the method header is displayed before the list of options. The label element contains the shipping option name, shipping quote, and shipping option description. Please note the value of the radio button INPUT element name shipping_option, corresponding to the shipping option identifier.

The checkout_step hidden field should be used in all checkout partials.

Displaying shipping service error messages

By default LemonStand does not return shipping options with errors. If a visitor entered an invalid ZIP code, all shipping options provided by external services (USPS, UPS, etc.) would be suppressed. You can enable the Display shipping service errors option on the Parameters tab of the System/Settings/Shipping Configuration page. When this option is enabled, LemonStand returns all options. To determine whether a shipping option has an error message assigned, use the error_hint field of the Shop_ShippingOption class. If this field is not empty, you should display its content instead of the option price and radio button. Example:

<? if (count($shipping_options)): ?>
  <p>Please select shipping option.</p>
  <? foreach ($shipping_options as $option): ?>
    <? if ($option->error_hint): ?>
      <p><?= h($option->name) ?> - <?= h($option->error_hint) ?></p>
    <? else: ?>
      Display the usual shipping option elements here
    <? endif ?>
  <? endforeach ?>
  ...

{% if shipping_options %}
  <p>Please select shipping option.</p>
  {% for option in shipping_options %}
    {% if option.error_hint %}
      <p>{{ option.name }} - {{ option.error_hint }}</p>
    {% else %}
      Display the usual shipping option elements here
    {% endif %}
  {% endfor %}
  ...

LemonStand Version 1 Has Been Discontinued

Creating a Form for Shipping Method

Displaying shipping service error messages

See also: