PART 1.2.8 – Theme images, view.xml

Useful documentation:

How to work with image gallery on product page

General about view.xml in theme

Gallery widget (js widget)



view.xml what is it used for?

The properties of product images used on the storefront are stored in the view.xml configuration file. The properties for the images displayed on the product pages are defined by the gallery widget options. The options of the widget can be configured in the theme view.xml as well.


<images module=“Magento_Catalog”>

    <image id=“unique_image_id” type=“image”>

        <width>100</width> <!– Image width in px –>

        <height>100</height> <!– Image height in px –>




Properties that can be modified from the view.xml are:

  • width
  • height
  • constrain
  • aspect_ratio
  • frame
  • transparency
  • background

Basically the same things that could be configured from the template in Magento 1. For more examples on how to use the specific properties:

Images in templates

Example from Magento_Catalog/view/template/product/list.phtml

Product image


$image = ‘category_page_grid’;

echo $block->getImage($product, $image)->toHtml(); ?>

Connection to gallery widget

Inside the view.xml you’ll find a lot of useful settings you can change to have different functionality for the image gallery on the product pages, for example you can change transition effect, zoom levels, thumbnail sizes. 

Nav direction

<var name=“gallery”>

    <var name=“navdir”>vertical</var> <!– Sliding direction of thumbnails (horizontal/vertical) –>


Behaviour of swatch images.

Swatch image

<vars module=“Magento_ConfigurableProduct”>

    <var name=“change_only_base_image”>true</var>



<vars module=“Magento_Swatches”>

    <var name=“change_only_base_image”>true</var>


PART 1.2.7 – Translations

Theme translations

A theme dictionary can be added inside the i18n folder of your theme:




<h3><?php echo __(‘Create Backup’) ?></h3>

String containing variable: <h3><?php echo sprintf(__(‘Hello %s’), $yourVariable) ?></h3>

Knockout templates

When a string is added in the scope of an HTML element:

<span data-bind=“i18n: ‘Sign In'”></span>


When a string is added with no binding to an HTML element:

<!– ko i18n: ‘You have no items in your shopping cart.’ –><!– /ko –>

Strings in js

Define mage translate to be able to use it:

define ([‘jquery’, ‘mage/translate’], function ($) {…});


 Then use “$.mage.__” before the string to be translated:



If a variable is included:

$.mage.__(‘Hello %1’).replace(‘%1’, yourVariable);

PART 1.2.6 – Knockout basics


Knockout in Magento 2, Fundamentals Part 1 (by Stefan Ström) 

Chrome plugin Knockout context debugger

How to modify the checkout in M2

Post by Inchoo

Where are knockout used in M2?

Mostly for checkout related functionality:

  • Header cart (minicart)
  • Checkout

Knockout templates

The knockout templates are located in web/template

An example:

module-checkout/view/frontend/web/template/form/element/email.html (e-mail input field in the checkout)


Example on how to disable a component. 


Disable component

<referenceBlock name=“checkout.root”>


        <argument name=“jsLayout” xsi:type=“array”>

            <item name=“components” xsi:type=“array”>

                <item name=“checkout” xsi:type=“array”>

                    <item name=“children” xsi:type=“array”>

                        <item name=“authentication” xsi:type=“array”>

                            <item name=“config” xsi:type=“array”>

                                <item name=“componentDisabled” xsi:type=“boolean”>true</item>









Customizing knockout template inside theme

Overriding a knockout template is not that different from overriding a template file. 

Example of overriding the shipping template in the checkout:

Original file: module-checkout/view/frontend/web/template/shipping.html

Theme version: <theme_location>/Magento_Checkout/web/template/shipping.html 


Exercise 9.0

Move the ‘Go to checkout’ button to the bottom of the mini cart (below view and edit cart).

PART 1.2.5 – jQuery widgets and require.js

Useful resources:

Initializing js


Example from layered navigation in Luma (theme-frontend-luma/Magento_LayeredNavigation/templates/layer/state.phtml)

When inserted in a certain element, the script is called only for this particular element. It is not automatically called for other elements of this type on the page.

<script type=”text/x-magento-init”>

Example from add to cart module-catalog/view/frontend/templates/product/view/addtocart.phtml  

To call a JS component on a HTML element without direct access to the element or with no relation to a certain element, use the <script type=”text/x-magento-init”> tag and attribute.


Some of the common ones include:

  • Accordion
  • Collapsible
  • Dropdown
  • Modal

Gallery widget


Example of how to add a new javascript

In the root of your theme add: a file named requirejs-config.js 





 * Copyright © 2009-2017 Vaimo Group. All rights reserved.

 * See LICENSE.txt for license details.



