2020-06-14 Magento2

Theming Magento 2 Layout Basics

Theming Magento 2 Layout Basics#

Layouts#

Pull together entire set of template files to be rendered by the browser

View configuration is built into a structure.

Page layouts and containers - header, left, main, right, footers
Blocks - each feature on a page
Content block templates (.phtml)
Page configuration - content blocks assigned to containers

Extend layout, containing only changes you want.

Overriding base layout file can be done by mimicking the directory but it is not recommended and should be avoided.

Overriding a base layout#

In <Vendor>/<theme>/<Namespace_Module>/layout/override/base/<layout1>.xml

Override a parent theme layout#

In <Vendor>/<theme>/<Namespace_Module>/layout/override/theme/<layout1>.xml

Where to find layout files#

Order of layout files determined by app/etc/config.php Determines the sequence of inherited themes Iterated the sequence from last ancestor to the current theme

Core Layout Files#

Module specific page layout in ./view/frontend/page_layout

Page configuration and generic layout files in ./view/frontend/layout and ./view/frontend/base

Extending Page Layouts#

<Theme_dir>/<Namespace>_<Module>/page_layout/<layout1>.xml

Override the theme file#

In <Vendor>/<theme>/<Namespace_Module>/layout/override/theme/<Parent_Vendor>/<parent_theme>/<layout1>.xml

Adding and Extending Layouts (Melding)#

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

Eg. To customise: app/code/Magento/Catalog/view/frontend/layout/catalog_product_view.xml

Add a layout file in your custom theme:

app/design/frontend/<Vendor>/<theme>/Magento_Catalog/layout/catalog_product_view.xml

Handles#

Each page in magento has a list of layout handles assigned to it:

Default: default.xml
Full action name: catalog_product_view.xml
Page specific handles: catalog_product_view_type_bundle

Check the common layout customisation tasks

For example to move compare products in default.xml:

<page ...>
  <body>
    <move element="catalog.compare.sidebar" destination="sidebar.additional" after="-" />
  </body>
</page>

Different XML File Types#

Page layout - overall structure
Page layout declaration - registers page layouts in Magento
Page configuration - overall page config and head section (meta, css, js)
Generic layout - rare, mostly used for ajax response content.

Page layouts#

Contains blocks and containers
Defined in xml files

Finding them: Grep search <layout (.*?)page_layout.xsd">

Container#

Sole purpose of assigning content structure to a page. Just included elements.

A block employs templates into a page.

base layouts are layout files provided by modules

Examples of page layouts:

2 columns left
2 columns right
3 columns
1 column
empty

Products -> Categories -> custom design to set the number of columns

Products -> Catalog -> Design

Product page layouts:

catalog_product_view_type_simple.xml
catalog_product_view_type_virtual.xml
catalog_product_view_type_grouped.xml
catalog_product_view_type_gift_card.xml
catalog_product_view_type_configurable.xml
catalog_product_view_type_bundle.xml

Class of the body tag usually points to layout handle used

Instructions to Update page layouts#

Check Layout Files Types

<container name=""> - create new container
<referenceContainer name=""> - reference existing container element
<move element="" destination=""> - move an element into a new parent container
<update handle=""> - include instructions from another handle and execute recursively

Page Layout Declararion#

To use a layout you must set it in:

modules: app/code/<Namespace>/<Module>/view/frontend/layouts.xml
themes: app/design/frontend/<Namespace>/<theme>/<Namspace_Module>/layouts.xml

Use: <layout id="layout_file_name">

Page Configuration#

If you want to render a full page you want to use <page>. Otherwise use layout.

One or more of these sections can be declared:

html
body
head
update

Customisation Tasks#

Change layout#

Copy file and add to theme in same strcuture.

Remove all other nodes except the one you want to change.

Including a static resource#

Please default_head_blocks.xml into app/design/frontend/<Vendor>/<theme>/Magneto_Theme/layout/default_head_blocks.xml
Make customisations:

Include custom js (or css)#

Place component in:

app/design/frontend/<Vendor>/<theme>/web/js
app/code/<Namespace>/<Module>/view/frontend/web/js

Create a requirejs-config.js file in:

<page ...>
  <head>
    <script src="js/sample2.js"/>
  </head>
</page>

Managing a container#

Check out layout instructions

Create a container:

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

Update a container:

<referenceContainer name="some.container">
  ...
</referenceContainer>

Remove a container:

<referenceContainer name="container.name" remove="true" />

Managing a block#

Declare a block:

<block class="Magento\Module\Block\Class" name="block.name" template="template.phtml" after="-">
  ...arguments
</block

Update a block:

<referenceBlock name="some.block">
  <arguments...>
</referenceBlock>

Remove a block:

<referenceBlock name="block.name" remove="true" />

Rearranging blocks:

<move element="block1.name" destination="container1.name" after="-" />

Blocks#

Move reusable functionality into classes for repurposing

Argument values in block can be accessed in template wit:

get{ArgumentName} or has{ArgumentName}

Eg. $this->getCssClass()

class attribute specifies class location for a block:

app/code
lib/internal
vendor/

Reusable Block Classes#

Magento\Framework\View\Element\Text: Renders simple text
Magento\Framework\View\Element\Text\ListText: Renders a list of child blocks
Magento\Framework\View\Element\Template: Renders a PHTML file
Magento\Framework\View\Element\Html\Link: Renders a link with various attributes

Templates and Customisation#

Templates are snippets of HTML code and PHP elements

Templates are located in the module: app/code/<Vendor>/<module>/view/_area_/templates

Can enable template hints

Rewrite core template#

Create your theme
Create a new template in your theme
Set your template to the block that contains the core template to rewrite

<theme_dir>/<Namespace>_<Module>/templates

Change template a block uses#

Copy app/code/Magento/Sales/view/frontend/layout/sales_guest+form.xml to app/design/frontend/<Vendor>/<theme>
Remove everything from the <body> tag
Add <ReferenceBlock name="guest.form" template="guest/alternative_form.phtml" />

Create a template block#

Create app/design/frontend/<Vendor>/<theme>/Magento_Theme/layout/default.xml

<page ...>
  <referenceContainer name="content">
    <block class="Magento\Framework\View\Element\Template" name="custom.name" template="path/to/my/template.phtml">
  </referenceBlock/>
</page>

Theming Magento 2 Layout Basics