How to make Alpine V2 and V3 compatible code in Hyva themes?

In today’s article, we will guide you on how to make Alpine v2 and v3 compatible code in Hyva themes.

The developer who developed the extension has a question about which Alpine.js version is supported.

Creating Alpine components that seamlessly function with both version 2 and version 3 is relatively straightforward. This page provides valuable insights on key considerations to ensure your extensions remain compatible with any version of Hyvä.

To ensure compatibility with both Alpine.js versions 2 and 3, incorporate the directives x-spread and x-bind into your code.

To ensure seamless compatibility across Alpine.js versions 2 and 3, include both x-spread for v2 and x-bind for v3 in your codebase.

Example:

<div x-data="{ attributes: { class: 'bg-blue-500', style: 'color: white;' } }">
    <div x-spread="attributes">
        <p x-bind:title="attributes['class']">Hover over me!</p>
    </div>
</div>

In this above example:

• x-data initializes a data object with an attributes property containing an object with some CSS attributes.
• x-spread directive spreads the attributes from the attributes object onto the parent <div>. This allows the dynamic addition of attributes to the element based on the data object.
• x-bind:title dynamically binds the title attribute of the <p> element to the value of attributes[‘class’]. This means that when you hover over the paragraph, you’ll see a tooltip with the value of the class attribute.
• This code is compatible with both Alpine.js v2 and v3, as it uses commonly supported directives and syntax for data manipulation and attribute binding.

New to Hyvä?? Learn about the Hyvä Theme from basics!

Use of $el

• In Alpine.js v2, $el consistently points to the root DOM element of the component. However, in Alpine.js v3, $el now refers to the DOM element on which the current binding is being evaluated.
• To ensure compatibility with both Alpine.js versions 2 and 3, limit the use of $el solely to the base element of the component.
• If you require a reference to another element within your component, adhere to these guidelines:

1. Alpine.js v2: Use x-ref to assign a reference to the element.
2. Alpine.js v3: Utilize querySelector() in vanilla JavaScript to fetch the desired element.

By following this approach, your components will remain compatible across both Alpine.js versions.

Example: 

• In Alpine.js version 2, you would typically use $el to reference the root DOM element of the component.

<div x-data="{ isOpen: false }">
    <button x-on:click="isOpen = !isOpen">Toggle</button>
    <div x-show="isOpen" x-ref="myDiv">Content</div>
</div>

• In Alpine.js version 3, $el refers to the DOM element currently being evaluated within the binding context.

<div x-data="{ isOpen: false }">
    <button x-on:click="isOpen = !isOpen">Toggle</button>
    <div x-show="isOpen" x-ref="myDiv" x-init="$el.classList.add('initialized')">Content</div>
</div>

In the above Alpine.js v3 example, $el in x-init refers to the <div> element with the x-ref=”myDiv” attribute.

Using $root

In Alpine.js v2, it’s advisable to avoid using $root altogether. However, if you do need to use it, you can create an alias to $root in an initialization method to ensure compatibility with Alpine.js v2.

Certainly! If you need to use $root in Alpine.js v2 but want to ensure compatibility with Alpine.js v3, you can alias it to $root in an initialization method. Here’s how you can do it:

<div x-data="initComponent()">
    <button @click="$root.someMethod()">Click me</button>
</div>

<script>
    function initComponent() {
        return {
            $root: Alpine.version.startsWith('3') ? this : window.Alpine,
            // Other component properties and methods
        };
    }
</script>

In this example:

• The initComponent function is used as the x-data value. This function returns an object that contains the component’s properties and methods.
• Inside initComponent, $root is aliased to either this (the component itself) or window. Alpine depending on whether the current Alpine.js version starts with ‘3’.
• This ensures that $root is available and points to the correct object regardless of the Alpine.js version being used.

By using this approach, you can write code that is compatible with both Alpine.js v2 and v3 while still being able to use $root when needed.

Using x-init

To ensure compatibility with Alpine.js v2 while using Alpine.js v3, make sure not to rely on the automatic invocation of the init method. Instead, explicitly specify x-init=”init” to ensure consistent behavior across both versions.

Usage of @click.away or @click.outside

To accommodate both Alpine.js versions in your component utilize both modifiers for handling clicks outside elements. Use click.away for Alpine.js v2 and click.outside for Alpine.js v3.

