In order to give MageSuite developers a better overview of frontend workflow, settings, and possibilities of customization examples from child themes are listed below.

Background for image teaser slide

Add the possibility to set solid, custom background instead of an image in the image-teaser based components.

Storefront

Admin panel

Add custom tab and background field to teaser admin CC configurator

<vars module="MageSuite_ContentConstructor">
    <var name="teaser">
        <var name="tabs">
            <var name="3">
                <var name="label">Custom</var>
                <var name="content">
                    <var name="fields">
                        <var name="0">
                            <var name="label">Background color</var>
                            <var name="type">color</var>
                            <var name="model">background_color</var>
                        </var>
                    </var>
                </var>
            </var>
        </var>
    </var>
</vars>

Detailed documentation of custom fields: Custom Fields

Add background template

Create MageSuite_ContentConstructorFrontend/templates/component/image_teaser/slide_elements/hotspots/before_content.phtml in a child theme.

<?php
$slide = $block->getSlide();
$backgroundColor = $slide->getBackgroundColor();
?>
<?php if (isset($backgroundColor)): ?>
    <div class="cs-image-teaser__background" style="background: <?= $backgroundColor ?>;"></div>
<?php endif; ?>

To learn about other slide hotspots check:k magesuite-content-constructor-frontend/view/frontend/templates/component/image_teaser/slide_elements/hotspotsfolder

List of hotspots:

after_content
after_slide-wrapper
after_text-content
before_content
before_slide-wrapper
before_text-content

Add styles

Add scss in a child theme components/image-teaser/image-teaser.scss

@import '~Creativeshop/components/image-teaser/image-teaser';

.#{$ns}image-teaser {
    &__background {
        position: absolute;
        top: 0;
        left: 0;
        width: 100%;
        height: 100%;
    }
}

Button new type

Add new styles for buttons.

Define a name and add styles

Define the new button type: extra-cta and add its styles.

Add components/button/hook.scss

@import 'config/variables';

@import '~Creativeshop/components/button/hook';

@mixin button-hook($type, $icon_pos) {
    @if ($type == 'extra-cta') {
        background-color: $color_background-1000;
        border: 1px solid $color_background-1000;
        color: $color_text-200;

        &:hover,
        &:focus,
        &:active {
            &:not([disabled]) {
                background-color: $color_text-200;
                border: 1px solid $color_secondary-200;
                color: $color_background-1000;

                * {
                    color: $color_secondary-200;
                    fill: $color_secondary-200;
                }
            }
        }
    }
}

Some button styles ar global and are applied to all types of button, f.e:

display: inline-block; font-size: $button_font-size; font-weight: $button_font-weight; text-align: $button_text-align; position: relative; line-height: $button_line-height; margin: 0; text-transform: $button_text-transform;

Check common variables in theme-creativeshop/src/components/button/mixin.scss

Override variables to change button type

If a button has defined button type variable override in order to apply new styles, f.e:

$checkout_next-button-type: 'extra-cta';
$checkout_place-order-button-type: 'extra-cta';

Style new button

@import 'components/button/mixin';

.actions-toolbar {
    .primary {
        button {
            @include button(
                $type: 'extra-cta',
                $icon_pos: $button_default-icon-pos
            );
        }
    }
}

Filters - make filters horizontal

The optional scenario for magesuite filters is to set them horizontally, above the toolbar and products.

Storefront

In order to introduce horizontal filters the layout must be changed to 1column and left column must be placed below or under the main column. Add the following changes in XML files:

src/Smile_ElasticsuiteCatalog/layout/catalog_category_view_type_layered.xml

<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd" layout="1column">
    <body>
        <move element="catalog.leftnav" destination="main" before="-" />
    </body>
</page>

src/Smile_ElasticsuiteCatalog/layout/catalogsearch_result_index.xml

<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd" layout="1column">
    <body>
        <move element="catalog.leftnav" destination="main" before="-" />
    </body>
</page>

