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

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.

MageSuite Developer Documentation

ThemeHelpers

Installation

Functionalities

Icon

Image View Model

Category page headline

Page scroll

Qty Increment

Tooltip

JsMageInit

mgsGetJqueryWidgetInstance

Related content