HyvaTheme — Hyvä Theme Extensions¶
Extension for Magento 2¶
User Manual¶
CopeX GmbH
Web: https://copex.io
Email: office@copex.io
Table of Contents¶
| Section | Page |
|---|---|
| 1 Requirements | 2 |
| 2 Configuration | 2 |
| 3 ViewModels | 2 |
| 3.1 Image ViewModels | 2 |
| 3.2 Cart and Checkout | 3 |
| 3.3 Helper Functions | 3 |
| 4 Plugins | 4 |
| 4.1 Page Builder and Alpine.js Compatibility | 4 |
| 4.2 Configurable Product JSON | 4 |
| 4.3 Store Switcher Extension | 4 |
| 5 Frontend JavaScript Helpers | 5 |
1 Requirements¶
- Magento 2.4 or higher
- PHP 8.1 or higher
- Hyvä Theme installed and active
2 Configuration¶
This module has no backend configuration. It extends the Hyvä Theme automatically after installation.
3 ViewModels¶
The module provides several ViewModels that can be used in Hyvä templates.
3.1 Image ViewModels¶
ViewModel\Image — Manages image file paths, local URL detection, and image cropping/scaling:
- Converts external image URLs to local file paths for server-side resize
- Creates scaled/cropped image versions in the Magento cache directory
- Provides a safe fallback when URLs cannot be resolved
ViewModel\ImageTag — Generates responsive image HTML with srcset:
- Creates <picture> and <img> elements with configurable breakpoints
- Supports lazy loading and fetchpriority attributes
- Used in Hyvä templates for hero images, product images, and banners
3.2 Cart and Checkout¶
ViewModel\Cart — Provides cart helper functions for templates.
Plugin ForceGuestCart — Ensures the guest cart ID exists before the getQuote() call. Prevents race conditions when loading the guest cart.
Plugin Magento/Checkout/CustomerData/Cart — Synchronizes guest and customer quote flag transitions to avoid inconsistent states during checkout.
3.3 Helper Functions¶
| ViewModel | Function |
|---|---|
AppState |
Returns the current Magento application state |
Request |
Provides access to request parameters for templates |
Cms |
CMS helper functions for templates |
Attribute |
Product attribute helper functions |
GiftMessage |
Access to gift message data |
ShippingInfo |
Shipping cost information for product pages |
Product |
General product helper functions |
LogoPathResolver |
Resolves the logo file path |
4 Plugins¶
4.1 Page Builder and Alpine.js Compatibility¶
Plugin PageBuilder/OverrideTemplatePlugin — Ensures that Alpine.js attributes (x-data, @click, etc.) are not removed or altered by Page Builder. Also correctly decodes HTML entities in Page Builder output.
Without this plugin, Magento Page Builder would strip Alpine.js attributes from the HTML, rendering Hyvä components on CMS pages non-functional.
4.2 Configurable Product JSON¶
Plugin ConfigurableData — Enriches the JSON configuration data of configurable products with additional label and configuration attributes. This data is required by Hyvä templates for the product variant selection.
4.3 Store Switcher Extension¶
Rewrite Hyva/Theme/ViewModel/StoreSwitcher — Extends the standard Hyvä store switcher to return active stores across all websites (not just the active website). This enables a full multi-website store switcher.
5 Frontend JavaScript Helpers¶
The module injects the following JavaScript helpers into all Hyvä frontend pages via view/frontend/layout/hyva_default.xml:
| Function | Description |
|---|---|
lazyLoadJS |
Loads JavaScript files when scrolling into the viewport (Intersection Observer) |
lazyLoadCss |
Deferred loading of CSS files |
evaluateScript |
Executes JavaScript from a string (CSP-compliant) |
evaluateScriptsByElement |
Executes all script tags within a DOM element |
updateContentFromTemplates |
Updates page content with Alpine.js-compatible AJAX responses |
| Alpine Collapse Plugin | Smooth collapse animation for Alpine.js x-show directives |
| Popper.js Tooltip | Tooltip positioning library for Hyvä components |
These helpers are available globally in all Hyvä templates.
License¶
Proprietary — CopeX GmbH. One license per production Magento instance. Test and development environments do not require an additional license.