Custom fields

Fields are declared inside a type's tabsets.<key>.fields map. Each field has a type and an optional config object. This page catalogues every documented type: the standard types, the special types that drive the form pipeline and remote data, the validators used inside validate, and the image, date and wysiwyg config notes.

The catalogue covers the 20 documented standard types plus 6 special types (26 documented entries). For where each type may be declared, see content-types, itemset-types and the content model.

Common options

These keys are valid on every field, regardless of type.

Sending the object shape to an id reference is not rejected today: the server normalises it to flat ids on write and on read, on all three, so rows a previous client stored that way repair themselves. Write the flat shape anyway — the normalisation is a safety net for legacy data, not the contract, and every other layer (the backoffice field, the where filters, the index) is built on flat ids. It matters because of what the object shape used to do before that net existed: on items it corrupted silently, the listing showing the right label while the edit form's select came back empty and where never matched; on page a PUT resolved the objects to nothing and emptied the field on a 200. If you inherit a site where a relation holds data but the backoffice select is empty, rewrite that field once in the flat shape.

Standard types

Twenty documented standard types. Fields not exercised on the live fil-rouge site are flagged below.

smartselect per-mode config keys:

Special fields

Form-pipeline and data-fetch types. Declared like any other field, usually one per tabset stage on a form-handling content-type.

Where-clause operators

The vocabulary a query accepts under where:. It is shared by items and api config too, anywhere a where appears.

Empty variables are dropped, unless the clause is strict

By default a clause whose variable resolves to empty is removed from the query, and the remaining clauses run without it. A where reduced to nothing returns the entire collection. That is deliberate and often useful — an absent ?q= on a search page lists everything rather than nothing — but it is also the single most expensive default here, because the failure is silent and looks like a template bug.

Prefix the operator with & to keep the clause even when its variable is empty, so a missing value yields zero rows instead of all of them:

where:
  '&=':
    slug: '{{route.article.slug}}'
    active: active

Use strict mode for anything a detail page depends on (slug), and for filters that must always apply (active, a published flag). Use the default mode when an absent value legitimately means "no filter".

searchable: true

A per-field boolean on the type. It has one effect: it puts the field within reach of the search: operator. It is not required for like/ilike, which name their field directly, and it does not affect the back-office filters: list.

search is word-based: case- and accent-insensitive, several terms combined with AND, and no partial-word matching — a query on forê does not find forêt. It also reads the translated values of the locale being rendered, so on a bilingual site each language searches its own text. For substring behaviour on one named column, use ilike with % wildcards instead. All measured on the Lisière demo; see Build a blog, section 8.

Validators

Rules listed inside validate.config.rules.<field>: [rule…]. A rule is either a bare keyword or a {rule: {param}} map.

validation:
  type: validate
  config:
    rules:
      email: [email, required]
      firstName: []          # no rule, but declared — see below
      consent: [required]

Spam filtering (antispam)

Beyond the recaptcha rule, a validate field can run the submission through the platform's spam filter — an IP / email / content reputation check. It is opt-in per form, and as with the captcha there is no key to obtain and no account to open: the platform holds the credentials.

validation:
  type: validate
  config:
    rules:
      email: [email, required]
      g-recaptcha-response: [recaptcha]
    antispam:
      email: '{{body.email}}'
      message: 'Contact {{body.name}}: {{body.message}}'

email and message are interpolated from the POST ({{body.<field>}}) and they are all the filter sees: a field the template does not name is not checked. Keep the template in sync with the form — a message referencing fields that no longer exist interpolates to an empty string, and a filter that receives nothing waves everything through.

silent defaults to true: a submission flagged as spam still validates and redirects — the visitor sees a normal success — but every action behind the gate (sendmail, save, http) is skipped. Set silent: false to reject the submission openly, like any failed rule.

When the mail actually leaves

sendmail applies its own gate on top of validation, and it fails silently — the visitor lands on the thank-you page either way:

• Platform sender (no custom smtp): the mail leaves only if a recaptcha rule validated on this submission. No captcha rule, no notification.
• Valid custom smtp (host, username, password, from all set): the captcha requirement is lifted.
• The spam filter said spam: nothing is sent, saved or forwarded, whatever the SMTP situation.
• Interpolated recipient (to containing {{…}}): allowed only when the spam filter actually checked the submission. A dynamic recipient with no spam check is skipped — that combination is what turns a contact form into an open relay.

save and http only apply the spam gate: they run with or without a captcha.

Engine-sourced: read from the rendering engine's send path, not exercised live.

Image, date and wysiwyg config

Image versions

An image field defines one or more named crops under config.versions.<key>. At least one is required. Templates read field[0].versions.<key>.url.

image:
  type: image
  label: Image
  config:
    multiple: true   # gallery
    max: 12
    versions:
      card:
        label: Card
        width: 800
        height: 600
      cover:
        label: Cover
        width: 1600
        height: 900

multiple: true + max: N turns the field into a gallery (live-confirmed). Write [{id:'<media-uuid>'}].

Date and calendar

• type: date is a single day, YYYY-MM-DD, with default: now. Render with value | date: 'DD MMMM YYYY'.
• type: calendar holds an RRULE value object (start, end, freq, interval, byday[], count) for recurring events. The template reads _occurrence.start / _occurrence.end, the single materialised occurrence. translatable defaults to false. Skill-sourced, not live-confirmed.

Wysiwyg

A wysiwyg field is configured minimally per-field: only config.limiter (an integer character cap) beyond the common options. All visual styling comes from the site-wide miscellaneous.wysiwyg.styles palette, not per-field config. The field renders as HTML.

Related