Where Custom Fields Belong

Custom fields extend a template with values an editor fills in. When a page template composes partial templates, each field has to belong somewhere. The rule is worth being deliberate about: the template that reads a FieldID is the template that should define it.

A partial that renders a hero banner defines the fields the hero needs. A partial that renders a call to action defines its own. The page template defines only the fields it reads directly, which is often none when the page is a thin composition of partials.

When a page includes a partial, that partial’s fields are composed onto the editing form for pages built from the page template. An editor filling in a page sees one form, assembled from every template involved in rendering it. Ownership decides where a field is defined; composition decides where the editor sees it.

Keeping a field with the template that reads it is what makes a partial reusable. Include that partial from another page template and its fields travel with it, with nothing to copy and nothing to keep in sync. Define the same field on the page template instead and the partial depends on a value it does not own, which then has to be recreated on every page template that includes it.

FieldIDs must be unique across the templates composed for one page, so name them for the partial’s own purpose rather than for the page it happens to appear on. A fieldset is a separate scope: its child FieldIDs only need to be unique inside that fieldset. When two templates in one composition define the same FieldID, that collision is an error to fix in the definitions themselves.

For what those values look like when a template reads them, see Field Values. For template types and how they compose, see Template.

For every Type, Condition, and Validator a field definition can use, see Custom Fields.