Drupal Commerce checkout: An example of being headless ready

Headless commerce is quickly becoming the gold standard in content management system architecture. In this article, Josh Miller delves into the capabilities of Drupal Commerce 2 for a headless setup.

Drupal Commerce 2, like Drupal 9, was a big change from previous versions. The codebase is much different, and it’s quite a learning curve when moving from older versions of Drupal, like 7 or 8. However, this is good. The new versions are modern and all-around better. I’ve had several revelations while working with Drupal Commerce 2 and Drupal 8 that made me smile. (If you haven’t upgraded to Drupal 9, check out my article Drupal 8 to Drupal 9: The Easiest Major Upgrade in a Decade).

In this post, I’ll explore one revelation I had while working with Drupal Commerce 2’s checkout handling and how its forward-thinking development has paved the way (and encourages all new checkout panes to follow suit) for headless ecommerce using Drupal.

Drupal Commerce 2 checkout is not a form. Say what!?

Generally, when you think of checkout, you think of it as a sequence of events and one big final submission. This is further driven home by the idea that you can, and should, be able to go back and edit your checkout choices before the final submission. In Drupal Commerce 2, going back and forth between checkout steps is supported, but no final submission handler saves everything.

Wait, what? That’s right; there’s no need to save all the data on the checkout form once checkout is completed. All checkout panes (a step in the checkout process) have a submission event that gets called when it's time to save the data. So if you save data in a checkout pane, you have to do it after your customer has moved forward in the process but before your customer is ready to commit to the checkout pane’s final value state (complete checkout). Submission is perceived to be at the end of checkout, not before.

On the surface, that might make sense. In fact, this obvious workflow might even blind you to the implications. Since each pane handles its own submission workflow, you can’t allow your form state to persist choices and not make a decision until the end. Like me, you’re probably thinking that saving and reacting to data are the same thing. But this assumption is old, out-of-date, incompatible with best practices, and in checkout for Commerce 2, causes design problems.

Explanation through an example: A checkout newsletter subscription

A common want is to include a little checkbox underneath a contact information email field where new or returning customers can opt-in to a newsletter. Sure, that’s no big deal, right?

Our customer expects things in checkout aren’t real until they complete checkout (i.e. nothing is saved until they place the order). On the other hand, Drupal Commerce 2 expects all panes to save their data after a “continue to next-step” button gets clicked, submitting that pane.

Here’s how the checkbox would be made using our current form submission logic:

1. Create a CheckoutPaneBase object that collects data through a checkbox.
2. On the pane form submission, subscribe the customer to your newsletter.

Do you see the problem? If we react on pane submission (our only choice in our current way of thinking), we’ll subscribe the customer to our newsletter well before they are done with checkout. Each time they see the first checkout page and proceed to the second, they will be subscribed to our newsletter. Not only is this not what the customer would expect, but subscribing to the user multiple times is unnecessary and would likely cause problems. Subscribing the customer on pane form submission is the wrong approach.

This is where things get really trippy — awesome, beautiful, wonderfully clever, and great. Drupal 8, which Commerce 2 is built around, has been designed not to require forms, form states and value persistence to trigger important actions. This is a whole new way of thinking and may be the most important to our discussion. Previous to this, most Drupal 7 developers would have assumed that all forms require user-facing interfaces that would be submitted, but that is a pretty brutal assumption and has plagued a lot of Drupal installations over the years. If that was still the case, then form submissions are something that headless implementations of Drupal would never really trigger. There must be a better way.

Headless decoupling breeds better code-using events.

If checkout was a single form with a final submission handler that submitted payment, subscribed users to newsletters, saved addresses to profiles, and did all the things you would expect all at once, then all the code that manages these things would have to react to a single form submission.

However, if we use Drupal's built-in event system instead, we suddenly have much greater control. But before we get into that, let’s first take a quick look at what events are and where they come from.

Drupal 8 shifted to object-oriented by adopting Symfony within its framework. Symfony provides many components useful in modern object-oriented programming, one of which is events. Events in Drupal 8 allow developers to extend and modify how interactions with core and other modules work. If you’re already familiar with Drupal 7, events are meant to replace hooks. Drupal 8’s event system documentation helps us to understand the basic concepts and components making up the event system.

• Event Subscribers — Sometimes called "Listeners," are callable methods or functions that react to an event being propagated throughout the Event Registry.
• Event Registry — Where event subscribers are collected and sorted.
• Event Dispatcher — The mechanism in which an event is triggered or "dispatched" throughout the system.
• Event Context — Many events require specific data that is important to the subscribers of an event. This can be as simple as a value passed to the Event Subscriber or as complex as a specially created class containing relevant data.

Source: Drupal.org documentation, Subscribe to and dispatch events (link)

Back to our checkout scenario, if you use the events system, your checkout completion is simply a state transition from Draft to Completed. Other modules could subscribe to that transition event, take the saved data from the different pane submissions, and do whatever they want with it.

Do you see the beauty here? By forcing checkout panes to submit before the final submission, we (module builders, implementers, etc.) have a baked-in reason to store checkout decisions on the order so that order events can access them separately, giving us the ability to create orders with checkout decisions saved that can skip checkout completely and still have the events trigger the needed actions. This is quite powerful and opens up a whole new world of possibilities. Of course, since this is an implicit design choice, it’s up to the module's author or code to see the reasons and embrace them.

Entity and event-based instead of form-based

So to complete our newsletter subscription pane example using our new knowledge of events instead of form submissions, here’s what we would do:

1. Create a CheckoutPaneBase object that collects data through a checkbox and saves it to the order (either through a field value or the ->setData typed data interface.
2. Save this value on pane submission but don’t act on the value (i.e. don’t subscribe the user).
3. Create an event subscriber and use the transition event you want to use as a trigger. Completing checkout makes the most sense.
4. Treat the order value as a "request subscription to newsletter." Then, when the event fires and the event subscriber runs, it can look for the saved value and set the user to subscribed or not after it returns. This allows us to handle someone going through an event twice for some reason, like for multiple orders, etc.

Your customer gets subscribed to your newsletter when they, and you, expect them to. No forms are needed. ISN’T THAT AMAZING?

Thanks to the many authors of Drupal Commerce 2, including Bojan Živanović and Matt Glaman, who implemented this design choice years ago, many modules and implementations are technically better and likely ready for headless implementations now that headless is all the rage.

And best of all, from a developer standpoint, this also means the bulk of your most critical automated tests that interact with your code doesn’t have to access the checkout form. They have to have orders that get transitioned. This makes writing tests, which equates to better code, simpler.

Your Drupal Commerce experts

As a full-service Drupal agency, Acro Commerce has significant expertise in digital commerce architecture, ecommerce consulting and design, customer experience, Drupal development and hosting architecture. We would love the opportunity to work with you.

---

Editor’s note: This article was originally published on October 28, 2019, and has been updated for freshness, accuracy and comprehensiveness.