Stimulus Shopify Sections Example

readme.md

Logic

We are using Stimulus.js and Siema Carousel to create a Product slideshow Shopify Section. Because stimulus accepts options from element attributes, we can pass customisations to the carousel from the sections HTML markup and thus we can avoid infusing JavaScript.

The code below can give you some understanding of how it is achieved. It's an extraction from a project I have in production and of course without the related stylesheets and css it will not function as a drop-in solution but hopefully gives you some clarity on how leveraging stimulus in a Shopify theme benefits one greatly.

Couple of key points and takeaways are the the way we wire it up, the "controller" context where we pass in option is set on the first div tag:

<div
  class="row pt-{{ section.settings.gutter }} pb-3"
  data-carousel-draggable-value="{{- section.settings.draggable }}"
  data-carousel-interval-value="{{- section.settings.interval | append: '000' -}}"
  data-carousel-loop-value="{{- section.settings.loop }}"
  data-carousel-per-page-value="{{- section.settings.per_page }}"
  data-controller="carousel">

This option are passed the static class values in the controller, eg:

static values = {
  startIndex: Number,
  draggable: Boolean,
  perPage: Number,
  loop: Boolean,
  interval: Number,
  initHidden: Boolean,
  hydrate: String,
  loadOnClick: Boolean,
  duration: Number
}

You will need to read about Stimulus to understand what is happening, so do that. Nonetheless this code stands as an example of how one would leverage stimulus in a Shopify theme project.

collection_carousel.liquid

<!-- gutter padding patch -->
{%- if section.settings.gutter != 0 -%}
  {%- assign gutter = section.settings.gutter | plus: 1 -%}
{%- else -%}
  {%- assign gutter = section.settings.gutter -%}
{%- endif -%}

<div
  class="row pt-{{ section.settings.gutter }} pb-3"
  data-carousel-draggable-value="{{- section.settings.draggable }}"
  data-carousel-interval-value="{{- section.settings.interval | append: '000' -}}"
  data-carousel-loop-value="{{- section.settings.loop }}"
  data-carousel-per-page-value="{{- section.settings.per_page }}"
  data-controller="carousel">

  <div class="previous d-flex ai-center">
    <button aria-label="Previous" data-action="click->carousel#prev" type="button">
      {%- include 'icon.chevron-left' -%}
    </button>
  </div>
  <div class="next d-flex ai-center">
    <button aria-label="Next" data-action="click->carousel#next" type="button">
      {%- include 'icon.chevron-right' -%}
    </button>
  </div>

  <div class="col px-2">
    <div class="row" data-carousel-target="siema">

      {%- assign before = section.settings.per_page | minus: 1 -%}

      {%- if section.settings.collection != blank -%}

        {%- for product in collections[section.settings.collection].products limit: 15 -%}
          {%- if forloop.index > section.settings.per_page -%}
            {%- assign class = 'col d-none px-' | append: section.settings.gutter -%}
          {%- else -%}
            {%- assign class = 'col px-' | append: section.settings.gutter -%}
          {%- endif -%}

          {%- render 'product' with product
          , grid: class
          , target: 'data-carousel-target="slide"'  -%}
        {%- endfor -%}

      {%- else -%}

        <!-- section preset defaults -->
        {%- for product in (1..6) -%}

          {%- if forloop.first == true  -%}
            {%- assign grid = 'col pr-1' -%}
          {%- elsif forloop.index == slides  -%}
            {%- assign grid = 'col pl-1' -%}
          {%- elsif forloop.index < section.settings.slides  -%}
            {%- assign grid = 'col px-1' -%}
          {%- else -%}
            {%- assign grid = 'col pr-1 d-none' -%}
          {%- endif -%}

          <div class="product-item col pr-1" data-carousel-target="slide">
            <a class="d-block" href="#">
              <div class="aspect-ratio">
                {{ 'image' | placeholder_svg_tag: 'image' }}
              </div>
            </a>
          </div>
        {%- endfor -%}

      {%- endif -%}

    </div>
  </div>

</div>