Although the behavior (vertical/horizontal position) of filters basically is set by page layout, it is also possible to force horizontal or vertical styling for any page layout. Check force_sidebar_filters_style and force_horizontal_filters_style variables in etc/view/xml file in order to learn more.

  <!-- If you want to have 1column-layout but still keep default filters styling (the one from sidebar) you can set this argument's value to 'true' -->
  <argument name="force_sidebar_filters_style" xsi:type="boolean">false</argument>
  
  <!-- If you want to have any other layout than '1column-layout' but still keep horizontal filters styling you can set this argument's value to 'true' -->
  <argument name="force_horizontal_filters_style" xsi:type="boolean">false</argument>

Styling

In theme-creativeshop/src/components/aftersearch-nav/aftersearch-nav.scss there are plenty of variables that can help with styling of horizontal filters.

Pay attention to the below variables, that help to set the desired number of rows and columns on tablet, laptop, and desktop breakpoint

$aftersearch-nav--horizontal_cols: (
    tablet: 4,
    laptop: 5,
    desktop: 6,
) !default;
$aftersearch-nav--horizontal_rows: (
    tablet: 1,
    laptop: 1,
    desktop: 1,
) !default;

Filters - move filters into offcanvas

The common design pattern is to move the filter into offcanvas on mobile. theme-creativeshop offers a built-in possibility to move filters into offcanvas on mobile and/or desktop. (However, desktop offcanvas filters are very rarely used)

Storefront

Display offcanvas toggle button and enable offcanvas filters:

etc/view.xml

<vars module="Magento_Catalog">
    <var name="toolbar">
        <var name="filters_offcanvas_button">
            <var name="display">false</var>
            <var name="label">Filters</var>
            <var name="icon">images/icons/toolbar/filters.svg</var>
        </var>
    </var>
    <var name="offcanvas_filters_enabled">
        <var name="mobile">true</var>
        <var name="desktop">false</var>
    </var>
</vars>

Do not collapse filters

the standard behavior of magesuite filters on mobile is to collapse the whole filters section:

In order to show filters in offcanvas set is_collapsible_mobile variable in:

Smile_ElasticsuiteCatalog/layout/catalog_category_view_type_layered.xml

<referenceBlock name="catalog.leftnav">
    <arguments>
        <argument name="is_collapsible_mobile" xsi:type="boolean">false</argument>
    </arguments>
</referenceBlock>

Smile_ElasticsuiteCatalog/layout/catalogsearch_result_index.xml

<referenceBlock name="catalogsearch.leftnav">
    <arguments>
        <argument name="is_collapsible_mobile" xsi:type="boolean">false</argument>
    </arguments>
</referenceBlock>

Styling

There are a couple of variables for the toggle button that can be adjusted. components/toolbar/toolbar.scss

$toolbar_filters-button-type: 'secondary' !default;
$toolbar_filters-button-icon-pos: 'left' !default;

Offcanvas filters styles are placed in components/offcanvas-filters There are some variables that can be adjusted in order to achieve the desired look&feel of the child project:

$offcanvas-filters_transition-time: $transition-default-time !default;
$offcanvas-filters_overlay-background: $modals_overlay-background !default;
$offcanvas-filters_drawer-background: $color_background-200 !default;
$offcanvas-filters_spinner-color: $color_primary-500 !default;
$offcanvas-filters__close-include-pseudoicon: true !default;
$offcanvas-filters__close-pseudoicon-type: 'plus' !default;
$offcanvas-filters__close-width: 2rem !default;
$offcanvas-filters__close-line-width: 0.2rem !default;
$offcanvas-filters__close-color: $color_text-600 !default;
$offcanvas-filters__close-color-hover: $color_text-500 !default;

Hover effect on tile - add the second image on hover

Many projects request to add a hover effect on tile that shows another product image (f.e. the back of the product).

Nagranie z ekranu 2023-01-9 o 11.01.33.mov

Add a template for the second image on the tile

In MageSuite_ProductTile/layout/product_tile.xml add a template with the second image:

<referenceBlock name="product.tile.container.figure">
    <block class="MageSuite\ProductTile\Block\Tile\Fragment" name="product.tile.figure.hover.image" template="MageSuite_ProductTile::fragments/hover-image.phtml" after="-">
        <arguments>
            <argument xsi:type="object" name="cache_key_model">MageSuite\ProductTile\Cache\Image</argument>
            <argument xsi:type="string" name="css_class">cs-product-tile__image cs-product-tile__image--hover</argument>
        </arguments>
    </block>
