Fields
A field is a place on the page that holds content. You write it where the content goes, and Verso makes it editable.
A field is written where its value goes, as a name, a type and any modifiers, separated by colons:
<h1 class="font:h1:bold">{{ headline:text:required }}</h1>
<img src="{{ cover:image }}">
<div>{{ body:rich:headings:lists:links:images }}</div>
<a href="mailto:{{ email:text }}">Write to us</a>
The type is optional. {{ headline }} is the same as {{ headline:text }}.
Types
| Type | Holds | Modifiers |
|---|---|---|
text | One line of plain text | required |
rich | Formatted text, as clean HTML | required and the tools it allows. See Rich text fields |
image | An image and its alt text | required. See Image and colour fields |
color | One of the site's colours | required |
blocks | A block area, where editors stack blocks | The names of the blocks it takes. See Blocks and block areas |
Names
A name uses letters, numbers, - and _, and starts with a letter. each, if, item, page, parent, part and end are taken by the template language. Verso turns the name into the label editors see: call-to-action becomes “Call to action” and heroTitle becomes “Hero title”.
The same field can appear more than once. Both places show the same value, and editing one edits the other. Using one name for two different types is a mistake, and Verso says which line to rename.
Where a field can go
Where you write a field decides how it is edited.
- In the page text, a field is clickable. When it is the only thing in its element, like the
<h1>above, that element becomes editable. Otherwise Verso wraps the value in a<span>in the editor, and only there. - Inside a tag, like the
hrefabove, a field can't be clicked, so it appears in Page settings with the page's title, description and date. - In the
<head>, a field also appears in Page settings. This is how you give a page its own social image or canonical address.
Some types have rules of their own. A rich text field or a block area needs an element to itself. An image field goes in an attribute. Fields can't go inside a <script> or <style>.
Fields can't go inside a list of pages either. A list shows other pages, so it has nothing of its own to edit. To show a field from each page in the list, use a reference:
{{ each:journal }}
<h2>{{ item.headline }}</h2>
{{ /each }}
For a list of items that belong to this page, like a team or a set of questions, use a repeater. Fields inside a repeater belong to each item.
Shared fields
Some words are the same on every page: a footer line, a phone number, a notice at the top. Write the field with site. in front of its name, and it is shared by the whole site:
<footer class="pd-y:d8 font:small">
<p>{{ site.footer:text }}</p>
<div>{{ site.notice:rich:links }}</div>
</footer>
Edit a shared field on any page and every page that shows it changes. In the editor, its label says “same on every page”. It works the same in a part or a block. A shared field can be text or rich, with the same modifiers as any field, required included. It can also be a block area, like {{ site.header:blocks }}, which is how a header or footer made of blocks is shared. Images and colours belong to a page, so {{ site.logo:image }} stops with “A field that's the same on every page can be text, rich text or blocks, not image.” For a shared image, put it in a block in a shared block area.
Shared fields are kept in content/site.json, not in any page:
{
"fields": { "footer": "Made in Savannah", "phone": "+1 912 555 0100" },
"rich": { "notice": "<p>Closed for <a href=\"/news/\">the holidays</a>.</p>" },
"blocks": { "header": [ … ] }
}
Use {{ if:site.notice }} to show part of a template only when a shared field is filled in.
Required fields
required means the page can't be published while the field is empty. The editor marks the field so it's easy to find. The build refuses with a message that names the field, the page and the line:
× content/journal/spring-menu/page.json
"Headline" on Spring menu is required, but it's empty.
Fill it in on the page, or remove :required from templates/post.html, line 9.
Placeholders
In the editor, an empty field shows its label in place of a value, so there is always something to click. A text field shows “Headline”. A rich text field shows its label as a paragraph. An image field shows a soft grey frame. None of this reaches the built site: an empty field there is simply empty, which is what conditions are for.
Where the content is kept
Text, image and colour fields are stored under "fields" in the page's page.json. Rich text fields are files of their own beside it, named after the field. Content for a field the template no longer has isn't shown. The build lists it as a warning, without stopping, and Page settings offers to remove it, so nothing is lost without you knowing.
"fields": {
"headline": "Spring menu",
"email": "hello@northlight.studio",
"accent": { "color": "proof" }
}