Components

A component is a reusable piece of markup with a contract. The contract, component.yaml, declares the props the component takes, the slots a caller may fill and whether the caller may add attributes. engine-dmo check holds every call to the contract, on every site, and the engine holds it again at render, so a wrong prop is an error with a file, line and column rather than a page that renders wrong.

Use a component for anything you would otherwise copy between templates: a card, a page header, a notice, a pager, an icon. Use {% include %} only for a fragment of one layout that needs the caller’s whole context.

A first componentCopy Anchor Link

engine-dmo new component teaser

created templates/_shared/components/teaser/component.yaml
created templates/_shared/components/teaser/teaser.html
created templates/_shared/components/teaser/teaser.css

# templates/_shared/components/teaser/component.yaml
name: teaser
description: A news story as a card for a grid, its title the one link.
props:
  doc:     { type: article, required: true, description: "The story the card shows" }
  heading: { type: enum, values: [h2, h3], default: h3, description: "The title's level" }
  tone:    { type: enum, values: [plain, feature], default: plain }
  note:    { type: string, description: "A line in place of the summary" }
slots:
  meta: { required: false, description: "Below the title, in place of the date" }
attrs: root

{# templates/_shared/components/teaser/teaser.html #}
<article class="teaser teaser--{{ tone }}" {{ attrs }}>
  {% if doc.heroImage %}
    {{ doc.heroImage.img("card", class="teaser__img") }}
    {% if doc.heroImage.credit %}<p class="teaser__credit">{{ doc.heroImage.credit }}</p>{% endif %}
  {% endif %}
  <{{ heading }} class="teaser__title"><a href="{{ doc.uri|url }}">{{ doc.title }}</a></{{ heading }}>
  {% if slots.meta %}<p class="teaser__meta">{% slot 'meta' %}{% endslot %}</p>{% endif %}
  {% if note %}<p>{{ note }}</p>{% elif doc.summary %}<p>{{ doc.summary }}</p>{% endif %}
</article>

{% for article in items %}
  {% component 'teaser' doc=article heading='h2' %}
{% endfor %}

{% component 'teaser' doc=entry tone='feature' %}
  {% slot 'meta' %}<time datetime="{{ entry.publishedAt|iso }}">{{ entry.publishedAt|date:"medium" }}</time>{% endslot %}
{% endcomponent %}

Where a component livesCopy Anchor Link

A component is a directory under components/ in a template root:

The name is the directory name: lower case letters, digits, - and _. Both files resolve along the site’s template chain, so a site root can override a shared component (Overriding a component).

The contractCopy Anchor Link

component.yaml is decoded strictly: an unknown key is an error, so a misspelt requried cannot quietly make a prop optional.

PropsCopy Anchor Link

required and default are exclusive. attrs and slots are reserved and cannot be prop names.

A prop the call leaves out takes its default, or is empty when it has none, so the markup can test any declared prop with {% if note %} without an error.

SlotsCopy Anchor Link

attrsCopy Anchor Link

Calling a componentCopy Anchor Link

{% component 'name' prop=expression prop2=expression %}

• The name is a quoted string literal, so engine-dmo check can find the contract. A variable name is a parse error.
• Props are name=expression pairs separated by spaces. A prop passed twice is an error.
• attrs= is not a prop. It passes the call site’s attributes: a value an engine helper built, such as sigmx.fragment(...), or a map. The template language has no map literal, so in practice attrs= takes a helper’s value:

{% component 'teaser' doc=article attrs=sigmx.fragment('results', on='click') %}

A map passed as attrs prints as escaped name="value" pairs in key order; true prints the bare name, and false or an empty value leaves the attribute out.

A call with slotsCopy Anchor Link

A call has a body, closed by {% endcomponent %}, exactly when the first thing after the tag (whitespace aside) is a {% slot %}:

{% component 'notice' tone='warning' %}
  {% slot 'body' %}<p>{{ t("closures.notice") }}</p>{% endslot %}
{% endcomponent %}

• Every region of the body is a named slot. Text or markup outside a slot is an error, both at check and at render. There is no unnamed default slot.
• A slot filled twice in one call is an error.
• A slot’s content renders in the caller’s scope, so it can use the caller’s loop variables and {% set %} names.

Inside the markupCopy Anchor Link

The markup sees:

• the page’s globals (site, locale, page, t(), path(), url(), assets, images and the rest of the globals);
• each declared prop: the value passed, else its default, else empty;
• attrs, the call’s attributes, ready to print;
• slots, the filled slots by name.

It never sees the caller’s own variables (a loop variable, a {% set %}), so a component cannot come to depend on the page that happens to call it. Pass what it needs as a prop.

Print a slot with a fallback, or test whether it was filled:

{% slot 'meta' %}<span>{{ t("teaser.no_date") }}</span>{% endslot %}
{% if slots.meta %}<p class="teaser__meta">{% slot 'meta' %}{% endslot %}</p>{% endif %}

{% slot 'name' %}fallback{% endslot %} in the markup prints what the call filled, or the fallback when it filled nothing. A {% slot %} the markup prints must be declared in the contract.

Components can call other components.

What is checkedCopy Anchor Link

engine-dmo check (and the language server as you type) reports each of these at its line and column, every site along its own chain. The engine refuses the same mistakes at render, so a value the check could not see (a prop computed from a variable) still fails loudly.

All of these are errors (MRD-1006, invalid configuration), and engine-dmo check exits 3.

What is not checkedCopy Anchor Link

A prop typed with one of your types (doc: { type: article }) is held to that type at the call, but fields read on it inside the markup are not. {{ doc.photo }} on a type with no photo field passes engine-dmo check and prints nothing at render, with no warning, even with template.strict: true. The same holds for a field read on a loop variable or a query() result. Take field names from engine-dmo describe type <type>, and read the rendered page (engine-dmo render <path>) to see each one print.

Dates have no properties: write {{ entry.publishedAt|iso }} and {{ entry.publishedAt|date:"medium" }}. A property such as entry.publishedAt.iso is not reported and prints nothing.

Overriding a component on one siteCopy Anchor Link

A site whose template chain puts its own root before _shared can override a component by adding the same directory to its root (Multisite templates):

templates/
  _shared/components/teaser/component.yaml
  _shared/components/teaser/teaser.html
  town/components/teaser/teaser.html        the town's own markup

• An override may carry markup alone. It then inherits the contract it overrides.
• An override may carry its own component.yaml, which must take the same inputs: the same props with the same types, requiredness and enum values, the same slots with the same requiredness, and the same attrs. Descriptions and defaults may differ. Anything else is an error at the override’s contract (component teaser on site town overrides _shared/components/teaser/component.yaml and takes different inputs: ...). A component with different inputs needs a name of its own.
• The override’s markup may extend the shared markup and replace blocks of it: {% extends "components/teaser/teaser.html" %} inside the override resolves to the next file of that name along the chain, never to itself.

Every call site, on every page and in every shared template, then renders the site’s version, unchanged.

Components and the frontend buildCopy Anchor Link

The co-located <name>.css and <name>.js files are not linked by the engine. With the meridian() Vite plugin, each site’s main bundle imports the CSS and JS of every component that resolves for that site, so a site’s override brings its own styles and not the shared ones. engine-dmo assets manifest lists which component directory each site resolves. See Frontend build.

Component styles are not scoped or class-prefixed by the build. Prefix your class names (the scaffold uses c-<name>).

Caching and componentsCopy Anchor Link

A component inside a {% cache %} block registers the documents passed to it as props, so publishing one of them clears the block. See Caching.