Oct 28 2019
Oct 28

Drupal Commerce 2, like Drupal 8, was a big change from previous versions. The code base is much different and it’s quite a learning curve when moving from Drupal 7 to the more complex approaches in Drupal 8. However, this is good. The new versions are modern and all around better. I’ve had a number of revelations while working with Drupal Commerce 2 and Drupal 8 that made me smile. In this post, I’ll explore one revelation I had while working with Drupal Commerce 2’s checkout handling and how it’s 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 there is no final submission handler that saves everything.

Wait, what? That’s right, there’s no need to save all the data on the checkout form once checkout is completed. You see, 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’re going to save data in a checkout pane, you gotta do it after your customer has moved forward in the checkout 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 workflow being so obvious might even blind you to the implications. Since each pane is basically handling its own submission workflow, you can’t allow your form state to persist choices and not make a decision until the end. You’re probably, like me, thinking that saving data and reacting to data is the same thing. But this assumption is old, out of date, incompatible with best practices, and in checkout for Commerce 2, causes design problems.

Click to discover your ideal architecture with our analysis.

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 that things in checkout aren’t real until they complete checkout (i.e. nothing is saved until they actually 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. In fact, each time they see the first page of checkout and proceed to the second, they will be subscribed to our newsletter. Not only is this not what the customer would expect, but subscribing them multiple times is totally unnecessary and would likely cause problems. Subscribing the customer on pane form submission is the wrong approach.

This is where things get really trippy – and awesome and beautiful and wonderfully clever and great. You see, Drupal 8, which Commerce 2 is built around, has been designed to not require forms, form states and value persistence in order to trigger important actions. This is a whole new way of thinking and maybe 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 degree of 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 made a big shift towards being object oriented by adopting Symfony within its framework. Symphony provides a number of components useful in modern object oriented programming, one of which is events. Events in Drupal 8 give developers a new way to extend and modify how interactions with core and other modules work. If you’re already familiar with Drupal 7, events are basically 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 set of data that is important to the subscribers to an event. This can be as simple as a value passed to the Event Subscriber, or as complex as a specially created class that contains the relevant data.

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

Getting back to our checkout scenario, if you use the events system and your checkout completion is simply a state transition from Draft to Completed, then 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 author of the module or code to see the reasons and embrace them.

Entity + 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 needed. ISN’T THAT AMAZING!

Thanks to the many authors of Drupal Commerce 2, including Bojan Živanović and Matt Glaman, that implemented this design choice years ago, many modules and implementations are simply 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 simply 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 Media 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.

View Our Drupal Commerce Services

Jun 14 2018
Jun 14
Empower your customers to customize products.


There is a high likelihood that the tshirt on your back or in your closet started life as someone’s idea that was being uploaded to an online tool. The idea that a person could not only buy tshirts, but design them in a tool and approve the proof before payment seems almost commonplace. Why aren’t more people talking about this? Your customers are expecting more tailored experiences when buying decorated apparel, signage and personalized promotional products from the small to medium web store fronts. Getting the “Web to Print” toolset just right on Drupal is not easy.

Here’s just a few of the expectations for ordering printed materials from the web on Drupal:

  • Drupal integration: Full integration with existing Drupal website
  • Intuitive editor experience: Drag and drop toolset, uploading of files (jpg, png, tiff, pdf, eps, ai, psd), cropping and quick fixes to pictures, lots of fonts, pop-over text formatting, white labelled branding with plenty of customizations, low resolution upload warnings, and mobile friendly web to print tool.
  • Proof and checkout workflow: Print-quality PDF proof, edit before purchase, edit after purchase, CMYK color space, super large files that need processing

Getting off the bespoke product editor island

An example of a bespoke web to print tool Acro Media built with Drupal and jQuery UI.

An example of a bespoke web to print tool Acro Media built with Drupal and jQuery UI.

Like many Drupal agencies, there’s rarely a problem we face that can’t be solved with in-house open source tools. Before we decry the problems, we are very proud of what we accomplished in the past given budget and available tools. With jQuery UI and html-to-pdf experience, we’ve built these kinds of tools before, to varying degrees of success. Every time we tackled a project like web-to-print, the struggle became very real. With minimal hours, the tools we knew and loved created a functional experience that was hard to maintain and very error prone.

Demo Drupal Commerce today! View our demo site.More often than not, we had trouble with converting HTML to PDF reliably enough for high-resolution print-quality, especially with customer supplied imagery and layout. Offering fonts in a customized product builder is challenging to get right, especially when you’re creating a PDF that has to have the font attached. The RGB colorspace doesn’t translate easily to CMYK, the most common four color process for printing. And all of our experience in software revolved around pixels, not these things called picas. In this crazy world resolution could go as high as 3200 dpi on standard printers, dimensions suddenly couldn’t be determined based on pixels.

When one of our clients that had a tool we had built with existing technologies asked for some (not all) of the features mentioned in the beginning of the article, we also wanted to solve all the technical challenges that we grappled with over a year ago. As the planning stage was coming to an end, it was clear the budget wasn’t going to support such a complicated software build.

Product Customization is not the right phrase

Example screenshot of keditor in action.

Example screenshot of keditor in action.

We started to look for product customization tools and found nada. Then we looked for web layout tools which would maybe give Drupal a better HTML editing experience, but found a disappointing lack of online web to print solutions. We did find grapejs, innovastudio, and keditor

But, almost universally, these javascript-based libraries were focused on content and not editing products that would be printed. We needed something that had the goal of creating a printable image or PDF with a tight integration around the editor experience. We had nearly convinced ourselves there wasn’t a vertical for this concept, it seemed like nearly all product builders in the wild were powered by one-off conglomerations of toolsets.

Web to Print using Customer’s Canvas works with Drupal, right?

Finally, via a project manager, an industry phrase was discovered that opened the floodgates: web to print. After a bit of sifting through the sales pitch of all the technologies, almost all tools were found to be cumbersome and hard to integrate in an existing Drupal website, save one. Customer’s Canvas checked all the boxes and then some:

  • SAAS (so we don’t have to host customer’s images, or maintain the technology)
  • White label
  • More than fully featured
  • Completely customizable
  • Iframe-friendly. Meaning we could seamlessly plop the product customization tool into an existing or new layout.

Example of Customers Canvas running in Drupal Commerce.

Example of Customers Canvas running in Drupal Commerce.

To make an even longer story short, we jumped on board with Customer’s Canvas and built the first (to our knowledge) third party web to print Drupal 7 module. We might make a Tech Talk regarding the installation and feature set of the module. Until then, here’s what you can do:

  1. Download and install the module
  2. Provide some API credentials in the form of a javascript link
  3. Turn on the Drupal Commerce integration
  4. Provide some JSON configuration for a product via a field that gets added to your choice of product types.
  5. Click on Add to Cart for a Customer’s Canvas product
  6. Get redirected to a beautiful tool
  7. Click “Finish” and directed to a cart that can redirect you back to edit or download your product.
  8. As a store administrator, you can also edit the product from the order view page.

web-to-print_customers_canvas_drupal_cart

Drupal 8 and Web to Print and the Future

Currently, the module is built for Drupal 7. Upgrading to Drupal 8 Commerce 2 is definitely on our roadmap and should be a straightforward upgrade. Other things on the roadmap:

  • Better B2B features
    You can imagine a company needs signs for all of it’s franchisee partners and would want the ability to create stores of customizable signage. With Commerce on Drupal 8, that would be pretty straightforward to build.
  • More download options
    Customer’s Canvas supports lower res watermarked downloads for the customers as well as the high res PDF downloads. Currently the module displays the high resolution for all parties.
  • Better administrative interface
    If you’re using Drupal 7, the integration for this module is pretty easy, but the technical experience required for creating the JSON formatting for each product is pretty cumbersome. So it would be awesome (and very possible) to build out the most common customizations in an administration interface so you wouldn’t have to manage the JSON formatting for most situations.
  • Improve the architecture
    Possibly support Customer’s Canvas templates like entities that are referenced so that you could create a dozen or so customizable experiences and then link them up to thousands of products.
  • Webform support
    The base module assumes your experience at least starts with an entity that has fields and gets rendered. We could build a webform integration that would allow the webform to have a customer’s canvas build step. T-shirt design content anyone?

Integration can be a game changer

One of the big reasons we work with Drupal and Drupal Commerce is that anything with an API can be integrated. This opens the doors to allow the platform to do so much more than any other platform out there. If an integration needs to be made, we can do. If you need an integration made, talk to us! We're happy to help.

Contact Acro Media Today!

Contact us and learn more about our custom ecommerce solutions

May 24 2018
May 24

In this video, Josh Miller shows you how to install Drupal Commerce 2 using a local development tool called Lando. Further instructions are included below the video.

Timestamps:

  1. Commerce Kickstart download: 0:51
  2. “composer install” command: 8:00
  3. “lando init” command: 12:56
  4. “lando start” command: 15:06
  5. “Drupal install” screen: 17:04
  6. “lando stop” command: 21:18

Prerequisites:

  1. Download and install Composer
  2. Download and install Lando

Code generated during this video:

https://github.com/AcroMedia/install-commerce-lando 

Installing Drupal Commerce 2 locally using Commerce Kickstart, Composer, and Lando

Getting Drupal up and running on your computer is an important first step as an evaluator. Good news is that there’s a lot of tech that makes this easier than ever before. We’re going to walk you through how to install Commerce 2 using the Kickstart resource, Composer, and Lando. 

  1. Download and install Composer
  2. Download and install Lando
  3. Next go to Commerce Kickstart to create and download your customized composer.json file

    Visit Commerce Kickstart

     Drupal Commerce Kickstart

  4. Run ‘composer install’

    Composer install command

  5. Run ‘lando init’

    Lando init command

  6. Run ‘lando start’

    Lando start command

  7. Visit your local URL and install Drupal

    Lando - 5 CommerceKickstart-ChooseLanguage

  8. Start building!

    Lando - 6 Congratulations

What is Drupal Commerce

Drupal Commerce is an ecommerce focused subset of tools and community based on the open source content management system called Drupal. Drupal Commerce gives you the ability to sell just about anything to anyone using a myriad of open source technologies and leveraging hundreds of Drupal modules built to make that thing you need do that thing you want.

We use Commerce Kickstart to get things started.

Try the Commerce Kickstart 2.x Installer

What is Composer

Composer is the PHP dependency manager that can not only build and bring in Drupal, Drupal Commerce, and Symfony, but is the technology behind the newest Drupal Commerce Kickstart distribution. We leverage the composer.json file that commercekickstart.com gives us to bring in all of the Drupal code necessary to run a Drupal Commerce website.

To get started, we run “composer install” and that command brings in all the requirements for our project.

What is Docker

Docker is a virtualization software that brings together App services like Apache, Nginx, MySQL, Solr, Memcache, and many other technologies so that it can run on your own computer. This installation video uses a tool that runs on top of Docker in an abstract, and frankly easier, way.

If you want to learn more about Docker and the many different types of tools that run on top of it, we recommend John Kennedy’s 2018 Drupalcon presentation about Docker.

Another great resource that compares using Docker tools is Michael Anello’s take on the various technologies.

What is Lando

Lando is a thin abstraction layer of tools on top of Docker that makes creating an environment as easy as “lando init” followed by “lando start.” Lando keeps the often confusing devops work of creating a local virtual environment to a few very well documented variable settings that it turns into full docker-compose scripts that Docker, in turn, uses to create a local environment where everything just works together. We’re very excited to see how Lando and Drupal Commerce start to work together.

Contact us and learn more about our custom ecommerce solutions

Mar 23 2018
Mar 23

Matthew Grasmick, grasmash on drupal.org and twitter.com, has written another inspiring post on documentation. As our CTO, Shawn McCabe has often said before, give Acro an easy button, and we’re 100% behind better documentation.

shawn-tweet-001

You can read Matthew’s original blog post for a more thorough and somewhat more roundabout explanation of his proposal. Below I’ve edited the heart of his post into 6 distinct proposals and responded to each one.

In general, I think we can all agree the documentation for Drupal has needed a breath of fresh air and is constant source of frustration for new and experienced users alike.

Proposal #1A: 

Elevate some docs to "official"

Elevate the Drupal 8 User Guide to the status of "Official Documentation"

The idea of creating a tiered documentation has been implemented partially already with the new documentation migration initiative. I think Matthew’s proposal goes one step further by wanting to introduce a new taxonomy term called “Official” for the “documentation page” and “documentation guide” that carries more weight. This idea is very drupally, as we currently do this exact same thing with marking modules as covered by the security policies. Providing a level of assurance that a certain module is produced by people who know what they’re doing and backed up by a team of specialists who voluntarily deal with logistics and other high-level situations.

In general, I think Matthew’s first proposal is a good one. We should implement it by “blessing” certain documentation pages and guides with a stamp of approval / official.

Proposal #1B: 

Prominently Feature "Official Docs"

Update the UX on Drupal.org to prominently feature the Official Documentation on major site entry points.

Along with the “stamp of approval” we would “red light / green light” these pages. Essentially flagging pages as “red light, unofficial” and “green light, official” would go a long way to signalling to the community at large that we take documentation seriously and only greenlight the best of the documentation.

To take Matthew’s proposal seriously, though, we would also need to implement new call-to-actions on non-documentation pages that point to the “official” pages. Maybe revamp the navigation of header and footer on drupal.org to clarify the difference between “official” documentation and “unofficial.”

Proposal #2: 

Adopt Best Practices

We should adopt the following as best practices for all Official Documentation:

This is the heart of the proposals. Matthew wants to constrain the carrot, that “official” stamp of approval, through a high-level checklist of best practices. Agreed. Below is a quick run down of the best practices Matthew is proposing.

  1. A governance process
  2. Use version control
  3. Use and follow documentation standards
  4. Write documentation in markdown format
  5. Use continuous integration process to generate and update screen shots of Drupal interfaces (Additional Info).

Contact us and learn more about our custom ecommerce solutions


Proposal #3: 

Integrate Semantic Versions

Let's integrate the semantic versions (8.5.x, 8.6.x, 9.0.x, etc.) into the Official Drupal.org Documentation UX, much in the way that Symfony and Laravel do.

This is absolutely critical but also a huge technical task (high risk). It means that official documentation would need to have it’s status coupled with minor releases of Drupal. The bigger our official documentation grows, the larger the task will be to maintain it adequately between minor versions. I think the manpower needed to make this idea happen might just burn out the individuals interested in stepping up to make it happen. If we, the Drupal community, can stomach the high risk nature of such a claim, then by all means, we need this.

Perhaps a way to reduce risk is to “evergreen” stamp certain pages, clarifying the fact that certain pages would not likely need updated between minor releases. We could also reach out to Symfony to ask how they manage minor releases and documentation.

Proposal #4: 

Lower Contribution Barrier

Lower the contribution barrier.

Decoupling the documentation contributors could impact the early adopters positively and long term users negatively. I think think the primary way to achieve the goal set out in this proposal is tightly coupled with the next proposal, by letting users of an open source git-powered platform make the edits, we essentially open source our documentation and our processes at the same time.

Check Out Our High Five Drupal Web SeriesI helped spearhead the move of Drupal Commerce’s documentation to the subdomain “docs” for the same reason. We have much better documentation because of this move. Anecdotally, for Drupal Commerce 1, we had maybe a handful of contributors to Drupal’s documentation. Now, for version 2, we have a myriad of contributors (51!!). Scaling documentation is hard, and this is one way to increase involvement.

Personally, I absolutely love this part of Matthew’s proposal. Professionally, I think the community is divided and people are picking sides. They are rightly asking: Why can't Drupal do this very content heavy thing better? Perhaps the answer is: Drupal can do this! We just have to accept this content lives in a version-controlled repo and not in the database.

Proposal #5: 

Host Docs on Repo

Use a repository that is hosted on GitHub (or GitLab) to manage the official Drupal documentation.

Agreed. I’m looking forward to learning how drupal.org will move to one of the git-based hosting services. I’d throw my hat into the github arena, but the initiative for drupal.org has already chosen bitbucket. So let’s use bitbucket.

Proposal #6: 

One Pager

Create a new class of documentation that we're lacking: "The Official One Pager."

Cool, love the idea. I think we could take or leave this. If I were proposing these changes to a client, I would mark this proposal as optional. This helps communicate that this proposal is a lower priority (unless the decision makers want to make it a higher priority) and helping the decision makers understand that this scope increase, while very beneficial, would impact the delivery and bottom line and could easily be moved on to a different delivery schedule.

About Drupal Sun

Drupal Sun is an Evolving Web project. It allows you to:

  • Do full-text search on all the articles in Drupal Planet (thanks to Apache Solr)
  • Facet based on tags, author, or feed
  • Flip through articles quickly (with j/k or arrow keys) to find what you're interested in
  • View the entire article text inline, or in the context of the site where it was created

See the blog post at Evolving Web

Evolving Web