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.
A link field holds a link an editor makes: a call to action, a booking link, a list of related pages. A link to a document, asset or site stores the target’s id, never its URL, so moving or renaming the target never breaks the link. The web layer resolves every link of a page in one batch to the target’s live address in the request locale, and a link whose target is not live renders nothing rather than a dead link.
fields:
- name: website
type: link
kinds: [{ of: url }]
- name: cta
type: link
kinds:
- { key: page, of: document, types: [page, walk], label: { en-GB: A page on this site } }
- { key: file, of: asset, kinds: [document], accept: [pdf] }
- { key: web, of: url, hosts: [example.org, www.example.org] }
- { key: mail, of: email, subject: true }
- { of: phone }
attributes: [text, title, aria_label, new_tab, rel, suffix, style]
text: required
rel: [nofollow, sponsored]
styles:
- { key: primary, label: { en-GB: Primary button }, class: button button--primary }
- { key: plain, label: { en-GB: Text link }, class: link }
fields:
- { name: icon, type: select, options: [arrow, download] }
- name: related
type: link
multiple: true
max: 5
kinds: [{ of: document, types: [walk], sites: network }, { of: url, relative: true }] Parameters
| Parameter | Type | Default | What it does |
|---|---|---|---|
kinds | list | url, email, phone, anchor | The kinds of link offered, in order. Each is { key, of, label, ...settings } (below). |
multiple | boolean | false | An ordered list of links. |
min | whole number | none | With multiple: the fewest links to publish. |
max | whole number | none | With multiple: the most links. |
attributes | list of text, title, aria_label, new_tab, rel, suffix, style | [text, new_tab] | What the editor may set on each link. |
text | required, optional or none | optional | Whether the editor writes link text. none takes no text of its own; required needs text in attributes. |
rel | list of rel tokens | none | The rel values the editor may choose: alternate, author, bookmark, external, help, license, me, next, nofollow, noopener, noreferrer, prev, privacy-policy, search, sponsored, tag, terms-of-service, ugc. Used with rel in attributes. |
styles | list | none | Named styles: { key, label, class }. The editor picks one; the template’s link gets its class. Each style gets an id from check --fix. |
fields | list | none | Sub-fields on every link, declared like any field (an icon, a short description for a card). |
structure | shared or per_locale | shared | per_locale makes the whole link each locale’s own. |
Kinds
Each kind has of, the engine kind; key, your handle for it (defaults to of, and must be unique within the field); label, what the editor sees; and the settings its engine kind takes:
of | Target | Settings |
|---|---|---|
document | A document, by id | types: the type keys it may point at (default any). sites: own (the default, this site), network (any site of the network) or any. |
asset | A media library asset, by id | kinds, accept, tags, as an asset field takes them. |
url | A web address | hosts: the host names allowed. relative: true also accepts a path starting with /. |
email | An email address | subject: true offers a subject line. |
phone | A telephone number | none |
site | Another site of the network’s home page, by id | none |
anchor | An element id on the same page, without # | none |
engine-dmo check refuses an unknown of, a setting that belongs to another kind (a url kind does not take "types"), a key offered twice, an unknown attribute or rel token, a style with no class, and min or max without multiple.
Validation
| Code | Message |
|---|---|
kind | Choose a link type: … |
target | Enter where the link goes |
document | Choose a page to link to |
link_asset | Choose a file to link to |
url | Enter a full web address starting with http:// or https:// |
url_relative | Enter a full web address starting with http:// or https://, or a path starting with / |
url_host | Link to one of: … |
email | Enter an email address |
phone, region | Enter a telephone number / Enter the number with its country code, starting with + |
site | Choose a site of the network |
anchor | An anchor is the id of an element on the page, without the # |
suffix, suffix_kind, suffix_offered | A query and fragment only, such as ?tab=prices#booking, on a page, web address or site link, when suffix is offered |
text_required, text_none | Enter the link text / This link takes no text of its own |
label_in_name | The accessible name should contain the visible text, so a person using speech can say what they see |
rel, link_style | A rel or style the field does not offer |
new_tab_offered, title_offered, aria_label_offered, subject_offered | A setting the field does not offer |
min_items / max_items | Add at least / no more than N links |
At save and publish the engine also checks that a document target is of an allowed type and on an allowed site.
Stored value
{
"_key": "l1", "kind": "page", "of": "document", "document": "8a6e...",
"suffix": "#booking", "new_tab": false, "rel": ["sponsored"], "style": "opt_3k9d0m2w1x",
"text": "Book a table", "title": "", "aria_label": "",
"fields": { "icon": "arrow" }
} The target key follows of: document, asset, url, email (with subject), phone (with region), site (a site id) or anchor. With multiple, a list of these. text, title and aria_label are each locale’s own; the target, style, rel and sub-fields are shared by every locale. In a seed file a document target is document: <type>/<seed key> and an asset target asset: <seed key>.
A link is not projected into the query index; document and asset targets are recorded as references, so the admin lists broken links and what links to a page.
Template value
Printing the value prints its URL. With multiple, the field is a list of link values.
| Property | What it is |
|---|---|
url | The resolved address with the suffix; empty when broken. A document on another site of the network is an absolute URL. |
text | The editor’s text, else the target’s title, the asset’s title, the URL’s host and path, the address or the number. |
kind, of | Your kind key and the engine kind. |
title, ariaLabel | The editor’s title and accessible name. |
newTab, target | Whether a new tab was asked for, and _blank when it was. |
rel | The chosen rel tokens, with noopener for a new tab. |
style, class | The chosen style’s key and class. |
isExternal | Whether the link leaves the site. |
broken | Whether the target is not live in the locale chain. |
document | The target document as an entry. |
asset | The target asset: url, title, filename, mime, extension, bytes, size. |
fields | The sub-field values by name. |
isAffiliate, affiliate | engine-dmo: whether the link goes through an affiliate programme, and which (Affiliates). |
| Method | What it writes |
|---|---|
link(text=, ...) | The whole <a> with every attribute the editor set, the style’s class merged with class=, and the new-tab and file-type announcements. Nothing when the link is broken or empty. href cannot be passed. |
attributes(...) | The attributes alone, href included, for an element you write yourself. |
{{ entry.cta.link() }}
{{ entry.cta.link(text="Book now", class="wide") }}
<a {{ entry.cta.attributes(class="card") }}>
<h3>{{ entry.cta.text }}</h3>
{% if entry.cta.fields.icon %}<span class="icon-{{ entry.cta.fields.icon.value }}"></span>{% endif %}
</a>
<ul>{% for l in entry.related %}<li>{{ l.link() }}</li>{% endfor %}</ul> See Links for links in templates generally. The link annotation in rich text uses the same kinds, attributes and rel (Blocks and rich text).
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.
Video
The video field: a YouTube or Vimeo video, a media library video or an .mp4/.webm file on an allowed host, with poster, captions confirmation, title and transcript, rendered through a privacy facade.