The single-page checkout

Basics

The single-page checkout's sections are updated with the default theme's checkout.js plugin.

The plugin includes hook functions containing JavaScript code executed in connection to pre-defined events. The hooks will be discussed later on in this article.

Fallback checkout

If the single-page checkout template is missing from the store theme, but the single-page checkout has been enabled in at least one version, the Barebones theme's single-page checkout will automatically be deployed in the theme. In such a case, it's impossible to apply custom CSS-styles or scripts to the checkout, as they will also come from the Barebones theme.

Defining checkout sections

If the checkout.js plugin is enabled in the theme, each single-page checkout's section has to be marked with the data-checkout-part="PartName" attribute. For example, the billing address could be defined in the following way:

<fieldset id="CheckoutBillingAddress" data-checkout-part="BillingAddress">
	{CheckoutBillingAddress(
		mode: 'form',
		ajax: 'true'
	)}
</fieldset>

If the visitor edits the billing address (managed with the {CheckoutBillingAddress} tag), all checkout sections that are dependent on the billing address will be updated automatically.

Dependencies are defined in the /scripts/plugins/checkout.js file's dependencies object. Learn more about defining dependencies.

Hook functions

All hooks included in the plugin are listed below. Their default settings can be found in the file /scripts/custom.js:

beforeUpdatePart()

Run before updating an individual checkout section.

afterUpdatePart()

Run after updating an individual checkout section.

beforeUpdate()

Run before updating checkout sections.

afterUpdate()

Run after all checkout sections have been updated.

If you'd like to add your own actions connected to hook-tracked events to the theme, add your own code inside the hook functions.

The example below shows the order in which hooks are executed when the address is edited at the checkout. In the example, the payment and shipping methods depend on the address.

1. The customer updates the address at checkout.
2. beforeUpdate() is run.
3. beforeUpdatePart() is run twice: before updating both address dependencies.
4. Both address dependencies are updated (payment and shipping methods included).
5. After both dependencies have been updated, afterUpdatePart() is run (when the server answers after each update).
6. At the end, afterUpdate() is run.

The hooks' content is determined when the plugin is initialized. See the next chapter for instructions.

Initializing the plugin

The plugin is initialized by calling its init() function and defining inside it the settings used by the plugin.:

MCF.Checkout.init({
	afterUpdate: function () {
		MCF.Theme.updateMiniCarts();
	},

	beforeUpdatePart: function ($part) {
		MCF.Loaders.show($part);
	},

	afterUpdatePart: function ($part) {
		MCF.Loaders.hide($part);
	}
});

In the example, the plugin is set to update the shopping cart's previews in the afterUpdate() hook. Additionally, the loading overlay is displayed with the loaders.js plugin while all sections are being updated.

The checkout section to be updated is forwarded to the function as a jQuery object in the $part parameter.

Checkout sections' dependencies

Individual sections of the single-page checkout are dependent on each other. For example, when the address is edited, the available shipping and payment methods may have to be updated.

Dependencies can be managed in the file /scripts/plugins/checkout.js:

dependencies: {
	'ShippingAddress': ['ShippingMethods', 'PaymentMethods'],
	'BillingAddress': ['ShippingMethods', 'PaymentMethods'],
	'ShippingMethods': ['PaymentMethods'],
	'PaymentMethods': []
}

The keys and values of the dependencies object are the values of the checkout sections' data-checkout-part attributes. In the table, they are assigned those values which correspond to the dependent sections.

The shipping and payment methods above are dependent on the delivery address and customer information. Payment methods are dependent on shipping methods and don't have any dependencies of their own.