Templates

In this documentation, "templates" refers to route-level page templates under yui/pages/*. These files orchestrate the final page by extending layouts and composing components.

Page Ownership

A page template should answer only:

• which layout this route uses
• which major blocks are filled
• which components are rendered for this route

It should not own deeply reusable markup or low-level fragments.

Current Page Directories

• yui/pages/catalog/*
• yui/pages/cart/*
• yui/pages/checkout/*
• yui/pages/customer/*
• yui/pages/pricing/*

High-Value Page Examples

• product detail: yui/pages/catalog/product.twig
• catalog listing/search: yui/pages/catalog/products.twig, search-results.twig
• cart screens: yui/pages/cart/view.twig, view-hyva.twig
• checkout screens: yui/pages/checkout/view.twig, success.twig, failed.twig, redirect-form.twig
• customer account area: yui/pages/customer/my-account.twig and yui/pages/customer/account/*

Typical Page Composition Pattern

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

{% block product_media %}
    {% include 'yui/components/product/media-simple' %}
{% endblock %}

{% block product_details %}
    {% include 'yui/components/product/details-simple' %}
{% endblock %}

{% block product_additional %}
    {# optional route-specific inserts #}
{% endblock %}

How to Build a New Page Safely

Recommended flow:

1. Pick the closest existing page in the same domain.
2. Keep the same layout unless the business requirement changes structure.
3. Reuse existing components first.
4. Introduce new components only when logic is genuinely reusable.
5. Push low-level repeated snippets to blocks.

Performance and Maintainability Rules

• Avoid heavy loops and expensive queries in Twig; prepare data in controllers/services.
• Keep translation and label formatting centralized where possible.
• Reuse existing checkout/cart/customer components to preserve behavior consistency.
• Keep page files thin and easy to read for future maintenance.