</referenceBlock>

<?php
    $product = $block->getProduct();
    $imageHelper = $this->helper('Magento\Catalog\Helper\Image');
    $productImageOnHover = $block->getImage($product, 'category_on_hover_page_grid');
    $productImageOnHoverUrl = $block->escapeUrl($productImageOnHover->getImageUrl());
    $productImageOnHover2x = $block->getImage($product, $block->getImage2xId() ?? 'category_on_hover_page_grid_x2');
    $productImageOnHover2xUrl = $block->escapeUrl($productImageOnHover2x->getImageUrl());
    $productImageOnHoverWidth = $productImageOnHover->getWidth();
    $productImageOnHoverHeight = $productImageOnHover->getHeight();
    $productImageOnHoverAlt = $block->escapeHtmlAttr($product->getName());
    $imageTypeHelper = $this->helper(\MageSuite\ThemeHelpers\Helper\ImageType::class);

    $loaderImage = 'data:image/gif;base64,R0lGODlhAQABAAD/ACwAAAAAAQABAAACADs=';

    /* XML config */
    $cssClass = $block->getCssClass();
    $imgClass = $block->getImgClass();
    $applyWidthHeightAttr = $block->getApplyWidthHeightAttr();
?>
<?php if ($productImageOnHover && strpos($productImageOnHoverUrl, 'placeholder') === false): ?>
    <picture class="<?= $cssClass ?>">
        <source
            srcset="<?= $productImageOnHoverUrl . ' 1x, ' . $productImageOnHover2xUrl . ' 2x' ?>"
        >
        <img
            src="<?= $productImageOnHoverUrl ?>"
            class="<?= $imgClass ?>"
            srcset="<?= $productImageOnHoverUrl . ' 1x, ' . $productImageOnHover2xUrl . ' 2x' ?>"
            <?php if ($applyWidthHeightAttr): ?>
                width="<?= $productImageOnHoverWidth ?>"
                height="<?= $productImageOnHoverHeight ?>"
            <?php endif; ?>
            alt="<?= $productImageOnHoverAlt ?>"
            loading="lazy"
        >
    </picture>
<?php endif; ?>

Add styling

.#{$ns}product-tile {
    $root: &;
    
    @media (hover: hover) {
        &:hover {
            #{$root}__image--hover {
                opacity: 1;
            }
        }
    }

    &__image {
        display: block;

        &--hover {
            display: none;

            @media (hover: hover) {
                display: block;
                position: absolute;
                top: 0;
                left: 0;
                width: 100%;
                height: 100%;
                z-index: 2;
                opacity: 0;
            }
        }
    }
}

Change scenario for navigation flyout teaser

The navigation teaser scenario can be changed to any available image teaser scenario.

In order to learn about configuration options check theme-creativeshop/src/MageSuite_Navigation/layout/default.xml

<block class="MageSuite\Navigation\Block\Navigation" name="navigation.main" template="MageSuite_Navigation::main/bar.phtml">
    <arguments>
        <argument xsi:type="array" name="imageTeaserConfig">
            <item name="items" xsi:type="array">
                <item name="0" xsi:type="array">
                    <item name="image" xsi:type="array">
                        <item name="aspect_ratio" xsi:type="string">3:5</item>
                    </item>
                    <item name="content_align" xsi:type="array">
                        <item name="x" xsi:type="string">2</item>
                        <item name="y" xsi:type="string">1</item>
                    </item>
                    <item name="optimizers" xsi:type="array">
                        <item name="color_scheme" xsi:type="string">dark</item>
                    </item>
                    <item name="teaserType" xsi:type="string">full</item>
                </item>
            </item>
            <item name="scenario" xsi:type="array">
 ....
        </argument>
    </arguments>
</block>

Add SKU (or other custom elements) on a product tile

In order to add an extra element to the product tile create a template and add it to the product tile XML:

