Overrides

How site templates, routers, and controllers take priority over addon and framework defaults, and how to compose instead of copy.

Updated
On this page

The chain

An @alias names a root folder: @phlat is the core, @users or @dash an addon. Anything named @alias/..., whether a view, a template, a field or a field type, can be replaced by putting your own file at the same path under @alias in your site. A bare name is always your site's own, so it has nothing to override. For an addon view such as @users/login:

site/views/@users/login/index.latte         ← checked first
phlat/addons/users/views/login/index.latte  ← addon default

Templates use this chain, and so do the core's views: site/views/@phlat/errors/ before phlat/views/errors/. The first file that exists wins. A plain site view has no chain; it is only site/views/{view}/. Routers and controllers are the exception, covered below.

A template override replaces, it doesn't merge

If site/views/@users/login/index.latte exists, it fully replaces the addon's template. None of the addon's markup runs unless the override references it.

A naive override therefore starts as a copy of the whole file, which drifts from the addon's original as it evolves. Compose instead of copying.

Templates

A template can't extend itself. {layout '@users/login/index.latte'} inside site/views/@users/login/index.latte resolves back to the override, because site/views/ is checked first. Override at a seam instead: when an addon template pulls in pieces with {include}, place a file of the same name under site/views/@dash/ and the rest keeps running. An override stands in for the addon's file, so its own bare includes are the addon's and a copy keeps working. To reach one of your site's templates from an override, use a relative path such as {layout '../../layout.latte'}.

When building an addon, or a site view meant to be overridden, split it into small partials at the points a caller is likely to customize.

Controllers

A controller in site/views/@users/login/controller.php extends the addon's instead of replacing it. The addon's controller runs first, then yours, and your result is merged over the addon's: later string keys win and lists are not appended. Your $context holds the addon's data as well as the layers before it, so read from it to build on a value:

<?php
// site/views/@users/login/controller.php

return fn(array $context): array => [
    'showSupportLink' => true,
    'providers' => [...$context['providers'], 'sso'],
];

The same goes for a global controller at site/views/@dash/controller.php, which extends the addon's views/controller.php for every page of the addon. A new key only shows once a template renders it, so pair it with a template override.

Routers

A router is never overridden. site/views/@users/login/router.php is ignored, because an update to the addon's routes would leave a copy stale and silently 404. To serve different routes, write a view of your own with its own router.php and include the addon's templates from it.

Full overrides

Replace a template whole when the change is large, such as a login page redesigned from scratch. Compose when customizing a seam.

Fields and field types

site/fields/@phlat/password/index.json replaces the core's password field everywhere it is used, inside the core and in every field that extends it. Inside an override, extending the name it overrides means the shipped original, so a tweak doesn't need a full copy:

// site/fields/@phlat/password/index.json
{
    "extends": "@phlat/password",
    "label": "Passphrase"
}

site/fieldtypes/@phlat/text/ replaces the folder the core's text type reads its index.json and its edit.latte, preview.latte and render.latte from. It is the whole folder, so copy the templates you want to keep. It can't replace the PHP class: other types extend the core's, so a second FieldTypeText is a fatal error. For different behaviour, write a type of your own that extends the core's class.