var config = {

    “map”: {

        “*”: {

            example: “js/example”




Create the js file




 * Copyright © 2009-2017 Vaimo Group. All rights reserved.

 * See LICENSE.txt for license details.




], function($) {

    $.widget(“vaimo.example”, {

        options: {

            color: ‘#fafafa’



        _create: function () {

            console.log(‘This is the background color: ‘ + this.options.color);




Initialization using data-mage-init


<footer data-mage-init=‘{“example”:{“color”: “#fab”}}’ class=“footer content”>


class=“footer__cms accordion accordion-container”>


class=“accordion-title footer__title”>



                echo __(‘Customer service’) ?>




class=“accordion-content footer__cms-links”>

            echo $block->getChildHtml(‘footer.links’) ?>






Exercise 8.0

  1. Create a js file in your theme.
  2. Include the js file using require-js.
  3. Intiate the js using data-mage-init on the div with the class products inside list.phtml (the template used in exercise 6)
  4. The script should add a class, color or console log a string when the product list is rendered.

PART 1.2.4 – Layout

  • Extending Layouts vs. Overriding Layouts
    • Extending layouts
    • Overriding layouts
  • Layout file processing
  • Page Layouts Declaration
  • Customisation
    • Managing Containers
    • Managing Blocks

Extending Layouts vs. Overriding Layouts

Extending layouts

Rather than copy extensive page layout or page configuration code and then modify what you want to change, in the Magento system, you only need to create an extending layout file that contains the changes you want.

To add an extending page configuration or generic layout file, put the layout file in the following location:

To add an extending page layout file, put the file in the following location:

Create an extending layout file that contains the changes you want, instead of creating and modifying many files.

For example, to customize the layout defined in /app/code/Magento/Catalog/view/frontend/layout/catalog_product_view.xml, add a layout file with the same name in your custom theme, such as: app/design/frontend/<Vendor>/<theme>/Magento_Catalog/layout/catalog_product_view.xml

Overriding layouts

If the amount of customization is large, you can use the overriding function for the needed layout file. This means that the new file that you place in the theme will be used instead of the parent theme layout file of the base layout file.

To add an overriding base layout file (to override a base layout provided by the module), put the layout file in the following location:

To add an overriding theme file (to override a parent theme layout), put the layout file in the following location:


Examples of customizations that involve overriding layouts:

  • Suppressing method invocation. Overriding is not necessary if a block has a method that cancels the effect of the originally invoked method. In this case, you can customize the layout by adding a layout file where the canceling method is invoked.
  • Modifying method arguments.
  • Canceling block/container removal using the remove directive.
  • Setting XML attributes of blocks and containers. Certain attributes, such as htmlClass and htmlId label attributes, can be changed in extending layouts.
  • Removing block arguments.
  • Modifying and suppressing handles inclusion.
  • Removing all handle instructions by declaring an overriding layout file with an empty handle.

Layout file processing

The Magento application processes layout files in the following order:

  1. Collects all layout files from modules. The order is determined by the modules order in the module list from app/etc/config.php.
  2. Determines the sequence of inherited themes [<parent_theme>, …, <parent1_theme>] <current_theme>
  3. Iterates the sequence of themes from the last ancestor to the current theme:
    1. Adds all extending theme layout files to the list.
    2. Replaces overridden layout files in the list.
    3. Merges all layout files from the list.



Parent Theme















Page Layouts Declaration

Module layout declarations: app/code/<Vendor>/<Module>/view/frontend/layouts.xml

Theme layout declaration: app/design/frontend/<Vendor>/<theme>/<Vendor_Module>/layouts.xml


<page_layouts xmlns:xsi=”” xsi:noNamespaceSchemaLocation=”urn:magento:framework:View/PageLayout/etc/layouts.xsd”>

    <layout id=”1column”>

        <label translate=”true”>1 column</label>


    <layout id=”2columns-left”>

        <label translate=”true”>2 columns with left bar</label>


    <layout id=”2columns-right”>

        <label translate=”true”>2 columns with right bar</label>


    <layout id=”3columns”>

        <label translate=”true”>3 columns</label>




<layout xmlns:xsi=”” xsi:noNamespaceSchemaLocation=”urn:magento:framework:View/Layout/etc/page_layout.xsd”>

    <update handle=”empty”/>

    <referenceContainer name=”page.wrapper”>

        <container name=”header.container” as=”header_container” label=”Page Header Container” htmlTag=”header” htmlClass=”page-header” before=”main.content”/>

        <container name=”” as=”page_top” label=”After Page Header” after=”header.container”/>

        <container name=”footer-container” as=”footer” before=”before.body.end” label=”Page Footer Container” htmlTag=”footer” htmlClass=”page-footer”/>





Managing Containers

To create a container, use the <container> instruction:


<container name=”some.container” as=”someContainer” label=”Some Container” htmlTag=”div” htmlClass=”some-container” />

To update a container, use the <referenceContainer> instruction:


<referenceContainer name=”some.container”>



To remove a container, use the remove=“true|false” attribute


<referenceContainer name=“” remove=“true” />


 In the current mainline the <remove> instruction is replaced by the “ remove”  attribute.

Managing Blocks

To create (declare) a block, use the <block> instruction:


<block class=“Magento\Module\Block\Class” name=“” template=“template.phtml” after=“-”>





To update a block, use the <referenceBlock> instruction:


<referenceBlock name=“some.block”>





To remove a block, use the remove=“true|false” attribute:


<referenceBlock name=“” remove=”true” />


 In the current mainline the <remove> instruction is replaced by the “ remove”  attribute.

To set up a template used by a block:


<referenceBlock name=“” template=“template.phtml”/>

To modify block arguments:


<referenceBlock name=”block.example”>


        <!– Modified block argument ->

        <argument name=”label” xsi:type=”string”>New Block Label</argument>

        <!- Newly added block argument ->

        <argument name=”custom_label” xsi:type=”string”>Custom Block Label</argument>



In layout files you can change the order of elements on a page:

• <move> instruction: Allows changing the order and parent for page elements.

• before and after attributes of <block>: Allows changing elements’ order within one parent.


<move element=“” destination=“” after=“-”/>

<move element=“” destination=“” before=“”/>

action method

Action methods are not used anymore (sometimes they work, but support may be dropped so be careful).

Exercise 7.0

7.1. Choose any element and move it to different place.

7.2. Choose another element and remove it from the site.

7.3. Change title of one of the tabs on product page.


Be the first to like this

  • No labels
  • Edit Labels


    • Mark Simonovskiy

      Some addition from my side. That’s was useful for me
      There is a way to find which layout file u suppose to override.
      First you have to find a needed block which you want to modify, in example i want to play change 

  • just search whole project for that name, and find xml which defines this  as a .phtml like so

  • <block class=“Magento\Catalog\Block\Product\View” name=“” template=“product/view/review.phtml” after=“” />

    • in my case that the file 
  • vendor/magento/module-catalog/view/frontend/layout/catalog_product_view.xml

  • this is a .xml fine that you have override in your theme

PART 1.2.3 – Templates

Overriding and customisations

There is two places where you can find templates. Some of template use phtml files, some of them use knockout.js.


To prevent XSS issues, Magento recommends the following rules of escapingHTML content in templates:

Escape data using the following methods:

  • $block->escapeHtml()
  • $block->escapeQuote()
  • $block->escapeUrl()
  • $block->escapeXssInUrl()

If a method indicates that the contents are escaped, do not escape: getTitleHtml(), getHtmlTitle() (the title is ready for the HTML output)



<?php echo $block->getTitleHtml() ?>


<?php echo $block->getHtmlTitle() ?>


<?php echo $block->escapeHtml($block->getTitle()) ?>


<h1><?php echo (int)$block->getId() ?></h1>


<?php echo count($var); ?>


<?php echo ‘some text’ ?>


<?php echo “some text” ?>


<a href=”<?php echo $block->escapeXssInUrl($block->getUrl()) ?>”>


<?php echo $block->getAnchorTextHtml() ?>



Magento 2.2

The upcoming release of Magento 2.2 will deprecate these functions.Please check back on this page ( after the 2.2 release for updated documentation on new escape functions.


Magento 2’s variables used in template shouldn’t have underscore “_” in the name what is a different comparing to Magento 1.

Magento 1

Magento 2



Exercise 6.0

Remove product name from items on category page.

PART – Icons

In order to add icons I would recommend to use IcoMoon. Add icons as font rather than images. In order to generate font, you will need to have icons in svg fill format, please, see the documentation how to convert strokes to fill. The next step is to upload and select icons, generate font and add to the project app/design/frontend/<Vendor>/<theme>/web/fonts/

Notice, that you will need to generate woff2 version as it is not included in IcoMoon zip, use some online convertors.

The next step is to create _typography_extend.less file with following content:




// Copyright © 2009-2017 Vaimo Group. All rights reserved.

// See LICENSE.txt for license details.



body {



    @font-path: ‘@{baseDir}fonts/icomoon/icomoon’,

    @font-weight: @font-weight__light,

    @font-style: normal




Notice that @font-weight__light is already defined. fonts/icomoon is directory where you can find font files named in different formats. All font files should have the same name. 

Remember to add_typography_extend.less  to _extend.less file.

As Magento2 has already icons as font, you will need to overwrite current icon font in _theme.less by adding following lines:



//  Icons

//  ———————————————

@icons__font-path: “@{baseDir}fonts/icomoon/icomoon”;

@icons__font-name: ‘icomoon’;

@icon-font__size: 2.2rem;



Notice that all new icons variables should be defined in _variables.less file. 




//  Icons

//  ———————————————

@icon-fb: ‘\e900’;

@icon-twitter: ‘\e904’;

@icon-yt: ‘\e905’;

<rdf:RDF xmlns:rdf=”; xmlns:dc=”; xmlns:trackback=””&gt; <rdf:Description rdf:about=”; dc:identifier=”; dc:title=”PART – Icons” trackback:ping=”″/&gt; </rdf:RDF>