Skip to main content
Version: 1.0.0

Theme Structure

This section explains how the storefront Twig layer is organized in YuiCraftPlugin, and how developers should extend or override it safely in project code.

If you are building a custom storefront, this page is your entry point. Use it to understand:

  1. where the default templates are located,
  2. which layer owns which responsibility,
  3. how to override files without breaking plugin upgrade compatibility.

Storefront Layers​

The plugin storefront is intentionally split into 4 layers:

  • yui/layouts/*: global page skeletons and top-level regions
  • yui/pages/*: route-level templates (catalog, cart, checkout, customer, pricing)
  • yui/components/*: reusable feature units (cart summary, checkout sections, product details)
  • yui/blocks/*: low-level partial fragments (totals rows, head includes, popup fragments)

Use this as a strict responsibility model. Keep each concern in its proper layer.

Source of Truth in Plugin​

Default files are shipped under:

src/templates/frontend/
├── layouts/
│   ├── 1column.twig
│   ├── account.twig
│   ├── cart/
│   ├── catalog/
│   ├── checkout/
│   └── product/
├── pages/
│   ├── cart/
│   ├── catalog/
│   ├── checkout/
│   ├── customer/
│   └── pricing/
├── components/
│   ├── cart/
│   ├── catalog/
│   ├── checkout/
│   ├── customer/
│   ├── global/
│   ├── header/
│   └── product/
└── blocks/
    ├── _head/
    ├── cart/
    ├── checkout/
    ├── customer/
    ├── errors/
    ├── global/
    └── ...

When in doubt, inspect this tree first before writing custom templates.

Rendering Flow​

Typical request flow:

  1. A route resolves to a page template (yui/pages/...).
  2. The page extends a layout (yui/layouts/...).
  3. The page/layout compose one or more components.
  4. Components include blocks for repeated low-level rendering.

To customize plugin templates, use path-compatible overrides in your project templates directory.

Rule:

  • plugin path: yui/...
  • project override path: templates/yui/...

Example:

  • plugin file: yui/components/cart/no-items.twig
  • your override: templates/yui/components/cart/no-items.twig

Practical workflow:

  1. Locate the original plugin file under src/templates/frontend.
  2. Copy only the file you need to override, keeping the same yui/... relative path.
  3. Make minimal, intentional changes.
  4. Keep comments for custom logic that differs from plugin defaults.
  5. Re-test cart/checkout/customer flows after each override.

What to Override First​

For most projects, start in this order:

  1. pages for route-level layout decisions
  2. components for reusable feature behavior
  3. blocks for small repeated rendering fragments
  4. layouts only when global structure must change

Avoid overriding layouts/1column.twig early unless required, because it affects the full storefront.

Upgrade-Safe Guidelines​

  • Prefer small targeted overrides over replacing full layout trees.
  • Keep plugin hooks and includes unless you intentionally replace them.
  • Do not move project-specific business logic into global blocks.
  • Document every override in your project changelog/README.
  • Rebase your overrides against plugin updates regularly.