blackbird/hyva-splide-js

An implementation of SplideJS library in Hyvä Theme for Magento 2

2.0.1 2023-09-27 08:53 UTC

Requires

• hyva-themes/magento2-default-theme: *
• magento/framework: *

MIT

• Blackbird Agency

README

hyva-splide-js

An implementation of SplideJS library in Hyvä Theme for Magento 2

You no longer need to worry about how to implement SplideJS in your Magento 2 Hyvä Theme projects.
No manipulations required, instant use after installation.

Splide is lazily loaded and does not affect performances accoding to Hyvä documentation.

How It Works • Installation • Usage • More modules

How It Works

The module simply loads SplideJS on all pages with at least one element in the DOM bearing the CSS class splide
(the class required by SplideJS).

When the library has been loaded on the page, a state stored in the Alpine.store is updated, indicating that SplideJS is ready for use.

The state can also be used to force the library to be loaded at any time, here is an example using forceLoad()

Installation

Requirements

• Hyvä Magento 2 Theme

composer require blackbird/hyva-splide-js

php bin/magento setup:upgrade

In production mode, do not forget to recompile and redeploy the static resources.

Usage

Once the module has been installed, simply add the HTML code required to create a slider, as described in the SplideJS documentation

<section class="splide" id="my-slider">
  <div class="splide__track">
    <ul class="splide__list">
      <li class="splide__slide">Slide 01</li>
      <li class="splide__slide">Slide 02</li>
      <li class="splide__slide">Slide 03</li>
    </ul>
  </div>
</section>

Next, create a function to listen the Alpine.store state is_loading indicating that SplideJS has been loaded, and apply Splide to the HTML elements, as described in the SplideJS documentation.

<?php
use \Blackbird\HyvaSplideJs\Api\HyvaSplideJSInterface;
?>
<script>
    function myXData () {
        return {
            initSlider() {
                if (Alpine.store('<?= HyvaSplideJSInterface::HYVA_SPLIDE_JS ?>').is_loaded) {
                    new Splide('#my-slider', {
                        ...options
                    }).mount();
                }
            }
        }
     }
</script>

You can specify any of the SplideJS options as shown here

Finally, set up the x-data directive and do not forget to call the previous function in an x-effect, to prevent Splide being applied until the library is loaded, and to allow it to be automatically applied when the library is loaded.

<section class="splide" id="my-slider" x-data="myXData()" x-effect="initSlider">
  ...
</section>

Full example

<?php
use \Blackbird\HyvaSplideJs\Api\HyvaSplideJSInterface;
?>
<section class="splide" id="my-slider" x-data="myXData()" x-effect="initSlider">
  <div class="splide__track">
    <ul class="splide__list">
      <li class="splide__slide">Slide 01</li>
      <li class="splide__slide">Slide 02</li>
      <li class="splide__slide">Slide 03</li>
    </ul>
  </div>
</section>
<script>
    function myXData () {
        return {
            initSlider() {
                if (Alpine.store('<?= HyvaSplideJSInterface::HYVA_SPLIDE_JS ?>').is_loaded) {
                    new Splide('#my-slider', {
                        ...options
                    }).mount();
                }
            }
        }
     }
</script>

You can specify any of the SplideJS options as shown here

Example : usage of forceLoad()

Imagine the following case: you do not have an element with the default splide class in your DOM, and you want to add a slider using SplideJS when a user's action is triggered.

In this case, Splide won't be loaded by default on the page, you will have to explicitly request that Splide be loaded.

Alpine.store('<?= HyvaSplideJSInterface::HYVA_SPLIDE_JS ?>').forceLoad()

or

$store.<?= HyvaSplideJSInterface::HYVA_SPLIDE_JS ?>.forceLoad()

To find out exactly which one to use, please see the official Alpine documentation for $store or for Alpine.store.

This will force the library to load on the page, even if no element has the splide class. You can then follow the classic Usage procedure to apply Splide.

More modules

hyva-photo-swipe : An implementation of PhotoSwipe library in Hyvä Theme for Magento 2, full-screen gallery sliders, zoomable and highly customizable.