@shopify/theme-sections

    4.1.1 • Public • Published

    @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:

    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

    Keywords

    Install

    npm i @shopify/theme-sections

    DownloadsWeekly Downloads

    1,601

    Version

    4.1.1

    License

    MIT

    Unpacked Size

    61.5 kB

    Total Files

    10

    Last publish

    Collaborators

    • vsumner
    • marytal
    • themallen
    • thomaskelly
    • nathanpjf
    • shopify-dep
    • goodforonefare
    • lemonmade
    • wizardlyhel
    • antoine.grant
    • tsov
    • andyw8-shopify
    • henrytao
    • hannachen
    • andrewapperley
    • iainmcampbell
    • vividviolet
    • bpscott
    • chris.berthe