1 Installation
2 Functionalities
- 2.1 Icon
- 2.2 Image View Model
- 2.3 Category page headline
- 2.4 Page scroll
- 2.5 Qty Increment
- 2.6 Tooltip
- 2.7 JsMageInit
- 2.8 mgsGetJqueryWidgetInstance
- 2.9 View Transition

https://github.com/magesuite/theme-helpers

This module contains blocks and helpers required by theme-creativeshop

Installation

This module is a part of MageSuite metapackage

composer require "creativestyle/magesuite-theme-helpers" ^1.0.0

Functionalities

Icon

Block introduce in order to easily add icons into phtml templates.

\MageSuite\ThemeHelpers\Block\Icon

Example

<block class="MageSuite\ThemeHelpers\Block\Icon" name="icon.name">
    <arguments>
        <argument name="icon_url" xsi:type="string">icon path</argument> //f.e. images/icons/icon-arrow-up.svg
        <argument name="css_class" xsi:type="string">css class</argument>
        <argument name="alt_text" xsi:type="string" translate="true">Alt text</argument>
        <argument name="lazy_loaded" xsi:type="boolean">true</argument> // true/false
        <argument name="inlined" xsi:type="boolean">true</argument> // true/false
        <argument name="width" xsi:type="number">200</argument>
        <argument name="height" xsi:type="number">150</argument>
    </arguments>
</block>

For lazy loading theme-creativeshop/src/web/js/vendor/lazyload.js script is used.

SVG file can be inlined. theme-creativeshop/src/web/js/vendor/inline-svg.js script is used in order to inline svg file.

Example of inlined icon

Example of lazyloaded, not inlined icon:

Image View Model

If you want to fetch product’s main image, you can do it via MageSuite\ThemeHelpers\ViewModel\Image view model. Example usage:

layout.xml:

<block name="sample" class="Magento\Catalog\Block\Category\View">
    <arguments>
        <argument name="image_view_model" xsi:type="object">MageSuite\ThemeHelpers\ViewModel\Image</argument>
    </arguments>
</block>

block.phtml:

<?php
/** @var \Magento\Catalog\Block\Category\View $block */
/** @var \MageSuite\ThemeHelpers\ViewModel\Image $imageViewModel */
$imageViewModel = $block->getImageViewModel();
$product = $block->getProduct();
?>

<img src="<?= /* @noEscape */ $imageViewModel->getImageUrl($product, 'swatch_image') ?>" />

You can find optional third attributes parameter here: MageSuite_ThemeHelpers\ViewModel\Image.

Category page headline

Category pages use an enhanced headline template. Collection size can be displayed.

\MageSuite\ThemeHelpers\Block\Category\View\Headline

Additional methods are provided:

$block->getHeadline()

$block->getCollectionSize()

$block->getIcon()

Collection size can be switch off by xml setting:

  <block class="MageSuite\ThemeHelpers\Block\Category\View\Headline" name="category.page.headline" template="MageSuite_ThemeHelpers::category/headline.phtml">
      <arguments>
          <argument name="show_collection_size" xsi:type="boolean">true</argument>
      </arguments>
  </block>

Page scroll

In order to display scroll to top button page_scroll.xml layout is added. It can be used as a layout update to show scroll to top button on all pages on a specific kind of page (f.e. cms pages).

<update handle="page_scroll" />

There are the following xml setting for scroll to top functionality:

  <block name="page.scroll" template="MageSuite_ThemeHelpers::page-scroll.phtml" after="-">
      <arguments>
          <argument xsi:type="string" name="wrapper_tag">div</argument>
          <argument xsi:type="string" name="wrapper_css_class">cs-page-scroll cs-visually-hidden</argument>
          <argument xsi:type="string" name="button_css_class">cs-page-scroll__button</argument>
          <argument name="label" xsi:type="string" translate="true">Go to Top</argument>
          <argument name="visible" xsi:type="boolean">true</argument>
      </arguments>
</block>

Styling and scripts

