Adobe Commerce 2.3 reached end of support in September 2022.

Templates basic concepts

What’s in this topic

This topic explains how default templates work in the Magento application.

How templates are initiated

Templates are initiated in layout files, and each layout block has an associated template.

The template is specified in the template attribute of the <block> layout instruction.

Take this example from app/code/Magento/Catalog/view/frontend/layout/catalog_category_view.xml:

1
<block class="Magento\Catalog\Block\Category\View" name="category.image" template="Magento_Catalog::category/image.phtml">

The category.image block is rendered by the image.phtml template in the category subdirectory of the Magento_Catalog module templates directory.

The templates directory of Magento_Catalog is app/code/Magento/Catalog/view/frontend/templates.

Templates may also be specified in the PHP Block class using the $_template protected variable.

Here is an example from the app/code/Magento/Review/view/frontend/layout/review_product_view.xml layout:

1
<block class="Magento\Review\Block\View" name="review_view" ifconfig="catalog/review/active"/>

The template for the review_view block is not specified using the template attribute of the <block> layout instruction. Instead, it is specified in the app/code/Magento/Review/Block/View.php block class.

1
protected $_template = 'Magento_Review::view.phtml';

Template location

Templates are stored in the following locations:

  • Module templates: <module_dir>/view/frontend/templates/<path_to_templates>
  • Theme templates: <theme_dir>/<Namespace>_<Module>/templates/<path_to_templates>

<path_to_templates> indicates zero or more directory levels.

Examples:

  • app/code/Magento/Catalog/view/frontend/templates/product/widget/new/content/new_grid.phtml
  • app/code/Magento/Checkout/view/frontend/templates/cart.phtml

Template overrides

For template files with the same name, the following override rules apply:

  • Theme templates override module templates
  • Child theme templates override parent theme templates

To change the output defined by an existing template, override the template in your custom theme. This concept is the basis of template customization in Magento.

See Theme inheritance

Root template

<Magento_Theme_module_dir>/view/base/templates/root.phtml is the root template for all storefront pages in the Magento application. This file can be overridden in a theme just like any other template file.

Unlike other templates, root.phtml contains the doctype specification and contributes to <head> and <body> sections of all pages rendered by Magento application.

Getting argument values from layout

Arguments values set in a layout file are accessed in templates using the block’s get{ArgumentName}() and has{ArgumentName}() methods.

For example, set an argument in the block: <argument name="store_name" xsi:type="string">ExampleCorp</argument>.

  • Get the argument value, in the template:

    • $block->getData('store_name')
    • $block->getStoreName()
  • Check if the argument exists:

    • $block->hasData('store_name')
    • $block->hasStoreName()

See Block arguments for more information.

Using PHP short tags in template PHTML files

The echo command in PHP can be written using the short tag in Magento templates.

For example:

<?= $block->getAdjustmentsHtml() ?>

is the same as writing

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

Localization

In order to support the translation of content, the text must be wrapped inside __('sample text').

<span><?= $escaper->escapeHtml(__('Back to Product Reviews')) ?></span>

Set a block’s template