src/MageSuite_ProductTile/layout/product_tile.xml

<referenceBlock name="product.tile.container.main.details">
    <block class="MageSuite\ProductTile\Block\Tile\Container" name="product.tile.sku.container" before="-">
        <arguments>
            <argument xsi:type="string" name="html_tag">div</argument>
            <argument xsi:type="string" name="css_class">cs-product-tile__sku</argument>
        </arguments>
        <block class="MageSuite\ProductTile\Block\Tile\Fragment" name="product.tile.sku" template="MageSuite_ProductTile::fragments/sku.phtml" />
    </block>
</referenceBlock>

<?= $block->escapeHtml($block->getProduct()->getSku()) ?>

Read more in MageSuite_productTile module documentation: ProductTile

Add a special variant for image teaser

Sometimes there is a need to style some image teasers in a special way. Thanks to the custom fields an admin editor can mark some teasers as special variants (see Custom Fields ) and a frontend developer can style them based on a custom class.

Storefront

Admin panel:

Add special variant custom fields

<vars module="MageSuite_ContentConstructor">
    <var name="image_teaser">
        <var name="custom_sections">
            <var name="0">
                <var name="label">Custom settings</var>
                <var name="content">
                    <var name="fields">
                        <var name="0">
                            <var name="label">Special variant (use only with image-teaser component)</var>
                            <var name="type">select</var>
                            <var name="options">
                                <var name=" ">Standard</var>
                                <var name="cs-container--mood-component">Mood component</var>
                            </var>
                            <var name="model">special-variant</var>
                            <var name="default"> </var>
                            <var name="frontend_type">css_class</var>
                        </var>
                    </var>
                </var>
            </var>
        </var>
    </var>
</vars>

Style component that is wrapped in a container with and extra modifier

components/image-teaser/image-teaser.scss

Styles example:

.#{$ns}container--mood-component {
    .#{$ns}image-teaser {
        --base-size: 100%;
        --gap: 0;

        --slogan-font-size: 2rem;
        --description-font-size: 1.4rem;

        @include media('>=laptop') {
            --slogan-font-size: 2.4rem;
            --description-font-size: 1.6rem;
        }

        .#{$ns}image-teaser__background {
            height: 73%;

            @include media('>=tablet') {
                height: 54%;
            }
        }

        .#{$ns}image-teaser__figure {
            display: flex;
            flex-direction: column;
            justify-content: space-between;
        }
    }
}

Custom will will be applied to all image-teaser based component (f.e. hero, icon component)

In order to hide a custom field in a specific component configuration hide them with styles, f.e.

.cc-image-teaser-configurator--teaser-and-text, 
.cc-image-teaser-configurator--icon {

   .cc-custom-fields__form-group:has(.cc-input--special-variant) {
        display: none;
    }
}

The CSS class of a custom field follows the pattern: .cc-input--[name]

Styles for CC configurator must be placed in a module, not in the child theme, f.e. under the following path:

customization-[project]/magesuite-custom-content-constructor-components/custom-components-configurator.scss

Place an additional element below mobile navigation in offcanvas

The common design pattern is to place some elements like my account icon or language switcher below mobile navigation. In the theme-creativeshop icons are placed in the header or mobile, but there is an easy way to move them into offcanvas if there is a such design requirement. It is also possible to place other, custom elements in mobile offcanvas navigation.

Storefront

Offcanvas drawer template hotspots

In the MageSuite_Navigation/templates/offcanvas/drawer.phtml template serevral hotspots are prepared:

  <?= $block->getChildHtml('navigation.offcanvas.after.list'); ?>
  <?= $block->getChildHtml('navigation.offcanvas.after.authorization'); ?>
  <?= $block->getChildHtml('navigation.offcanvas.after.language'); ?>
  <?= $block->getChildHtml('navigation.offcanvas.after'); ?>

They can be used in order to place inside them some new elements f.e. static block:

<referenceBlock name="navigation.offcanvas">
    <block class="MageSuite\ThemeHelpers\Block\Cms\CacheableBlock" name="navigation.offcanvas.after.list">
        <arguments>
            <argument name="block_id" xsi:type="string">company-menu</argument>
        </arguments>
    </block>
