Field Types
Every field has a type. The type decides how input is validated and sanitized, how the
value is stored, and what cafe_get_field() returns.
| Category | Type | Name | Returns |
|---|---|---|---|
| Basic | Text | text |
string |
| Basic | Textarea | textarea |
string with \n |
| Content | Rich Text Editor | rich_text |
HTML string |
| Basic | email |
string |
|
| Basic | URL | url |
string |
| Basic | Link | link |
array (url, title, target) or URL |
| Basic | Password | password |
string (sensitive) |
| Basic | Color | color |
hex string, rgb() or array |
| Numeric | Number | number |
int / float |
| Numeric | Range | range |
int / float |
| Choice | Select | select |
value, label or pair (list when multiple) |
| Choice | Radio Buttons | radio |
value, label or pair |
| Choice | Button Group | button_group |
value, label or pair |
| Choice | Checkbox | checkbox |
list |
| Choice | Toggle | toggle |
bool |
| Date & time | Date | date |
formatted string |
| Date & time | Time | time |
formatted string |
| Date & time | Date and Time | date_time |
formatted string (site time) |
| Media | Image | image |
image array, ID or URL |
| Media | Gallery | gallery |
list of images |
| Media | File | file |
file array, ID or URL |
| Media | Video | video |
video array or URL |
| Media | oEmbed | oembed |
embed HTML, URL or array |
| Relationship | Post Object | post_object |
WP_Post / ID (list when multiple) |
| Relationship | Relationship | relationship |
list of WP_Post / IDs |
| Relationship | Page Link | page_link |
URL (list when multiple) |
| Relationship | Taxonomy | taxonomy |
WP_Term / ID (list when multiple) |
| Relationship | User | user |
user array, WP_User or ID |
| Layout | Message | message |
null |
| Layout | Clone | clone |
array by sub-field name |
| Advanced | Google Map | google_map |
array (address, lat, lng, zoom) |
Layout fields (Tab, Collapsible Section, Field Set, Collection, Section Builder) are listed below; relationship fields are listed above. You can add your own types: see Custom field types.
Empty values and defaults
CAFE distinguishes three situations:
| Situation | cafe_has_field() |
cafe_get_field() returns |
|---|---|---|
| Field does not exist (unknown name or key) | false |
the $default_value argument, or null |
| No stored value | false |
the $default_value argument if given, else the field's Default Value setting, else null |
| Stored value | true |
the stored value, formatted |
Saving an empty value ('', null, []) removes the stored value, so afterwards the
field is back in the "no stored value" situation. There is no separate "stored empty value".
Exceptions, where the value is real data and is stored: 0 (Number, Range) and false (Toggle).
The precedence is stored value → $default_value argument → field default. The argument
comes first so that code can always override the configured default at the call site:
cafe_get_field( 'subtitle', $post_id, null, '' ); // '' when nothing is saved, ignoring the field default
cafe_get_field( 'subtitle', $post_id ); // field default when nothing is saved
The $default_value argument is returned exactly as given (no formatting or filters);
a field's own default goes through formatting and the value filters like a stored value.
Settings are validated
Every setting is declared by the field type (label, description, type, default, constraints). When a field is saved:
- unknown settings are rejected (
cafe_unsupported_setting); - wrongly typed or out-of-range settings are rejected (
cafe_invalid_setting); - required settings (e.g. choices) must be present (
cafe_missing_setting); - cross-checks run (minimum ≤ maximum, step > 0, choices unique, image size exists);
- the default value must itself be a valid value (
cafe_invalid_default_value).
Names, keys and identity
| Identifier | Rules | Purpose |
|---|---|---|
| Field name | letters, digits, _; starts with a letter or _; max 64 |
What you use in code: cafe_get_field( 'hero_title' ). Unique among siblings. |
| Field key | lowercase letters, digits, _; max 64; generated as field_… if omitted |
Stable identity across sites and exports. Unique across all groups. |
| Group key | lowercase letters, digits, _; max 64; generated as group_… if omitted |
Stable identity of the group. |
Values are linked to the field's internal ID, never to its label or name, so renaming a label or a name keeps every saved value. Database IDs are never the public identity; use names in templates and keys in exports.
Layout fields
| Type | Name |
|---|---|
| Tab | tab |
| Collapsible Section | collapsible |
| Field Set | fieldset |
| Collection | collection |
| Section Builder | section_builder |
| Section | section |
Read Collections and Section Builders with cafe_rows().