Basic concepts
This topic explains how default templates work in the 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
:
Copied to your clipboard<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:
Copied to your clipboard<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.
Copied to your clipboardprotected $_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.
Root template
<Magento_Theme_module_dir>/view/base/templates/root.phtml
is the root template for all storefront pages in the 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 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.
Templates must not instantiate new objects within their code. All objects must be passed from the Block object. This way, the template remains stateless and its sole responsibility is to display the data it receives from the Block object. This approach promotes a clear separation of concerns, improves testability, and makes the code more modular and easier to maintain. It also ensures that the template does not have unexpected side effects, as it is not responsible for creating objects or managing their lifecycle.
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 templates.
For example:
Copied to your clipboard<?= $block->getAdjustmentsHtml() ?>
is the same as writing
Copied to your clipboard<?php echo $block->getAdjustmentsHtml() ?>
Localization
In order to support the translation of content, the text must be wrapped inside __('sample text')
.
Copied to your clipboard<span><?= $escaper->escapeHtml(__('Back to Product Reviews')) ?></span>