Layout

The layout defines the structure of pages and provides ways to extend and modify them across modules. The layout file name is determined in the configuration per entity using entity.my_entity.layout or through custom logic.

A typical structure in the module/layout directory may look like this:

module/layout
├── component
│   └── my_component.yaml
├── my_base_layout.yaml
├── my_entity1.yaml
├── my_entity2.yaml
├── existing_entity.yaml
└── page.yaml

component/my_component.yaml	Reusable component that can be included in multiple pages
my_base_layout.yaml	Custom base layout within the module
my_entity1.yaml, my_entity2.yaml	New pages introduced by the module
existing_entity.yaml	Customizations for an existing page from a base module
page.yaml	Customizations for the base layout that all pages extend

Regular Block

A regular block is a block that uses a .phtml template.

.my-block:
  private: false
  type: null
  id: identifier
  attributes:
    class: [ my-class1, my-class2, ... ]
    any-attribute: value
  template: my-project/my-module/template/name.phtml
  my-property1: value
  my-property2:
    - value 1
    - value 2
  .child-block1: [ ... ]
  .child-block2: [ ... ]

private	Optional, indicates that the block renders private content, false by default. If the page is cached, private: true instructs Lightna to render this block via JavaScript instead of server-side to prevent caching personal information. See the configuration page for page cache settings.
type	Defines how the block behaves. Possible values: dynamic – Updates dynamically on user actions. Enables Blocks.updateHtml on the client side. lazy – Same as dynamic, but the block is not initially rendered on the server and requires Blocks.updateHtml to load content. null – Default block type.
id	Required for private, dynamic, and lazy blocks. Can also be used for easier block access in the layout.
attributes	Array of HTML attributes rendered inside the block as <div <?= $block->attributes() ?>>. If an attribute value is an array, it will be joined with spaces as a separator.
template	Required, specifies the block's template with a full path starting from the module name.
my-property1, my-property2	Custom properties defined within the block.
.child-block1, .child-block2	Defines child blocks. A dot before the name marks it as a block instead of a property.

Container Block

A container block has no template of its own and renders a configured wrapper around all its child blocks.

.my-wrapper:
  private: false
  type: null
  id: identifier
  container: div 
  attributes: 
    class: [ my-class1, my-class2, ... ] 
    any-attribute: value 
  .child-block1: [ ... ]
  .child-block2: [ ... ]

container	Defines the HTML tag used as a wrapper.
attributes	Defines HTML attributes for the wrapper element.

Reusable Component

When the same complex block is needed in multiple places or pages, move it to a separate component and include it as follows:

.product-list:
  template: my-project/my-module/product/list.phtml
  .item: component/product/tile.yaml

Reuse Base Layout

A page can extend multiple base layouts or apply updates using the extends root property.

extends:
  - page
  - my-custom-layout
.head: ...
.body: ...

Extending Layout

All layout files with the same name are merged across modules. Creating a file with an existing layout name will automatically extend it. Additional layout modifications can be made using directives. See YAML Directives for more details.

Inserting Blocks Before and After

It's simple to add your block inside a block that renders all its children:

• Container block
• Regular block that renders all its children using <?= block() ?> without specifying a block name

However, some blocks render only specific child blocks by specifying the child name, like <?= block('child-name') ?>. If your customization requires placing a block before or after the child-name block, use the .before and .after pseudo-blocks, which are automatically rendered before and after any block.

Short syntax:

.product-infobox.sku.before:
  .my-block: [ ... ]

Equivalent to:

.product-infobox:
  .sku:
    .before:
      .my-block: [ ... ]

Updating a Block by ID

Instead of using the full path to the block, you can update it directly by referencing its ID. For example:

id=my-block-id:
  attributes:
    class: [ my-class ]