Designing Editor-Friendly Fields

Defining Custom Fields says what each property does. This page is about when to reach for it, so the editing form an editor opens is short, clear, and hard to fill in wrong.

Required only where output breaks
Set IsRequired when an empty value would render broken markup — an empty link, a card with no title. When the template already guards the field with is_valid and degrades gracefully, leave the field optional; requiring it only blocks saving a half-finished page. Whenever IsRequired is set, write a RequiredMessage that names what is missing in the editor's terms ("Add an answer.", "Select a thumbnail.") instead of the generic "Value is required". RequiredMessage works on every field that stores a value, not only on forms.

Help text for values that are easy to get wrong
An opaque or format-sensitive value — an id copied from another site, a code with a particular shape — earns Subtext that names the expected shape with an example, because the editor still needs the hint after they start typing:

{ "Type": "text", "FieldID": "intro_video", "Label": "YouTube video", "Subtext": "The 11-character video id, for example sV2pXngkwR0 — not the full URL." }

Use Subtext when the label leaves a real question unanswered: a format, a consequence ("shows only when a title is set"), or a rule across fields. Do not restate the label in other words.

Placeholder and DefaultValue
Placeholder is never saved; it disappears as soon as the editor types. Use it freely wherever the expected content is not obvious from the label (an icon class, a URL pattern, an example heading). DefaultValue is saved if the editor never touches the field, so content that looks real — a dated notice, a phone number — risks shipping as stale copy on every new item. Reserve DefaultValue for values that are correct by default, such as a toggle's starting state or a sensible number, and prefer Placeholder for anything page- or date-specific.

Choose the Type for how the content is edited
• html for formatted copy — more than one paragraph, a link, a list. textarea for one plain paragraph with no formatting. Splitting one flowing passage into several textarea fields leaves the editor unable to add a link or a paragraph without a code change.
• select (or radio) for any value chosen from a known set — a layout variant, a style keyword, an icon. A select cannot be mistyped; free text can.
• textlist for a simple ordered list of short phrases. A fieldset earns its child fields only when each row really carries more than one value (a photo and its caption, a statistic and its label).

Sections that can be switched off
Give an optional section its own checkbox or toggle and put a Condition on the rest of the section's fields. The editor turns the section off without clearing every field, and the template checks the same toggle instead of inferring "off" from blank fields. Never let a condition hide a field that the visible mode still reads: a logo/text switch whose image mode uses a hidden text field for alt text leaves the editor no way to set it. Give the visible mode its own field, or read the image's own Alt.

Order, grouping, and collapsing
Keep fields in the order they appear on the page. Leave the first group open so the editor sees something immediately, and collapse the rest (Collapsed on a group, InitCollapsed on a fieldset). On a repeating fieldset, set Noun so the add button says what a row is ("Add a branch", not "Add an item").

One group per section, a fieldset for repeating rows
A group gives the editor a labelled, collapsible section and costs nothing in the template: its fields stay directly on the object, so the template reads entity.contact_phone whether or not the field sits in a group. A section partial with several fields benefits from a group named for the section ("Overview", "Contact") so the editor can find and collapse it; a section with one or two fields may not need one. Use a fieldset for rows that repeat, such as a list of branches that each carry their own values. A fieldset can also be used where the value has to be defined as an object, for example for compatibility with datastore items, though that is less common. The most common fieldset that does not repeat (AllowMultiple set to false) is a custom site setting.

Name the edit, not the position
Labels and FieldIDs such as "Copy 3" or section_text10 record where a field sat in the original design, not what the editor is changing. Name both for the content: "Accreditation summary" and accreditation_summary. Editors return to these fields months later without the design in front of them.

Where fields live affects how editors work
Prefer small partials that each own the few fields they read over one large section whose fields mix unrelated edits. Put site-wide content — logo, contact details, calls to action, social links, footer — on a single settings record that the header and footer read, not on fields repeated across page templates. Split or group to make an edit easier, not to reach a field count.