The page context

A template’s context is the set of variables it can read. Every page template receives the globals (site, locale, page, request, now and the rest) and the functions (path(), query(), t() and the rest). Each kind of page then adds its own variables, described here.

To see the context of a real page with its values, run:

engine-dmo describe route /places/the-red-lion --json

context in the output is every variable the template receives, with its value; template is the file the site’s chain resolved. It needs the project’s database. engine-dmo template api --json lists the same surface without a database, with your own types’ fields.

Every template starts from the same globals and functions; the kind of page decides what is added on top:

flowchart TD
  G["Globals and functions<br/>site, locale, page, request, t(), path(), query() ..."] --> D["A document's page<br/>entry, its type's key"]
  G --> I["An index page<br/>items, pagination, facets"]
  I --> L["A landing page (engine-dmo)<br/>plus landing"]
  G --> S["The search page<br/>results, pagination"]
  G --> E["Error pages<br/>page only, no entry"]
  D --> B["Block and rich text templates<br/>block or node, plus entry and page"]

Every pageCopy Anchor Link

A document’s pageCopy Anchor Link

Rendered with <type>/entry.html (or the type’s or variant’s template:). The document is entry, and the same value is also available under the type’s key, so listing/entry.html can write {{ listing.title }} or {{ entry.title }}:

{% extends "base.html" %}
{% block body %}
<article>
  <h1>{{ entry.title }}</h1>
  <p>{{ entry.summary }}</p>
  {% if entry.publishedAt %}<p><time datetime="{{ entry.publishedAt|iso }}">{{ entry.publishedAt|date:"long" }}</time></p>{% endif %}
  {{ entry.description|ptext }}
  {% for tag in entry.tags %}<span class="tag">{{ tag.label }}</span>{% endfor %}
</article>
{% endblock %}

page on a documentCopy Anchor Link

Fields every document hasCopy Anchor Link

engine-dmo check holds entry.<field> and <type key>.<field> to the schema, so {{ entry.photo }} on a type without a photo field is an error. It does not follow a document reached any other way: a loop variable over items, query() results or a relation ({% for w in entry.relatedWalks %}{{ w.photo }}), or a component prop. A field those do not have prints nothing, with no error or warning at check or at render, even with template.strict: true. Check those names against engine-dmo describe type <type> and read the output of engine-dmo render.

There is no entry.author. A byline is a field you declare, such as a relation to a person or a text field.

With engine-dmo, the modules add properties: entry.organisation (the organisation that owns a listing, from the CRM module, when it has one) and entry.landings (the live landing pages a place has, or that a document is a result of). See the DMO section.

Field valuesCopy Anchor Link

Each field prints sensibly on its own and has properties and helpers for everything else:

engine-dmo describe fieldtypes lists every field type’s properties and helpers, with the keywords each helper takes. engine-dmo check refuses a property or helper a field’s type does not have.

Guides and collectionsCopy Anchor Link

A guide or collection document’s entry also has:

On a collection’s page pagination is also set at the top level of the context.

An index pageCopy Anchor Link

Rendered with <type>/index.html at the route’s index: address. The route’s paginate: sets the page size.

{% extends "base.html" %}
{% block body %}
<h1>{{ t('places.title') }}</h1>
<p>{{ t('index.count', pagination.total) }}</p>
<ul>
  {% for item in items %}<li><a href="{{ item.uri|url }}">{{ item.title }}</a></li>{% endfor %}
</ul>
{% if pagination.pages > 1 %}
<nav aria-label="{{ t('pager.label') }}">
  {% if pagination.prev %}<a rel="prev" href="{{ pagination.prev|url }}">{{ t('pager.previous') }}</a>{% endif %}
  <span>{{ t('pager.page_of', 'page', pagination.page, 'pages', pagination.pages) }}</span>
  {% if pagination.next %}<a rel="next" href="{{ pagination.next|url }}">{{ t('pager.next') }}</a>{% endif %}
</nav>
{% endif %}
{% endblock %}

The response also carries Link headers with rel="prev" and rel="next".

Only pagination.prev and pagination.next are addresses. They keep the selected facets (/walks?difficulty=easy&page=2). There is no address for an arbitrary page number, and a link written as href="?page={{ n }}" drops every selected facet, which engine-dmo check does not report. Build the pager from prev and next, as above, or print numbered links only on an unfiltered index ({% if not page.noindex %}). The strings pager.label, pager.previous, pager.next and pager.page_of are your own, in config/strings/<locale>.yaml.

Each facet is field, label (the field’s label), selected (whether a value is chosen), clearUrl (the index without this facet) and values. Each value is value, label (an option’s or tag’s label in the request locale), count, selected and url (the index with the value chosen, or removed when it is the chosen one). A facet is selected by the query string ?<field>=<value>.

Facet values are links, not form controls, so draw them as lists of links under a heading inside one navigation landmark, not as a <fieldset> and not as one landmark per facet:

{% if facets %}
<nav aria-label="{{ t('facets.label') }}">
  {% for facet in facets %}
  <h2>{{ facet.label }}</h2>
  <ul>
    {% for v in facet.values %}<li><a href="{{ v.url|url }}"{% if v.selected %} aria-current="true"{% endif %}>{{ v.label }} ({{ v.count }})</a></li>{% endfor %}
  </ul>
  {% if facet.selected %}<p><a href="{{ facet.clearUrl|url }}">{{ t('facets.clear') }}</a></p>{% endif %}
  {% endfor %}
</nav>
{% endif %}

A select facet’s value labels are the option labels, which must be written as a map per locale (label: { en: Easy, cy: Hawdd }); a plain-string option label prints the value instead.

A landing pageCopy Anchor Link

A landing page is an index filtered to a place and a category at a clean path. It renders <type>/landing.html where the chain has one, else <type>/index.html, with everything an index page has, plus landing (key, place, category, title, heading, description, content, faq, count, siblings, parents, breadcrumbs, jsonld and more) and page.landing set to true. See Landing pages.

The search pageCopy Anchor Link

Rendered with search.html at the site’s special.search route, for the request’s q, type, tag, sort, lat, lon, km and page parameters. The page is never cached.

Error pagesCopy Anchor Link

errors/404.html and errors/500.html receive the globals and the functions, with page set to uri (the requested path), title (Not found or Error), type (error) and isPreview. They receive no entry. Keep them simple: an error template that itself fails falls back to a plain-text response.

Block templatesCopy Anchor Link

{% blocks entry.body %} renders each item of a blocks field through blocks/<block key>.html on the site’s chain. The block template receives the page’s globals and functions, the page’s entry and page, and:

<aside class="callout callout--{{ block.tone.value }}">
  {% if block.title %}<p class="callout__title">{{ block.title }}</p>{% endif %}
  {{ block.content|ptext }}
</aside>

engine-dmo check refuses a project that declares a block with no blocks/<key>.html anywhere on a site’s chain. engine-dmo new block <key> scaffolds one.

Rich text serialisersCopy Anchor Link

|ptext renders an object block inside rich text through ptext/<set>/<block key>.html, where the set is the filter’s argument (default when none: |ptext or |ptext:"compact"). The serialiser receives the page’s globals and functions, and:

An object block with no serialiser renders nothing on a public page; under serve --dev it shows a notice naming the template to add, and engine-dmo check warns about it. Naming a set that has no templates at all is an error at render.

Endpoint and module templatesCopy Anchor Link

Declared endpoints (forms and their responses) and some modules render templates with context of their own, such as form, values, errors, submission, signals and endpoint. Those are described with the features: Forms, and, with engine-dmo, the member portal.