README.md

@shopify/theme-sections

Getting Started

Theme Scripts can be used in any theme project. To take advantage of semantic versioning and easy updates, we recommend using NPM or Yarn to include them in your project:

yarn add @shopify/theme-sections

and then import the functions you wish to use through ES6 imports:

import * as sections from '@shopify/theme-sections';

If you prefer not to use a package manager, you can download the latest version of Theme Sections and include it in your project manually from the following links:

• theme-sections.js
• theme-sections.min.js

These files make Theme Sections accessible via the Shopify.theme.sections global variable.

Sections

Default Properties

Every registered section has the following accessible properties:

Property	Description
this.id	The unique ID for the section
this.container	The DOM element for the section container
this.type	The type of section

Register a section

sections.register('type', { properties });

Register a section type to the list of available sections to be loaded. The section type should match the section type specified on the section container using data-section-type attribute.

<div class="featured-product" data-section-type="featured-product" data-section-id="{{ section.id }}">
  <!-- section liquid -->
</div>

import { register } from '@shopify/theme-sections';

register('featured-product', {
  publicMethod: function() {
    // Custom public section method
  },

  _privateMethod: function() {
    // Custom private section method
  },

  // Shortcut function called when a section is loaded via 'sections.load()' or by the Theme Editor 'shopify:section:load' event.
  onLoad: function() {
    // Do something when a section instance is loaded
  },

  // Shortcut function called when a section unloaded by the Theme Editor 'shopify:section:unload' event.
  onUnload: function() {
    // Do something when a section instance is unloaded
  },

  // Shortcut function called when a section is selected by the Theme Editor 'shopify:section:select' event.
  onSelect: function() {
    // Do something when a section instance is selected
  },

  // Shortcut function called when a section is deselected by the Theme Editor 'shopify:section:deselect' event.
  onDeselect: function() {
    // Do something when a section instance is deselected
  },

  // Shortcut function called when a section block is selected by the Theme Editor 'shopify:block:select' event.
  onBlockSelect: function() {
    // Do something when a section block is selected
  },

  // Shortcut function called when a section block is deselected by the Theme Editor 'shopify:block:deselect' event.
  onBlockDeselect: function() {
    // Do something when a section block is deselected
  }
});

Load sections

Single section

import { load } from '@shopify/theme-sections';

load('featured-product');

Load a single section type on the page.

Multiple sections

import { load } from '@shopify/theme-sections';

load(['featured-product', 'map']);

Load multiple section types on the page.

All sections

import { load } from '@shopify/theme-sections';

load('*');

Load all registered sections on the page. This triggers the onLoad() method of each section and also fires the load section event.

Section instances

isInstance('type');

Returns a boolean that indicates if a particular section instance is present on the page or not.

getInstances('type');

Returns an array of instances that match the provided type(s).

import { getInstances } from '@shopify/theme-sections';

const instances = getInstances('featured-product');
instances.forEach(function(instance) {
  console.log(
    'A section of type ' +
      instance.type +
      ' and with an id of ' +
      instance.id +
      'is loaded on the page'
  );
});

Extensions

this.extend(extension);

Creating an extension is simply creating an object with a list of methods you'd like to extend. For example, if you were extending a section it would look similar to this:

var extension = {
  // the init method is a special method that is called when the extension is loaded. It is not available for the section to use.
  init: function() {
    this.on('section_load', function() {
      console.log('Do something else when the section loads');
    });
  },

  // Overrides the onLoad() method of the section
  onLoad: function() {
    console.log('My custom load event');
  },

  getProduct: function(id) {
    return this.products[id];
  },

  setProduct: function(product) {
    this.products[product.id] = product;
  }
};

Extending sections

Single section

sections.extend('type', extension);

Extend all current instances of a single section type

Multiple sections

sections.extend(['types'], extension);

Extend all current instances of multiple section types

All sections

sections.extend('*', extension);

Extend all current of any type