Asset
The asset field (one or several media library files: images, documents, audio or library videos) with kinds, file and image constraints, per-use alt text, captions and framing, the stored shape and the image value templates receive.
An asset field picks files from the media library: a hero image, a gallery, a PDF download, an audio guide. It stores the asset’s id, never its URL, so replacing or renaming a file never breaks a page. Each use of an asset may carry its own alt text and caption (per locale) and its own focal point, hotspot and crop, over the asset’s own values in the library.
fields:
- name: heroImage
type: asset
alt: required
min_width: 1600
aspect: "16:9"
caption: true
- name: gallery
type: asset
multiple: true
min: 2
max: 12
caption: true
tags: [gallery]
upload: true
upload_tags: [gallery]
- name: download
type: asset
kinds: [document]
accept: [pdf, application/vnd.ms-excel]
max_size: 20MB Parameters
| Parameter | Type | Default | What it does |
|---|---|---|---|
kinds | list of image, document, audio, video | [image] | What may be chosen. video is a library video reference; for YouTube, Vimeo and files on a host, use a video field. |
multiple | boolean | false | An ordered list of assets. |
min | whole number | none | With multiple: the fewest assets to publish. |
max | whole number | none | With multiple: the most assets. |
accept | list | any of the kinds | Narrows the kinds by extension (jpg, pdf) or media type (application/pdf, image/*). |
max_size | size | none | The largest file, in decimal units: 500kB, 10MB, 2GB, or a number of bytes. |
min_width, min_height | pixels | none | Images: the smallest size accepted. |
max_width, max_height | pixels | none | Images: the largest size accepted. |
aspect | width:height | none | Images: the proportion, such as 3:2, within two percent. |
orientation | landscape, portrait or square | none | Images: the orientation. Give aspect or orientation, not both. |
alt | inherit or required | inherit | Images: inherit uses the asset’s alt text from the library, which a use may override. required refuses an image with no alt text in the locale (per use or in the library) unless it is marked decorative. |
caption | boolean | false | Offers a per-use caption, per locale. |
focal | boolean | true for images | Images: offers a per-use focal point, hotspot and crop. |
tags | list of tag keys | none | The picker shows assets with these tags. |
upload | boolean | false | Lets an editor upload from the field; they still need the media upload permission. |
upload_tags | list of tag keys | none | Tags an upload from the field receives. Needs upload: true. |
engine-dmo check reports a parameter that does not fit the kinds: alt applies to images, and this field takes document, aspect and orientation are given together, min and max count the assets of a field with multiple: true, unknown asset kind "photo" (with the four kinds listed), "10XB" has an unknown unit; write B, kB, MB or GB.
Validation
When an editor chooses a file, the field refuses one that does not fit, with the reason:
| Code | Message |
|---|---|
asset_kind | This kind of file is not accepted here |
asset_type | This type of file is not accepted here; choose PDF, … |
asset_size | Choose a file of 20 MB or less |
image_min_width / image_min_height | Choose an image at least 1600 pixels wide / high |
image_max_width / image_max_height | Choose an image no more than N pixels wide / high |
image_aspect | Choose an image in the proportion 16:9 |
min_assets / max_assets | Choose at least N / Choose no more than N |
asset_choose | Choose a file from the library |
focal_offered, framing_offered, caption_offered | This field does not take a focal point / a hotspot or a crop / a caption |
At publish the engine also checks each asset against the library:
| Code | Severity | When |
|---|---|---|
asset_missing | error | The image is no longer in the library. |
rights_expired | error at publish, warning on save | The asset’s usage rights have ended. |
rights_expiring | warning | The rights end while the page stays live. |
alt_needed | error | alt: required and the image has no alt text in the locale (per use, in the library, or by fallback), and is not decorative. |
alt | error at publish | The image has no alt text anywhere and media.require_alt_text is on (the default), and is not decorative. |
alt_fallback | warning | The alt text shown comes from another locale. |
alt_fallback_blocked | error | As above, on a site whose accessibility.alt_fallback refuses fallback alt text for the locale. |
Stored value
One asset:
{ "asset": "6f1c0b0e-...", "focal": { "x": 0.42, "y": 0.35 }, "alt": "Boats in the harbour at dawn", "caption": "Clovelly harbour" } With multiple, a list of the same, each with a _key. focal is { x, y } and hotspot and crop are { x, y, w, h }, all fractions of the image. The asset and its framing are shared by every locale; alt and caption are each locale’s own. That is why engine-dmo describe type shows the field as translate locale. A locale that writes the field with a different asset changes it for every locale, and one that writes only alt empties the shared choice; use structure: per_locale for a different image per locale (Links, assets and videos). In a seed file an asset is named by its seed key, { asset: harbour-dawn } or just harbour-dawn (Seeding and importing).
With index: true each asset id is projected, so lists can find the documents that use an asset.
Template value
The field is an image value (or, with multiple, a list of them). Printing it prints the original’s URL.
| Property | What it is |
|---|---|
url | The original’s URL. |
alt, altLang | The per-use alt text, else the asset’s for the site and locale; altLang names the locale it came from when it is a fallback. |
decorative | Whether an empty alt is intended. |
caption, captionLang | The per-use caption, else the asset’s. |
credit, creditRequired | The credit line the licence requires, and whether a template must show it. |
width, height, aspect, orientation, dominant | Images: size, proportion, orientation and dominant colour (#rrggbb). |
focal, hotspot, crop | The per-use framing, else the asset’s. |
id, kind, mime, extension, type, filename, title, bytes, size | The file’s facts; type is PDF, JPG; size is 2.1 MB in the request locale. |
| Method | What it writes |
|---|---|
img(transform, ...) | An <img> with src, srcset, sizes, width, height, alt, loading and decoding. |
picture(transform, ...) | A <picture> with a source per format and art direction. |
figure(transform, ...) | The picture in a <figure> with the caption and credit in <figcaption>. |
transform(name, width=) | A transform object for custom markup. |
url(transform, width=, format=, absolute=) | One derivative’s address, for an Open Graph image or a CSS background. |
link(text=) | A download link announcing the type and size: Annual report (PDF, 2.1 MB). |
audio() | An <audio controls> for an audio asset. |
The image methods take sizes=, priority=true for the page’s main image, loading=, fetchpriority=, placeholder=, alt=, and any other HTML attribute. A transform is a name from config/images.yaml.
{% if entry.heroImage %}{{ entry.heroImage.figure("hero", priority=true) }}{% endif %}
<div class="gallery">
{% for image in entry.gallery %}{{ image.figure("card") }}{% endfor %}
</div>
{% if entry.download %}<p>{{ entry.download.link() }}</p>{% endif %} engine-dmo check warns when an image is printed with img() or picture() and its credit nowhere in the template; figure() writes it. See Images for transforms, sizes and art direction, and Media for the library itself.
Phone and opening hours
The phone field (an E.164 number parsed in a region, with accepted number types) and the opening_hours field (a weekly pattern, seasons, exceptions and public holidays), with parameters, validation, stored shapes and template values.
Link
The link field (one link or a list) to a document, asset, URL, email address, phone number, site or anchor, with kinds and their settings, editor attributes, rel, named styles, sub-fields, the stored shape and the link value templates receive.