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.