Enterprise is a powerful and customisable theme designed for large scale e-commerce stores. Built using web components, it offers a highly modular architecture that makes customisation and maintenance easier than ever.
In addition, Enterprise is optimised for speed, ensuring stores run as fast as possible to provide customers with a seamless shopping experience.
Caution
The following guide is not intended as general user guidance. It is important to note that we do not offer general support on any custom development to our themes, or provide assistance on leveraging any of the items outlined below.
Custom JavaScript events
Enterprise broadcasts many custom events for ease of extensibility, detailed in this section.
If you would like to add your own JS to Enterprise, we recommend using the custom.js file supplied with the theme and referencing it using Theme settings > Advanced > Custom HTML.
As a brief overview, Enterprise:
- Broadcasts many JS events
- Is built using web components
- Follows a code splitting architecture
- Is completely custom built (no JS libraries other than instant.page)
- Has a number of JS utilities
Events are named in the following convention:
[on/dispatch]:[subject]:[action]
Where dispatch will trigger an event to occur and on indicates an event has occurred.
All return data detailed in this section is returned within the event.detail object.
Tip: When in the Theme Editor, the details of each custom event will be logged out in the Dev Tools console every time one is triggered.
The available events are:
on:variant:change
on:cart:add
on:cart:error
on:line-item:change
on:cart-drawer:before-open
on:cart-drawer:after-open
on:cart-drawer:after-close
on:quickbuy:before-open
on:quickbuy:after-open
on:quickbuy:after-close
dispatch:cart-drawer:open
dispatch:cart-drawer:refresh
dispatch:cart-drawer:close
on:debounced-resize
on:breakpoint-change
on:variant:change
Fires whenever a variant is selected (e.g. product page, quick buy, featured product etc).
How to listen:
document.addEventListener('on:variant:change', (event) => {
// your code here
});
Returned data:
- form: the product form content
- variant: the selected variant object
- product: the product object (includes a list of all variants)
on:cart:add
Fires when a variant has been added to the cart, where it didn’t exist in the cart before. This event does not fire when the added variant was already in the cart. To listen for this, see the on:line-item:change event.
How to listen:
document.addEventListener('on:cart:add', (event) => {
// your code here
});
Returned data:
- cart: the new cart object after the variant was added
- variantId: id of the variant that was just added to the cart
on:line-item:change
Fires when the quantity of an item already in the cart is updated. Note, if the newQuantity is 0, this indicates the item was removed from that cart.
Note, when adding a variant to the cart - this event will fire if that variant is already in the cart (i.e. the quantity is incremented). In this situation, on:cart:add will not fire.
How to listen:
document.addEventListener('on:line-item:change', (event) => {
// your code here
});
Returned data:
- cart: the new cart object after the quantity change was completed
- variantId: id of the variant that was just updated
- newQuantity: new quantity of the line item
- oldQuantity: old quantity of the line item
on:cart:error
Fires when an action related to the cart has failed, for example adding too much quantity of an item to the cart.
How to listen:
document.addEventListener('on:cart:error', (event) => {
// your code here
});
Returned data:
- error: the error message
on:cart-drawer:before-open
Fires before the cart drawer opens.
How to listen:
document.addEventListener('on:cart-drawer:before-open', (event) => {
// your code here
});
on:cart-drawer:after-open
Fires after the cart drawer has finished opening.
How to listen:
document.addEventListener('on:cart-drawer:after-open', (event) => {
// your code here
});
on:cart-drawer:after-close
Fires after the cart drawer has finished closing.
How to listen:
document.addEventListener('on:cart-drawer:after-close', (event) => {
// your code here
});
on:quickbuy:before-open
Fires before the quick buy drawer opens.
How to listen:
document.addEventListener('on:quickbuy:before-open', (event) => {
// your code here
});
on:quickbuy:after-open
Fires after the quick buy drawer has finished opening.
How to listen:
document.addEventListener('on:quickbuy:after-open', (event) => {
// your code here
});
on:quickbuy:after-close
Fires after the quick buy drawer has finished closing.
How to listen:
document.addEventListener('on:quickbuy:after-close', (event) => {
// your code here
});
dispatch:cart-drawer:open
Opens the cart drawer (if enabled in the theme settings).
How to trigger:
document.dispatchEvent(new CustomEvent('dispatch:cart-drawer:open'));
You can optionally pass in a detail object with a property of opener, which specifies the DOM element that should be focussed on when the drawer is closed.
Example:
document.getElementById('header-search').addEventListener('keydown', (evt) => {
if (evt.keyCode === 67) {
evt.preventDefault();
document.dispatchEvent(new CustomEvent('dispatch:cart-drawer:open', {
detail: {
opener: evt.target
}
}));
}
});
In this example, we attach a keydown listener to the search input in the header. If the user presses the c key, it prevents the default behaviour (which would be to type the letter c in the input) and dispatches the dispatch:cart-drawer:open event with a detail object that specifies the search input as the opener. When the cart drawer is closed, focus is returned to the search input.
dispatch:cart-drawer:refresh
Refreshes the contents of the cart drawer.
This event is useful when you are adding variants to the cart and would like to instruct the theme to re-render the cart drawer.
How to trigger:
document.dispatchEvent(new CustomEvent('dispatch:cart-drawer:refresh', {
bubbles: true
}));
dispatch:cart-drawer:close
Closes the cart drawer.
How to trigger:
document.dispatchEvent(new CustomEvent('dispatch:cart-drawer:close'));
on:debounced-resize
Fires when the viewport finishes resizing (debounced to 300ms by default).
How to listen:
window.addEventListener('on:debounced-resize', (event) => {
// your code here
});
on:breakpoint-change
Fires when the breakpoint of the viewport changes. See the Media queries section in this file for more information.
Example:
window.addEventListener('on:breakpoint-change', (event) => {
if (theme.mediaMatches.md) {
console.log(‘we are not on mobile’);
}
});
Web components
Enterprise utilises web components to the fullest.
Web components are a set of standardised APIs that allow developers to create custom, reusable HTML elements that can be used across different web pages and applications. They consist of three main things: custom elements, shadow DOM and HTML Templates.
See the Mozilla Web Component documentation for more.
Third party JavaScript dependencies
Enterprise only has one third-party dependency: instant.page.
It's included locally and is only active if it has been enabled in Theme settings > Advanced > Preload links on hover.
Instant.page is a JavaScript library that speeds up page loads by preloading links as soon as the customer hovers over them.
Code splitting
We followed the ‘code splitting’ technique when building Enterprise.
Code splitting consists of writing in JavaScript (and CSS) in a modularised way within typically small, more manageable files that can be loaded on-demand, as needed. The idea is to improve the performance of our theme by reducing the amount of code that needs to be loaded upfront.
If the customer is visiting a specific page of the theme that requires certain JavaScript functionality, only the code needed for that page will be loaded, rather than one large JavaScript file containing largely unused code. For example, the file media-gallery.js will only be loaded if there is a media gallery on the page.
Shopify uses HTTP/2, which is the newer version of the HTTP protocol used to deliver web content. HTTP/2 supports multiplexing, which means that multiple requests can effectively be sent over a single connection at the same time - meaning multiple JS files are essentially served at the speed of a single file.
The only JS file which is served on every page in Enterprise is main.js. This file contains utility JS which is likely to be needed by many scripts. This is outlined more in the next section.
Utilities
Enterprise provides a few utility functions, contained in main.js.
Lazy loading
Lazy loading is a technique for delaying the loading of certain elements until they are needed, which can help improve page load times.
Within Enterprise, images are lazy loaded using the browsers native lazy load feature.
We use an initLazyScript JavaScript function to load relevant scripts when a specific element is scrolled into view.
Cookies
Cookies are small pieces of data that can be stored on a user's computer. They can be useful for tracking user activity, remembering user preferences or other similar purposes.
We use three functions to manage cookies:
- The setCookie function sets a cookie with a given name, value and number of days until it should expire
- The getCookie function takes in the name of a cookie to retrieve its value
- The deleteCookie function takes in the name of a cookie to delete it
Media queries
The theme creates a theme.mediaMatches object (defined in theme.liquid) for several key screen sizes specified in our theme, and adds listeners for each media query.
These are:
mediaQueries: {
sm: '(min-width: 600px)',
md: '(min-width: 769px)',
lg: '(min-width: 1024px)',
xl: '(min-width: 1280px)',
xxl: '(min-width: 1536px)',
portrait: '(orientation: portrait)'
}
If a breakpoint is crossed, the mediaMatches values are updated and a on:breakpoint-change event is dispatched.
You can request the entire theme.mediaMatches object to check which media queries are currently matched. In this case, the returned data will be an object with the names of the media queries as keys and boolean values indicating whether they are currently matched or not.
Example:
{
sm: true,
md: true,
lg: true,
xl: true,
xxl: false,
portrait: false
}
You can reference a specific media query to check if it's currently matched by using:
theme.mediaMatches.lg
To check if you’re on mobile you can use:
!theme.mediaMatches.md
If you want to perform some action when the breakpoint changes, you can listen for the breakpoint-change event on the window object.
Example:
window.addEventListener('on:breakpoint-change', (event) => {
// your code here
});
Can't find what you're looking for?
Our support staff are here to answer your queries, so don't hesitate to write to us!
Contact us