Who this is for. Content modellers setting rules and defaults, and developers who rely on them in templates. After this page you know which rule lives where, what the author sees when it fails, and why changing a default changes pages nobody edited.
When the checks run
Every rule below is checked when a record is saved, whether from the admin or through the API, and a failure stops the save with a message against the field. The messages are fixed and in English, and they name the rule rather than the field, so pair every rule with help text that says it ("Add one to three slides").
Rules on the input type
| Rule (admin label) | Checked for these editors | Message on failure |
|---|---|---|
| Regular Expression | Text, textarea, number | This value is not valid. |
| Max. length (Max. digits for a number) | Text, textarea, richtext, number | This value exceeds the maximum length of 50 characters |
| Built in: a number with no regular expression of its own must be a whole number of zero or more | Number | This value is not valid. |
| Built in: a select's key, or every key of a multiselect, must be one of its options | Select, multiselect | This value is not valid. |
Built in: a switch is 1 or 0; a colour is #rrggbb, #rrggbbaa, rgb() or rgba() | Switch, colour | This value is not valid. |
- A rule on an input type applies everywhere the type is used, on every layout area and every custom field built on it. For a rule that belongs to one field only, create a separate type.
- The maximum length counts bytes, not characters: an accented letter counts as two, and in rich text every tag counts too.
- A pattern written without delimiters is wrapped in
/…/; one that starts and ends with the same delimiter is used as it is. The form's help asks for special characters such as+and.to be escaped twice (\\+,\\.). - An email area is checked by the browser on the form, not on save, so the API can store any text in it.
Rules on the layout area
| Rule (admin label) | Applies to | Message on failure |
|---|---|---|
| Required | Any area | This value is required |
| # Min. components | Collection areas only | At least 1 occurrences required, but only 0 provided |
| # Max. components | Collection areas only | Maximum 3 occurrences allowed, but 4 provided |
An empty minimum or maximum, or 0, means no limit. These are the rules every layout gets without any input type configuration, and the minimum and maximum are what make a collection safe to design for: a carousel that needs two to six slides can say so.
Default content
Both an input type and a layout area have a Default. When an area has no content of its own in the record's active revision, every getter and the shorthand return the layout area's default if it has one, otherwise the input type's. Three consequences:
- The default is applied when the page renders, not when the record is created. Nothing is copied into the record, so changing a default changes every record that never filled the area in, at once.
- The author sees the default as a hint, the placeholder of an empty text field. A switch is the exception: with a default of on, the switch starts switched on, and saving the record stores that.
- A template cannot tell a default from an entered value through the ordinary getters. When it must, compare with the raw content, which is empty when the author left the field alone: see Introspection, raw content and attributes.
Use defaults to make an unfinished page look intentional: a standard section background on a style select, a stock image on a hero, a sensible button label. Set them on the layout area when they belong to one layout, and on the input type only when every use of the type should share them. A new select option can be chosen as the input type's default only after the type has been saved once with it.