Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 4 Current »

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:

    • 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.

  • No labels