How a page finds its shell
There is no routing file that lists pages. An entity in data/ claims an address, and the engine walks a short ladder to find its template.
An entity claims an address
An entity is a JSON file: data/service/branding.json, data/blogposting/summer-closure.json. With a slug it is a page at that address — a list (data/itemlist/…) excepted: it is curation, shown by a page whose template reads it. The slug is one string (the same path in every language) or a map per language:
"slug": { "nl": "/diensten/branding", "en": "/services/branding" }
URL per language, alternate-language links, sitemap entry and @id all derive from the map on read, stored nowhere else. A language missing from the map means no page in that language. The home page is the designated entity data/webpage/home.json, which claims the root without a slug.
The ladder
The router matches the path against the slugs, finds the entity and its type, and picks a shell in this order:
| Rung | Shell | Note |
|---|---|---|
| 1. Designated | campaign.php, from "presentation": { "shell": "campaign.php" } on the entity. A subfolder is allowed: "service/landing.php". |
Always wins when set. |
| 2. Type | <type>.php, lower-cased: a BlogPosting renders through blogposting.php, a Service through service.php. |
Where nearly all your work goes — one shell per kind of thing. |
| 3. Floor | index.php, renders the entity generically from its schema. |
A freshly claimed page works before you write anything; it just looks plain. |
Each rung is a file name; where the file sits is the language’s business (next section). Data carries the content; the template carries the direction. The floor is a safety net, not a design.
Per language
Every rung looks in three places, most specific first: the region’s tree, the language’s tree, then templates/ itself — the language-invariant seat.
templates/en-gb/blogposting.php the region (only where it differs)
templates/en/blogposting.php the language
templates/blogposting.php every language
So a site in one language keeps no language folder at all: its shells sit in templates/ directly. A multilingual site keeps in templates/<lang>/ only what differs per language — a shell that carries language-specific copy or structure — and shares the rest. Translating a site is then a choice per file: add templates/en/home.php when the English home needs its own shell, leave templates/blogposting.php where the difference is content, which the data and the strings already carry. A tree beside the invariant file always wins; a regional variant such as en-gb falls to en before the invariant seat.
Which languages a page has is never the shell’s decision: the slug map on the entity declares them, and an invariant shell opens no language the entity did not declare. The engine requires a floor — templates/index.php, the invariant seat of the last rung, is the one that ships. The 404.php is found the same way, with one extra step: region, base, default, then templates/404.php; where none exists the engine’s own bare page serves, with an audit warning until the theme has one.
Inside a type shell
A type shell starts the same way every time: identify the entity, load it, bail to the 404 if it is missing.
<?php
defined('CTXR') || exit;
$slug = page_identifier(); // the language-invariant key the router resolved
$article = data('blogposting/' . $slug); // the entity, localised to the active language
if (empty($article)) page_notfound();
?>
<!doctype html>
<html lang="<?= locale_lang() ?>">
<head>
<?php snippet('meta'); ?>
<?php seo_head([
'title' => $article['headline'] . ' | Site',
'description' => $article['description'] ?? '',
'type' => 'article',
'image' => data_image_url($article['image'] ?? null),
]); ?>
<?php ld(ld_page('BlogPosting', ld_entity('blogposting/' . $slug))); ?>
</head>
<body>
<?php section('header'); ?>
<main id="main">
<h1><?= e($article['headline']) ?></h1>
<?php body($article['articleBody'] ?? ''); ?>
</main>
<?php section('footer'); ?>
</body>
</html>
Each line is explained next: data() and localisation, the head helpers, and why body() is the only raw echo.
Two things that are not the ladder
Redirects in theme/index.php: when a slug changes, a 301 line catches the old address. Explicit routes in the same file map a path to a shell directly, for the rare page that is not an entity — a form’s POST handler, a one-off. Keep that table empty where you can: only a page that is an entity is known to the machine views.