Styling and scripts are not included by default in theme-creativeshop as the component is optional.

Styles: theme-creativeshop/src/components/page-scroll/page-scroll.scss

Scripts: theme-creativeshop/src/components/page-scroll/page-scroll.scss

In order to add tooltip styles and scripts in the child theme import the tooltip component in an entry file:

import 'components/page-scroll';

Qty Increment

Template used to enhanced usability on numeric input type by adding -/+ button. This template is used across the whole shop.

Example of the qty-increment implementation: theme-creativeshop/src/Magento_Checkout/templates/cart/item/qty/qty.phtml

<?php
$item = $block->getData('item');

echo $this->getLayout()
    ->createBlock(\Magento\Framework\View\Element\Template::class)
    ->setInputName('cart[' . $item->getId() . '][qty]')
    ->setInputSize(1)
    ->setInputInitialValue($block->getQty())
    ->setInputAdditionalParams('data-validate="{required:true}" id="cart-' . $block->escapeHtmlAttr($item->getId()) .'-qty" data-cart-item-id="' . $block->escapeHtmlAttr($item->getSku()) . '" data-role="cart-item-qty"')
    ->setDecrementIconUrl($block->getVar('qty_increment/icons/decrement', 'MageSuite_ThemeHelpers'))
    ->setIncrementIconUrl($block->getVar('qty_increment/icons/increment', 'MageSuite_ThemeHelpers'))
    ->setTemplate($block->getVar('qty_increment/template', 'MageSuite_ThemeHelpers'))
    ->toHtml();
?>

Styling and scripts

Styling and scripts are included by default in theme-creativeshop

Styles: theme-creativeshop/src/components/qty-increment/qty-increment.scss

Scripts: theme-creativeshop/src/components/qty-increment/qty-increment.scss

Tooltip

Magesuite introduces its own tooltip functionality with touch device support.

Component not included in any entry by default,
For all touch devices, tooltip changes into modal
Tooltip alignment can be set as setAlignment (top/bottom/left/right)

Sample block creation template usage:

 <?= $this->getLayout()
  ->createBlock('Magento\Framework\View\Element\Template')
  ->setTemplate('MageSuite_ThemeHelpers::tooltip.phtml')
  ->setAlignment('top')
  ->setTriggerText(__('Your trigger title'))
  ->setTitle(__('Your toolbar title'))
  ->setContent($yourContent)
  ->toHtml();
 ?>

Styling and scripts

Styling and scripts are not included by default in theme-creativeshop as the component is optional.

Styles: theme-creativeshop/src/components/tooltip/tooltip.scss

Scripts: theme-creativeshop/src/components/tooltip/tooltip.ts

In order to add tooltip styles and scripts in the child theme import the tooltip component in an entry file:

import 'components/tooltip';

JsMageInit

If you want to initialize some JS without creating or editing template, you can add MageSuite\ThemeHelpers\Block\JsMageInit block. It allows you to specify selector, component and js configuration (static). Example:

<block name="example_block" class="MageSuite\ThemeHelpers\Block\JsMageInit">
    <arguments>
        <argument name="selector" xsi:type="string">#component_selector</argument>
        <argument name="component" xsi:type="string">collapsible</argument>
        <argument name="js_config" xsi:type="array">
            <item name="content" xsi:type="string">ul.accordion</item>
            <item name="header" xsi:type="string">.block-title</item>
            <item name="mediaQueryScope" xsi:type="string">(max-width: 767px)</item>
        </argument>
    </arguments>
</block>

Above initialization will render standard Magento text/x-magento-init script:

<script type="text/x-magento-init">
{
    ".sidebar\u0020.block\u002Dcategories": {
        "collapsible": {
            "content": "ul.accordion",
            "header": ".block-title",
            "mediaQueryScope": "(max-width: 767px)"
        }    
    }
}
</script>

Only component property is required. If you do not specify it, nothing will be rendered.
If you do not specify any selector, "*" will be used.
If you do not specify any js_config, "{}" will be used.