{% schema %}
{
  "name": "Collection Slideshow",
  "class": "collection-slideshow",
  "tag": "section",
  "settings": [
    {
      "type": "header",
      "content": "Collection Slideshow",
      "info": "Provides a collection of as a carousel slideshow"
    },
    {
      "type": "checkbox",
      "id": "loop",
      "label": "Loop",
      "default": false
    },
    {
      "type": "checkbox",
      "id": "draggable",
      "label": "Draggable",
      "default": true
    },
    {
      "type": "checkbox",
      "id": "show_arrows",
      "label": "Show Buttons",
      "default": true
    },
    {
      "type": "range",
      "id": "per_page",
      "min": 2,
      "max": 8,
      "step": 2,
      "label": "Showing (Per Page)",
      "default": 6,
      "info": "Products are responsive based on maximum matrix sizes."
    },
    {
      "type": "header",
      "content": "Style",
      "info": "Styling options for the slideshow"
    },
    {
      "type": "range",
      "id": "gutter",
      "label": "Gutter",
      "min": 0,
      "max": 5,
      "step": 1,
      "default": 0
    },
    {
      "label": "Collection",
      "id": "collection",
      "type": "collection",
      "info": "Products will be displayed in the same order defined within the collection"
    }
  ],
  "presets": [
    {
      "name": "Collection Slideshow",
      "category": "Collection"
    }
  ]
}
{% endschema %}

controller.js

// @ts-nocheck

import { Controller } from 'stimulus'
import Siema from 'siema'

/**
 * Carousel
 *
 * @export
 * @class Carousel
 * @extends {Controller}
 * @typedef {Targets.Carousel} ITargets
 * @typedef {Model.IValues<Carousel.values>} IValues
 * @typedef {ITargets & IValues & Carousel} ICarousel
 */
export class Carousel extends Controller {

  static cache = {
    loadOnClick: []
  }

  /**
   * Default Dataset Values
   *
   * @static
   * @memberof Carousel
   */
  static values = {
    startIndex: Number,
    draggable: Boolean,
    perPage: Number,
    loop: Boolean,
    interval: Number,
    initHidden: Boolean,
    hydrate: String,
    loadOnClick: Boolean,
    duration: Number
  }

  /**
   * Stimulus Targets
   *
   * @static
   * @memberof Slideshow
   */
  static targets = [
    'slide',
    'siema'
  ]

  /**
   * Stimulus Initialize
   */
  initialize () {

    this.hydrate()

  }

  /**
   * Stimulus Connect
   *
   * @this {ICarousel}
   */
  connect () {

    this.slider = new Siema({
      selector: this.siemaTarget,
      loop: this.loopValue,
      startIndex: this.startIndexValue,
      duration: 300,
      easing: 'ease-out',
      onInit: this.onInit.bind(this),
      onChange: this.onChange.bind(this),
      draggable: this.draggableValue,
      perPage: this.perPageValue <= 1 ? 1 : {
        0: 2,
        480: 2,
        768: this.perPageValue - 2,
        1024: this.perPageValue - 1,
        1400: this.perPageValue
      }
    })
  }

  /**
   * Stimulus Disconnect
   */
  disconnect () {

    if (this.loadOnClickValue) {
      Carousel.cache.loadOnClick.forEach(slide => {
        if (!slide.classList.contains('d-none')) {
          slide.classList.add('d-none')
        }
      })
    }
    // this.onMouseOver()
    this.slider.destroy()

  }

  /**
   * Reset
   * Executes on the Turbo `before-cache` event
   */
  reset () {

    this.slider.destroy(true)

  }

  /**
   * Hydrate
   * Modifies the SSR content
   *
   * @this {ICarousel}
   */
  hydrate () {

    if (this.siemaTarget.classList.contains('row')) {
      this.siemaTarget.classList.remove('row')
      this.slideTargets.forEach(({ classList }) => classList.remove('d-none'))
    } else if (this.initHiddenValue === true) {
      this.slideTargets.forEach(({ classList }) => classList.remove('d-none'))
    } else if (this.hasHydrateValue) {
      this.slideTargets.forEach(({ classList }) => classList.remove('d-none'))
    }

  }

  /**
   * Siema
   * Next Button
   */
  next () {

    this.slider.next()

  }

  /**
   * Siema
   * Previous Button
   */
  prev () {

    this.slider.prev()

  }

  onMouseOver () {
    if (this.intervalValue > 0) {
      clearInterval(this.interval)
    }
  }

  onMouseOut () {

    this.onInit()

  }

  onInit () {

    if (this.intervalValue > 0) {
      this.interval = setInterval(() => this.slider.next(), this.intervalValue)
    }

  }

  /**
   * Siema
   * onChange event
   */
  onChange () {

    this.startIndexValue = this.slider.currentSlide

    if (this.loadOnClickValue) {

      const slide = this.slideTargets[this.slider.currentSlide]

      if (slide.classList.contains('d-none')) {
        slide.classList.remove('d-none')
        Carousel.cache.loadOnClick.push(slide)
      } else {
        Carousel.cache.loadOnClick.forEach(slide => {
          if (!slide.classList.contains('d-none')) {
            slide.classList.add('d-none')
          }
        })

      }

    }
  }

}