</referenceBlock>

Show search input on the desktop as a dropdown

By default in MageSuite above defined breakpoint search input is visible as a normal header element (layer), by default between the logo & user nav.

$global_header-mobile-search-in-offcanvas-breakpoint: 'tablet' !default

The other possible option is to place search input below header - in the same way as on mobile.

In order to change this behavior in src/config/variables.scss file of your there set the following variable:

$global_header-hide-search-item-trigger-breakpoint: false;
$global_header-searchbox-as-layer-breakpoint: false;

Integrate self-hosted fonts

To provide self-hosted, preloaded fonts, define specific arguments in fonts XML block.

Step 1: provide (in local_fonts) CSS file in which custom @font-face rules are defined. Example:

<argument name="local_fonts" xsi:type="array">
    <item name="local.fonts.css" xsi:type="string">css/font.css</item>
</argument>

Step 2: provide (in local_fonts_file) paths to fonts.Example:

<argument name="local_fonts_file" xsi:type="array">
    <item name="local.fonts.path_1" xsi:type="string">fonts/PT-Sans_Regular.woff2</item>
    <item name="local.fonts.path_2" xsi:type="string">fonts/PT-Sans_Bold.woff2</item>
</argument>

Step 3: Define custom fonts rules in CSS file defined in first step. Example:

@font-face {
    font-family: 'PT Sans';
    src: url('../fonts/PT-Sans_Regular.woff2') format('woff2'),
        url('../fonts/PT-Sans_Regular.woff') format('woff');
    font-weight: 400;
    font-style: normal;
    font-display: optional;
}

@font-face {
    font-family: 'PT Sans';
    src: url('../fonts/PT-Sans_Bold.woff2') format('woff2'),
        url('../fonts/PT-Sans_Bold.woff') format('woff');
    font-weight: 700;
    font-style: normal;
    font-display: optional;
}

Change category links component mobile layout from dropdown to scrollable list

In order to introduce a scrollable list for the category links component override the following files in your theme:

src/MageSuite_ContentConstructorFrontend/templates/component/category_links.phtml
1. remove initialisation of collapsible widget: data-mage-init='{"collapsible":{"mediaQueryScope":"(max-width: 767px)"},"ccCategoryLinks":{}}'
2. remove dropdown trigger: cs-category-links__subtitle | cs-category-links-dropdown__trigger
src/components/category-links/index.ts
1. In order to avoid including not used styles remove import 'components/category-links/category-links-dropdown.scss'; import. Leave only import components/category-links/category-links.scss'; import

In etc/view.xml file decide how many items should be shown in the component. To always show every subcategory, which was selected in the admin panel, use a high number, f.e.

<var name="category_links">
    <var name="hide_links_breakpoints">
        <var name="tablet">
            <var name="hide_from">99</var>
        </var>
        <var name="laptop">
            <var name="hide_from">99</var>
        </var>
        <var name="laptopLg">
            <var name="hide_from">99</var>
        </var>
        <var name="desktop">
            <var name="hide_from">99</var>
        </var>
    </var>
</var>

The following CSS can be helpful in order to make a native scroll on a list with subcategory items. use it in src/components/category-links/category-links.scss file.

&__list-wrapper {
    display: flex;
    padding-left: $page_edge-gutter;
    padding-right: $page_edge-gutter;
    scroll-padding-left: $page_edge-gutter;
    scroll-padding-right: $page_edge-gutter;
    scroll-snap-type: x mandatory;
    overflow-x: auto;
    overscroll-behavior-inline: contain;
    scroll-behavior: smooth;
}

Frontend Customizations - examples

Background for image teaser slide

Button new type

Filters - make filters horizontal

Filters - move filters into offcanvas

Hover effect on tile - add the second image on hover

Change scenario for navigation flyout teaser

Add SKU (or other custom elements) on a product tile

Add a special variant for image teaser

Place an additional element below mobile navigation in offcanvas

Show search input on the desktop as a dropdown

Integrate self-hosted fonts

Change category links component mobile layout from dropdown to scrollable list