ThemeHelpers

Owned by Marta Siewierska-Stańczak
Last updated: Jan 23, 2024 by Krzysztof Kula
6 min read

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:

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:

 

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

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

 

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:

 

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

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:

 

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:

 

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:

Above initialization will render standard Magento text/x-magento-init 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:

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.