Optimized One Page Checkout Customization Guide

When doing customizations on the OOPC, even when using a headless front end, the Checkout page and the Order Confirmation page must be customized using Stencil.

In the checkout.HTML and order-confirmation.HTML files, the Checkout and Order Confirmation page are able to have code injected into them. There are elements or Stencil theme objects within each of these files that correlate to the:

• Checkout React app (content.checkount_content)

• Order Confirmation React app (content.order_confirmation_content)

Here's the link to documentation on those objects.

If you're unfamiliar with what a React app is, here's a quick rundown in this YouTube video.

Getting more specific on how Stencil works with our Checkout React app, in the checkout.HTML file, we have a Stencil Object referenced as "checkout.checkout_content". This object is what loads the Checkout React app within the Stencil Checkout page. This means that the Stencil Checkout page works the same as any other page in the theme template, except that this object loads in this React app, which itself cannot be accessed for direct customizations. You cannot directly modify the underlying React app unless you install your custom checkout. We can only add HTML and other customizations layered on top of that app.

In the order-confirmation.HTML file, we have a similar Stencil object referenced as "checkout.order_confirmation_content", which loads a React app for the content on the order confirmation page. This works the same way as described above.

There are a number of nuances to how changes can be made in each of these pages' contexts within the Stencil theme. Given this, I wanted to provide some information and methods for customizations using "third party JavaScript" and CSS. The link included can give more details, but briefly and for our purposes, third party JavaScript relates to any JavaScript loaded during the runtime of the browser via a script tag and that is essentially an overlay on top of an existing web page. For instance, jQuery is a popular example of this kind of application. 

Note that "third party JavaScript" can also refer to npm packages that someone downloads in a Node environment, but for this we'll be talking about it from a browser side perspective, i.e. <script> tags.

Here are the different techniques that can be used:

Styling

The simplest way to customize the Checkout page both inside and outside of the Checkout React app is by not using JavaScript at all, but rather using CSS styles. What is great about using CSS to change the design of a page is that it is applied just once in the loading of an HTML page and will immediately determine the look and feel of any element that is loaded on the page, regardless of when in the order of operations. 

Each style that is applied can be superseded by another style loaded later, but that will also depend on the specificity of how each style is defined. (More about how CSS works if this is a new concept for you - MDN: How CSS Works). 

The main point here is that styles will be applied to any dynamically loaded content, even within the React app and only needs to be defined at the top of the page in the HTML template to immediately go into effect and avoid flicker of unstyled content.

3 JavaScript Injection Techniques

Now there are, in addition to styling, three JavaScript injection techniques we can use for doing anything that can't be done with CSS, such as adding new HTML elements when certain actions occur in a React app, like our OOPC.

A couple of things that will be helpful in understanding the technical challenges with making more advanced customizations on top of the Checkout React app are some fundamental aspects of web development and browser rendering, in particular, understanding two related topics: 

• What the Document Object Model is

• What the order of operations are when a page is being loaded within a client browser like Chrome, Safari, etc. 

These concepts will give important context into the methods I'll describe. Here are links for more information: the Document Object Model / DOM and the order of operations in browser rendering.

Mutation Observers

The fist method I'll talk about, Mutation Observers, is the best approach to making customizations through a JavaScript injection that is outside of the React app, because it gives us the greatest amount of precision among each technique. Since a developer won't have access to the source code of the Checkout React app, they will need to use this Mutation Observer Web API in order to "listen" for changes that are made in the Checkout app as the user interacts with it. 

For instance, when a customer goes to the billing step after the shipping step, the HTML that React has loaded for the shipping step is changed or removed in order to show the customer the shipping step as closed and React also loads in new HTML to reveal the billing step. As this UI is interacted with by the customer, multiple HTML elements are being dynamically changed and a developer needs to adjust the page in a way that can pivot off of those changes. Mutation Observers give developers the tools to do that.

In a more concise way, Mutation Observers are what the name implies. They are a set of Web APIs that observe mutations on the page and will then allow a developer to do something once that change has happened.

Polling Functions

Another way to make a customization to the page is by using Polling Functions, which are functions that are similar to mutation observers in that they essentially listen for when a particular element is loaded on the page, except the standard approach for writing Polling Functions is that they will apply a change only once then go away. 

For instance, if a customer goes to the billing step after the shipping step, the polling function may detect an element that it was waiting for as the billing step is loaded, but it will only apply that change at that particular moment. So, if the customer decides to go back to the shipping step then back to the billing step, that polling function won't be there to detect the change happening for the second time and won't do the desired customization once again. 

There are different ways to construct polling functions, but generally for this reason they are a more basic approach and a much less useful method for making changes on top of an existing React app since a React app can change multiple times and in multiple ways.

Monkey Patching

This is a much more advanced coding concept that is possible within JavaScript as well as other languages, but requires much more in depth understanding of base Web APIs and JavaScript as a whole. Not only that, but this approach is generally considered unwise and a form of "dark wizardry" that, if not done with superb precision and foresight, could have drastic ill effects. I won't go into detail on this methodology, but I mention it here for completeness in listing possible tactics. 

If you're curious, here is a StackOverflow article that describes how to monkey patch the XMLHttpRequest object, which is a Web API that is used whenever an HTTP request is made from the browser.

Reference / Annotations:

• Redbus, INP, and the Magic of requestIdleCallback

• BigCommerce Checkout React app

• BigCommerce Confirmation Page