mgsGetJqueryWidgetInstance

Helper function that returns jQuery widget instance.

Source: MageSuite_ThemeHelpers/js/utils/get-jquery-widget-instance.js

Requirejs alias: mgsGetJqueryWidgetInstance

Example:

define('mgsGetJqueryWidgetInstance', function (getJqueryWidgetInstance) {
  return async function () {
    const swatchesWidgetHtmlElement = document.querySelector('[data-role=swatch-options]');
    if (!swatchesWidgetHtmlElement) {
      return
    }
    const swatchesWidget = await getJqueryWidgetInstance({
        element: swatchesWidgetHtmlElement,
        widgetName: 'mage-SwatchRenderer',
        widgetCreateEventName: 'swatchrenderercreate'
    }, true);
  }
})

That block of code will bring you swatch renderer widget instance.

Params description and how to get them:

First argument: widget data (object type)
- element: html element (not jQuery object) that widget is attatched to. You can check this in two ways:
  - by widget initialization script: "[data-role=swatch-options]",
  - by console.log(this.element) in one of the widget's methods,
- widgetName: jQuery widget name. You can check it in two ways:
  - open devtools, click on element to which widget is attached and select “Properties” tab:
  - console.log(this.widgetFullName) in one of the widget's methods
- widgetCreateEventName - this parameter is required if you pass second (wait) parameter as true. It's event name that's triggered after widget initialization. In 99% of cases it's `${widget's name}create`.toLowerCase(). How to get widget name:
  - it’s word after prefix in widgets initialization: $.widget('mage.SwatchRenderer', {... <- swatchrenderer,
  - you can console.log(this.widgetName) in one of the widget's methods,
  - if above methods don’t work, you can always put console.log(event) somewhere here: lib/web/jquery/ui-modules/widget::_trigger. This will list you all widgets create events, so you can find yours.
Second argument: wait (boolean type):
- false (default) - if widget is not initialized yet, you will get null as promise resolve,
- true - function will wait until widget is initialized.

View Transition

Feature overview

This feature utilizes the Cross‑Document View Transitions API by adding CSS/Script to the page.

The feature currently allows enabling two options:

Option	Description

Option	Description
Cross‑document fade	Cross‑document fade — a smooth transition between pages.
Cross‑document product image transition	Cross‑document product image transition — an animated transition between a product tile's image on any page containing it (when clicked) and that product's image in the gallery on the PDP (combined with the smooth transition between pages).

Transitions are skipped for visitors who prefer reduced motion or whose browsers don't support the feature.

Configuration

The feature can be enabled and configured in the admin panel at:

Path

Path
Stores → Configuration → MageSuite → View Transition

General — Enabled/Disabled

Enables the cross‑document fade effect (and is the master switch — the options below require it to be enabled).

Product Image Transition

Setting	Details

Setting	Details
Enabled/Disabled	Enabled/Disabled — requires General to be enabled.
Selectors	Selectors — initially configured to work well with the product tile image ↔ fotorama main image transition. Keep in mind you need to adjust the configuration per project, depending on the product tile customization and the product gallery you use (fotorama / slide gallery / custom).
Duration	By default 250ms

Tech details

The CSS and script are injected by a block, rendered inline into the page <head>:

Aspect	Details

Aspect	Details
Block	Block: MageSuite\ThemeHelpers\Block\ViewTransition, config read via MageSuite\ThemeHelpers\Helper\Configuration\ViewTransition.
Placement	Placement: added to head.additional in view/frontend/layout/default.xml (block name magesuite.viewtransition), with ifconfig="view_transition/general/is_enabled" so it only renders when the feature is enabled.
Output	Output: an inline <style> (the @view-transition { navigation: auto; } rule, wrapped in @media (prefers-reduced-motion: no-preference) and @supports (view-transition-name: none)) plus an inline <script> (the pageswap/pagereveal handlers) - only if Product Image Transition option is enabled.

ref: https://developer.chrome.com/docs/web-platform/view-transitions