Commerce Commerce 1.x Upgrades v0.12

Most upgrades are automatically applied, but sometimes you may need to update custom templates, or status configuration, to take advantage of new features or improvements. Those changes are discussed here.

Most changes listed in this migration document are optional.

Table of Contents

Order references & received on date (0.12.0-rc2)

New in 0.12.0-rc2 are order references. When you upgrade to 0.12, Commerce will automatically update all your orders to add the reference. See the last section about order references on regenerating them with a different template.

In 0.12.0-rc1 a new received_on datestamp was also added; this is also automatically added to orders when upgrading.

Various default templates have also been changed to use the order reference instead of the order id and the received_on date instead of created_on. Some lexicons have also been updated, which will automatically get translated again.

Here’s a list of the changed templates:

  • emails/order-received.twig, around line 3 from {% block subject %}{{ lex('commerce.email.order_rcvd.subject', { name: config.site_name }) }}{% endblock %} to {% block subject %}{{ lex('commerce.email.order_rcvd.subject', { name: config.site_name, id: order.reference }) }}{% endblock %}
  • emails/order-received.twig, around line 4 from {% block hidden_preheader %}{{ lex('commerce.email.order_rcvd.preheader', { name: config.site_name, id: order.id }) }}{% endblock %} to {% block hidden_preheader %}{{ lex('commerce.email.order_rcvd.preheader', { name: config.site_name, id: order.reference }) }}{% endblock %}
  • emails/order-received.twig, around line 24 from {{ lex('commerce.email.order_rcvd.received', { name: config.site_name, id: order.id }) }} to {{ lex('commerce.email.order_rcvd.received', { name: config.site_name, id: order.reference }) }}
  • emails/order-to-merchant.twig, around line 4 from {% block subject %}{{ lex('commerce.email.order_rcvdmerch.subject', { name: billing_address.fullname, site_name: config.site_name, id: order.id }) }}{% endblock %} to {% block subject %}{{ lex('commerce.email.order_rcvdmerch.subject', { name: billing_address.fullname, site_name: config.site_name, id: order.reference }) }}{% endblock %}
  • emails/order-to-merchant.twig, around line 19 from <td align="center" style="font-size: 20px; font-family: Helvetica, Arial, sans-serif; color: #333333; padding-top: 30px;" class="padding-copy">{{ lex('commerce.email.order_rcvdmerch.header', { id: order.id, name: billing_address.fullname }) }}</td> to <td align="center" style="font-size: 20px; font-family: Helvetica, Arial, sans-serif; color: #333333; padding-top: 30px;" class="padding-copy">{{ lex('commerce.email.order_rcvdmerch.header', { id: order.reference, name: billing_address.fullname }) }}</td>
  • emails/shipping-confirmation.twig around line 3 from {% block subject %}{{ lex('commerce.email.shipping.subject', { name: config.site_name, id: order.id }) }}{% endblock %} to {% block subject %}{{ lex('commerce.email.shipping.subject', { name: config.site_name, id: order.reference }) }}{% endblock %}
  • frontend/checkout/thank-you.twig around line 6 from <p>{{ lex('commerce.order_complete', {'id': order.id}) }}</p> to <p>{{ lex('commerce.order_complete', {'id': order.reference}) }}</p>
  • frontend/account/order-detail.twig, around line 2 from <h2>{{ lex('commerce.order') }} #{{ order.id }}</h2> to <h2>{{ lex('commerce.order') }} {{ order.reference }}</h2>
  • frontend/account/order-detail.twig, around line 7 from <span class="c-order-summary-value">{{ order.created_on|date('Y-m-d H:i') }}</span> to <span class="c-order-summary-value">{{ order.received_on|date('Y-m-d H:i') }}</span>
  • frontend/account/orders.twig, around line 14 from <td><a href="[[~[[++commerce.order_resource]]? &order={{ order.id }}]]">#{{ order.id }}</a></td> to <td><a href="[[~[[++commerce.order_resource]]? &order={{ order.id }}]]">{{ order.reference }}</a></td>
  • frontend/account/orders.twig, around line 15 from <td>{{ order.received_on|date('Y-m-d') }}</td>

