Integration with the theme editor
When merchants customize sections, the HTML of those sections is dynamically added, removed, or re-rendered directly onto the existing DOM without reloading the entire page.
JavaScript that runs when the page loads will not run again when a section is re-rendered or added to the page. This poses a problem for any custom scripts that would need to be re-run.
Theme authors must also make sure that when a section or block is selected, that section or block is visible and remains visible while it is selected. A slideshow, for example, should slide to the block (slide) that is selected and pause while that block is selected.
Section and block JavaScript events
To help with this, the editor fires DOM events within the context of the theme page (that is, the preview of the theme) which the theme's JavaScript should listen and react to:
type |
target |
detail |
bubbles |
cancelable |
Action | Expected |
---|---|---|---|---|---|---|
shopify:section:load |
section | {sectionId} |
yes | no | A section has been added or re-rendered. | Re-execute any JavaScript needed for the section to work and display properly (as if the page had just been loaded). |
shopify:section:unload |
section | {sectionId} |
yes | no | A section has been deleted or is being re-rendered. | Clean up any event listeners, variables, etc., so that nothing breaks when the page is interacted with and no memory leaks occur. |
shopify:section:select |
section | {sectionId,load} |
yes | no | User has selected the section in the sidebar. | Make sure the section is in view and stays in view while selected (scrolling happens automatically). |
shopify:section:deselect |
section | {sectionId} |
yes | no | User has deselected the section in the sidebar. | |
shopify:section:reorder |
section | {sectionId} |
yes | no | A section has been reordered. | |
shopify:block:select |
block | {blockId,sectionId,load} |
yes | no | User has selected the block in the sidebar. | Make sure the block is in view and stays in view while selected (scrolling happens automatically). |
shopify:block:deselect |
block | {blockId,sectionId} |
yes | no | User has deselected the block in the sidebar. |
Events are triggered directly on section or block elements. In other words, event.target
is the section or block element.
Section events are triggered on the <div>
generated by Shopify. Block events are triggered on the elements that have the {{ block.shopify_attributes }}
.
Events bubble up like other DOM events, such as click
and keydown
. This allows your scripts to listen for events using addEventListener
or using a JavaScript library like jQuery. More information, like the section ID, is attached in event.detail
. If you're using an older version of jQuery, you might have to use event.originalEvent.detail
instead.
The event.detail.load
property in the shopify:section:select
and shopify:block:select
events indicates whether the event is being triggered as part of a section re-render (i.e. after a shopify:section:load
event), or following a selection by the user.
Detecting the theme editor
From Liquid
The request.design_mode
global variable can be used in your theme's Liquid files to detect whether the storefront is being viewed in the theme editor. The value of the variable is set to true
when viewing the theme editor, otherwise it is set to false
.
{% if request.design_mode %}
<!-- This will only render in the theme editor -->
{% endif %}
From JavasScript
The Shopify.designMode
global variable can be used in your theme's JavaScript files to detect whether the storefront is being viewed in the theme editor. The value of the variable is set to true
when viewing the theme editor, otherwise it is set to undefined
.
if (Shopify.designMode) {
// This will only happen in the theme editor
}