Layouts

Layouts control the outer HTML contract of storefront pages. They should contain structure, shared includes, and top-level extension points, but not page-specific business rules.

Base Layout Contract

yui/layouts/1column.twig is the primary base layout used across storefront routes.

Key responsibilities in this file:

• load default head includes (meta, favicons, fonts, styles, scripts)
• expose hook points for plugins and custom modules
• define the major page regions (before_content, main, after_content, popups)
• include global UX elements (messages, global scripts, popups)

Critical hook points to preserve in custom overrides:

• after-head-start
• before-head-end
• after-body-start
• before-body-end

If these are removed, third-party integrations and plugin features may stop rendering correctly.

Layout Families

The plugin provides specialized layout families for different storefront contexts:

• yui/layouts/catalog/*
• yui/layouts/product/*
• yui/layouts/cart/*
• yui/layouts/checkout/*
• yui/layouts/account.twig

Common patterns:

• cart: 1column, 2column-left, 2column-right, hyva
• checkout: 1column, 2column-*, compact, wide, fullpage, hyva, stripe
• product: 1column, 2column-left, 2column-right

How to Create a Custom Layout

Use this process to keep upgrades manageable:

1. Start from the nearest plugin layout variant.
2. Override only the needed blocks.
3. Keep original include/hook contract unless there is a strong reason to change it.
4. Register custom assets with depends on plugin asset bundles when possible.
5. Validate cart/checkout/account pages after changes.

Example extension:

{% extends 'layouts/1column.twig' %}

{% block head %}
    {{ parent() }}
    {# Add project-level metadata or styles here #}
{% endblock %}

{% block main %}
    {# Layout-specific wrapper for downstream pages #}
    <div class="my-layout">
        {{ block('content') }}
    </div>
{% endblock %}

Do and Do Not

Do:

• keep layout-level concerns in layouts
• centralize reusable wrappers and shared structure
• document custom layout variants for your team

Do not:

• move route-specific business logic into base layouts
• remove plugin hook calls blindly
• duplicate checkout/cart logic that already exists in pages/components