<div x-data="initComponent()">
    <div x-show="open" @click.away="closeDropdown" @click.outside="closeDropdown">
        Dropdown content
    </div>
    <button @click="toggleDropdown">Toggle Dropdown</button>
</div>

<script>
    function initComponent() {
        return {
            open: false,
            toggleDropdown() {
                this.open = !this.open;
            },
            closeDropdown() {
                this.open = false;
            }
        };
    }
</script>

In this example:

• The initComponent function initializes the component with a data property open to control the visibility of the dropdown.
• The toggleDropdown method toggles the value of open when the button is clicked.
• Both @click.away and @click.outside directives are included in the <div> element. Alpine.js v2 will use click.away while Alpine.js v3 will use click.outside. They both call the closeDropdown method when a click occurs outside the dropdown, effectively closing it.

This setup ensures compatibility with both Alpine.js v2 and v3, allowing the component to handle clicks outside the dropdown element regardless of the Alpine.js version being used.

We use 

<div @click.away.outside="open = false"> … </div>

Instead of 

<div x-show="open" @click.away="callFunction" @click.outside="callFunction">
        Dropdown content
    </div>

Using Alpine plugins

• To ensure cross-version compatibility with Alpine.js components, it’s recommended to refrain from using plugins unless they are available for both Alpine.js versions. For instance, the intersect plugin is native to Alpine.js v3, and a backport for v2 is provided as part of Hyvä. Thus, you can safely utilize x-intersect=”…” regardless of the Alpine version.
• If you opt to rely on other plugins, you’ll likely need to backport them to version 2 yourself and ensure the correct version is loaded. The have-libraries.json file specifies the versions of libraries to load, and you can access these versions using the getVersionIdFor method in the view model. This approach ensures the appropriate versions of Alpine.js and intersect plugins are loaded into your theme.

<?php
/** @var Template $block */
/** @var ViewModelRegistry $viewModels */
use Hyva\Theme\Model\ViewModelRegistry;
use Hyva\Theme\ViewModel\ThemeLibrariesConfig;
use Magento\Framework\View\Element\Template;

$themeLibrary = $viewModels->require(ThemeLibrariesConfig::class);
$version = $themeLibrary->getVersionIdFor('intersect-plugin')
   ?: $themeLibrary->getVersionIdFor('alpine') ?: '2';?>
<?= /** @noEscape */ $block->fetchView($block->getTemplateFile("Hyva_Theme::page/js/plugins/v${version}/intersect.phtml")) ?>

The provided code dynamically determines the version of the intersect plugin or Alpine.js configured for the theme. If no specific version for the intersect plugin is specified, it checks if an Alpine.js version is provided. If neither is specified, it defaults to version 2. 

It then uses this version information to construct the fully qualified path to render the appropriate template file. This pattern can similarly be utilized to render custom JavaScript code based on the Alpine version of a theme.

Warning if the Alpine version is too old

If your module only supports one version of Alpine.js, it’s crucial to clearly state this in the module README and documentation. However, in scenarios where a Magento instance has multiple store views with different themes, each theme might utilize a different Alpine version. 

To specify a dependency on a minimum Alpine version, modules can employ layout XML to add a child to the require-alpine-v3 block. This ensures proper management of dependencies and compatibility across different themes within the Magento instance.

<body>
   <referenceBlock name="require-alpine-v3">
       <block name="My_Module"/>
   </referenceBlock>
</body>

If this module is used with a theme that employs a lower version of Alpine.js, a warning will be logged to the browser console.

The current Alpine.js version is 2.8.2, but version >= 3 is required by the following extensions:
[
   'My_Module'
]

The name of the child block should match the module name, since it will be listed in the error message.

More resources on Hyva themes:

• Check out the InstaBuild for Hyvä Themes: Ready-made Hyva theme templates for faster storefront development!
• Hyva Themes Development – For Online Merchants
• Hyvä Theme Benefits that your store needs
• 10 Best Hyva Compatibility Extension Providers For Magento 2 Stores
• Hyvä VS PWA: Where to Invest?
• How a Slow Magento Website Can Cost You Advertising Dollars
• Mobile Commerce: How Hyva Themes Boost Mobile Conversions