Sites, locales and routes

One install serves one or more sites from one database. The install declares its locales once; each site enables a subset and chooses how locales appear in its URLs. Each site’s routes decide which content types have pages on it, and at which URI patterns.

A minimal exampleCopy Anchor Link

Two locales, one site that serves both, and two routed types:

# config/locales.yaml
locales:
  available:
    - code: en
      label: English
      source: true
      timezone: Europe/London
      currency: GBP
    - code: cy
      label: Cymraeg
      fallback: [en]

# config/sites/main/site.yaml
site:
  name: { en: "Visit Wyndmouth", cy: "Ymweld â Wyndmouth" }
  domains: [www.wyndmouth.example, localhost]
  default: true

locales:
  strategy: prefix
  enabled: [en, cy]
  default: en

# config/sites/main/routes.yaml
routes:
  - type: page
    uri: "/{slug}"

  - type: article
    uri:
      en: "/news/{slug}"
      cy: "/newyddion/{slug}"
    index:
      en: "/news"
      cy: "/newyddion"
    paginate: 12

home: { type: page, slug: home }

Run engine-dmo check --fix after writing these by hand: it gives each locale, site and route its id: (see Stable ids). The engine-dmo dev locale add, dev site add and dev route add verbs write the same configuration with ids for you.

With this configuration an English article is at /news/<slug> and its Welsh translation at /cy/newyddion/<slug>. The site needs article/entry.html and article/index.html on its template chain; check refuses the routes until they exist.

LocalesCopy Anchor Link

config/locales.yaml lists every locale the install knows, once. A site never redeclares a locale; it enables some of them.

locales:
  available:
    - code: en-GB
      label: English
      source: true
      timezone: Europe/London
      currency: GBP
    - code: cy-GB
      label: Cymraeg
      fallback: [en-GB]

groups (beside available) declares sets of locales that share values for fields translated per group. engine-dmo check reports a missing source locale, two source locales, two defaults, an unknown time zone or currency, a fallback to an unknown locale or to itself, and a locale in two groups, each at its line. Localisation explains how fields are translated.

SitesCopy Anchor Link

Each site is a directory under config/sites/, named by its key. An install with one site is no different from one with ten: the admin simply shows no site switcher.

# config/sites/town/site.yaml
site:
  name: { en: "Larkwyn" }
  domains: [www.larkwyn.example, town.localhost]

templates:
  roots: [town, _shared]

locales:
  enabled: [en]

templates/town/ must exist as a directory, since the chain names it; check refuses a root that does not.

The site: block:

The rest of site.yaml:

site.yaml has every key.

What sites share and what they do notCopy Anchor Link

A content type is on every site unless sites: in its schema file limits it, and a type or field declared in config/sites/<key>/schema/ belongs to that site alone. A document has an owner site and can be shared to other sites, where it has its own URL from each site’s routes. Multisite templates covers template chains and per-site overrides.

A site’s locales and URL strategyCopy Anchor Link

locales:
  strategy: prefix
  enabled: [en, cy]
  default: en
  fallback:
    cy: [en]

The prefix is the locale’s language subtag (cy) when no other enabled locale shares it, and otherwise the whole code in lower case (en-gb, en-ie).

# strategy: domain
locales:
  strategy: domain
  enabled: [en, cy]
  default: en
  domains:
    en: www.wyndmouth.example
    cy: www.wyndmouth-cy.example

check refuses strategy: domain without a host for every enabled locale.

RoutesCopy Anchor Link

A route gives a content type pages on a site. Without a route a type’s documents still exist and can be listed and related, but have no URL on that site, and check warns about a site with no routes.yaml.

routes:
  - type: article
    uri:
      en: "/news/{publishedAt|date:'Y/m'}/{slug}"
      cy: "/newyddion/{publishedAt|date:'Y/m'}/{slug}"
    index:
      en: "/news"
      cy: "/newyddion"
    paginate: 12
    feed:
      formats: [rss, atom]

The rest of routes.yaml:

home: { type, slug } takes one slug for every locale: a document is the home page in a locale when its slug in that locale is exactly that value. Give the home page the same slug (home) in every locale. A Welsh translation slugged hafan is not the Welsh home page: /cy/ is not found and the page is served at /cy/hafan. The home page answers / (or /cy/), and its slug path (/home) is not found.

Without home, a document of any routed type whose slug in a locale is exactly __home__ answers / in that locale, so an editor can choose the home page. A site uses one mechanism or the other, and check refuses both together.

check validates redirects at their line: a 410 with a target, a status outside the five, a loop, and a target the site does not answer:

config/sites/main/routes.yaml:29:13: redirect loop: /loop-a -> /loop-b -> /loop-a
config/sites/main/routes.yaml:31:25: redirect target /nowhere/at/all resolves to nothing on site main in cy, en

routes.yaml has every key, and Redirects and URLs covers the redirects editors manage in the admin.

Addresses are stored, not computedCopy Anchor Link

When a locale of a document is published, its address on every site it is on is resolved from that site’s route and stored. Requests are answered from the stored addresses, so a page’s URL does not change because a field it does not use changed. When a published slug changes, the old address redirects (301) to the new one. When a route’s pattern or parent changes, documents whose stored address no longer matches are moved when the engine next starts, each old address redirecting to the new one.

How a request is answeredCopy Anchor Link

A request passes through three choices, each made from the configuration and the stored addresses:

flowchart TD
  req["Request: host and path"] --> site{"Host in a site's domains?"}
  site -- yes --> s1["That site"]
  site -- no --> s2["The default: true site"]
  s1 --> loc{"strategy: domain?"}
  s2 --> loc
  loc -- yes --> l1["The host names the locale"]
  loc -- no --> l2{"First path segment<br/>a locale prefix?"}
  l2 -- yes --> l3["That locale"]
  l2 -- no --> l4["The site's default locale"]
  l1 --> page{"Rest of the path"}
  l3 --> page
  l4 --> page
  page -- "redirect rule" --> redirect["Redirect"]
  page -- "stored document address" --> doc["Document, rendered with<br/>type/entry.html on the site's chain"]
  page -- "index, feed, landing or special page" --> other["That page's template"]
  page -- "nothing" --> notfound["errors/404.html"]

engine-dmo describe route <path> shows which route answers a path, the template the chain resolved and the whole template context, and engine-dmo render <path> --host <host> --locale <code> renders it, both against a database.

CommandsCopy Anchor Link