To use the reference instead of ID in the subject of the order received email, you’ll need to edit your status workflow as well. Go to Commerce > Configuration > Statuses and click the name of your status change that fires when payment has been received, typically that’s called “Payment Received”.

  • Change the Confirmation Email to Customer subject to {{ lex('commerce.email.order_rcvd.subject', { name: config.site_name, id: order.reference }) }}
  • Change the Order Notification to Merchant subject to {{ lex('commerce.email.order_rcvdmerch.subject', { name: billing_address.fullname, site_name: config.site_name, id: order.reference }) }}

Address refactor (0.12.0-rc2)

We refactored the way addresses are stored in 0.12.0-rc2, which includes some breaking changes. Most of this is transparently handled under-the-hood, but any modules or extensions that interact with comAddress (incl comOrder->getBillingAddress/getShippingAddress and related methods) will likely need to slightly upgraded.

Templating-wise, update the following in your custom theme to make sure selected addresses are checked after the update:

  • In frontend/checkout/address.twig around line 17, change current_address: address_shipping_id to current_address: address_shipping_user_address.
  • In frontend/checkout/address.twig around line 67, change current_address: address_billing_id to current_address: address_billing_user_address.

Code-wise, what was changed is that the address details for an order are now stored in the comOrderAddress model. Previously, this was in comAddress, where comOrderAddress acted as a joining table only. While this had some benefits, it also complicated basic tasks and made keeping things organised harder.

All the various address related functionality is now more about the comOrderAddress model. Calling $order->getBillingAddress/$order->getShippingAddress will now receive the comOrderAddress instance instead of comAddress. That does have the same field names, but type checks will fail.

When upgrading to 0.12, existing order address details are automatically copied into the comOrderAddress table, so you should not notice this change in the interface. If the comAddress record was not set to be remembered, it will be removed when it’s no longer used by any orders.

New shop_resource setting

Previously, an empty cart would link to the site_start setting, but now in 0.12 we’re linking to a new commerce.shop_resource setting instead. This is useful to change where the customer is sent without needing to create a custom template just for that.

To tweak this in existing custom templates, edit your frontend/checkout/cart.twig template, around line 28, from:

<p><a href="[[~[[++site_start]]]]">{{ lex('commerce.cart.no_items_yet') }} {{ lex('commerce.cart.continue_shopping') }}</a></p>

<p><a href="{{ shop_root_url }}">{{ lex('commerce.cart.no_items_yet') }} {{ lex('commerce.cart.continue_shopping') }}</a></p>

The {{ shop_root_url }} placeholder is available throughout the entire checkout.

Add to cart now in the lexicon

You can now use [[!%commerce.add_to_cart]] (in MODX templates) or {{ lex('commerce.add_to_cart') }} (in twig templates) in your add to cart forms. This is not required, but will automatically be translated for you in supported languages.

New email notes on shipping and payment methods

It’s now possible to configure notes on shipping and payment methods, which are automatically added to the email sent to the customer.

If you have a custom emails/order-received.twig template, add the following placeholders where you want those messages to show up; in the default they’re around line 335 following {{ lex('commerce.email.order_rcvd.footnote') }}:

{{ payment_method_note }}
{{ shipping_method_note }}

Cart resource now used instead of checkout resource

Previously, when you submitted a form on the cart resource (add a coupon, change/remove items), it would end up sending you to the checkout resource. Similarly, using the steps navigation on the checkout page would leave you on the checkout resource.

As of 0.12, if you have separate cart and checkout resources, any cart request will be handled by the cart resource. So changing an order item will redirect you back to the cart, instead of the cart resource.

Particularly for users with JavaScript checkout systems, please validate your cart and checkout still behave as you expect them to.