Field settings: general, validation and SQL column

Last updated Oct 3, 20267 min read

Click Advanced options on a field row to open its settings panel. It has five tabs:

Tab	What it holds	Documented in
Type settings	Settings of the chosen type (choices, return format, ...).	Field types
General	Default value, placeholder, instructions, width.	this page
Validation	Required, index, unique, validation rules, SQL column.	this page
Display	Wrapper class and id, prefix, suffix, admin column, translation mode.	Field settings: display and advanced
Conditional logic	Show or hide the field depending on other fields.	Conditional logic

Layout fields (Tab, Accordion) store nothing, so most of these options do not apply to them.

General tab

Setting	Default	Effect
Default value	empty	The value an edit screen shows for an object that has no stored value yet; a plain default is also the column's SQL `DEFAULT`. A default containing `{{ }}` is evaluated per object on the edit screen and is not stored as the SQL default. It is stored when the object is saved. It never changes values that already exist. Dates must be `YYYY-MM-DD`, times `HH:MM:SS`, otherwise saving fails with `Field "x": the default value does not fit this field type`. Disabled while a SQL function is set.
Placeholder	empty	The grey hint inside an empty input. It is never stored. `{{ }}` expressions in it are evaluated when the screen loads (for example `{{ sys.year }}` shows the current year).
Instructions	empty	Help text shown to editors with the field. Where it appears depends on the group's Instruction placement (Below labels or Below fields). Plain text only.
Width	Full width	How much of the row the field takes on the edit screen: Full width, Three quarters, Two thirds, Half, One third or One quarter. Fields sit side by side until a row is full. Other values are ignored; full width is not stored.

Validation tab

The tab has three parts and a summary line.

Constraints

Setting	Default	Effect
Required	off	The editor must fill the field in. The edit screen marks it with `*`; the column becomes `NOT NULL`. See Required fields below.
Add index	off	Adds a regular index on the column so queries that filter or sort by it are fast. Not available for fields stored as JSON (checkbox lists, relationships, groups, repeaters, ...).
Unique	off	Adds a `UNIQUE` index: no two rows may hold the same value. Turning it on also turns on Add index. See the warning below.
Prefix length	`191` for text types	Shown for text types that use a prefix index. Only the first N characters are indexed (1 to 3072). A shorter prefix is a smaller index with less coverage. Types with a numeric or date column index the whole value.

Add index and Unique are not offered for sub-fields inside a Group or Repeater (they are not real columns).

Index names are idx_{key} and uq_{key}. A Map field indexes its latitude and longitude columns together.

Limits: from 8 indexed fields in one group a warning appears (Many indexes slow down writes); above 20 the group cannot be saved. Only index fields you actually filter or sort by.

Validation rules

Which rules you get depends on the type:

Field types	Rules
Text-like (Text, Text area, Email, URL, Password, ...)	Min length and Max length (in characters).
Numeric (Number, Range)	Min value, Max value, Step (for example `0.5`, `1`, `10`).
Choice, relational, date/time, JSON and container types	No extra rules. The panel says `No extra validation rules available for the <type> type.`

How the rules are enforced:

Rule	In the browser	On save (server)
Max length	`maxlength` on the input	Longer text is cut to the length (no error).
Min length	`minlength` on the input	Not enforced on the server (the Password type does enforce its minimum).
Min value / Max value	`min` / `max` on the input	The number is clamped into the range.
Step	`step` on the input	Not enforced on the server.

So the rules protect normal editing but not API writes of wpmcf_update_field() (which runs the type's own sanitizing). If you allow negative numbers, make sure the SQL column is not Unsigned.

Required fields

Where	Behavior
Classic forms (user, term, comment, widget, classic post editor)	The browser blocks submit and the field shows `This field is required.` Picker, WYSIWYG and color fields that cannot carry a native `required` are checked by the plugin's script.
Block editor (posts)	Saving is locked and the notice `Fill in the required fields before saving: {labels}.` appears until the fields are filled.
Server	A save is never rejected. If a required field is still empty (for example the value came from the API), the values are saved and the next screen shows `Saved, but these required fields are empty: {labels}.`
Fields hidden by conditional logic	Never required.
Group, Repeater, Flexible content	Required means at least one row (or one filled sub-field for a Group). A required sub-field is checked inside each row.

Making an existing field required changes its column to NOT NULL. Existing empty (NULL) values are first replaced by the field's default, '' for text or 0 for numbers, so the change does not fail. Date and time columns stay nullable.

SQL column

A collapsible block, normally left closed (Override the physical column type and charset when needed. Most sites can keep this closed.). It is hidden for fields stored as JSON, and sub-fields only get the options that make sense inside a JSON value.

Setting	Default	Effect
Column type	the type's own (for example `VARCHAR(255)` for Text, `DECIMAL(20,6)` for Number)	Replace it with another SQL type the field type allows, with a length or precision where relevant (for example `VARCHAR(100)`, `DECIMAL(10,2)`, `TINYINT`). The list only offers compatible types. For utf8mb4, keep `VARCHAR` length at about 16,383 or below.
Numeric › Unsigned	off	`Non-negative only`: the column cannot hold negative numbers.
Encoding	the site's charset and collation	Pick a preset charset, or Custom... and type a Charset (`utf8mb4`) and Collation (`utf8mb4_unicode_ci`). Text columns only.
Function	None	Computes the stored value, see below.

Column functions:

Function	What it stores	Requirements
None	what the editor submits
Current timestamp	The database sets `DEFAULT CURRENT_TIMESTAMP`.	A `DATETIME` or `TIMESTAMP` column.
MD5 (on save)	32-character MD5 hex of the submitted value.	`VARCHAR`/`CHAR` of at least 32.
UUID	A 36-character UUID. MySQL 8.0.13+ can default it in the database; otherwise it is filled when saving an empty value.	`VARCHAR`/`CHAR` of at least 36, not `TEXT`.
SHA1 (on save)	40-character SHA-1 hex digest.	`VARCHAR`/`CHAR` of at least 40, or a `TEXT` type.
UPPER (on save), LOWER (on save)	The text in upper or lower case (UTF-8 aware).	A text column; not for Email or URL fields.
ABS (on save)	The absolute value of the number.	A numeric column.
RAND (on save)	A random number between 0 and 1 when the value is empty.	A numeric column.

While a function is active, Default value, Prefix and Suffix are disabled, because the function decides the stored value. Functions are not available inside Group or Repeater sub-fields. The save is rejected with a message such as Field "x": UUID requires VARCHAR(n) or CHAR(n) with n ≥ 36 (not TEXT). when the column type does not fit.

Column summary

At the bottom, a line such as Column: price NOT NULL INDEX shows what the column will look like: its name, NOT NULL for required fields, and INDEX, INDEX (191) (prefix) or UNIQUE INDEX.

Changing these settings on a saved field

Changing the default, Required, the column type, charset, collation, function or unique flag alters the column (MODIFY COLUMN). Index changes add or drop an index. Both happen safely: if the database rejects the change (for example a new Unique index on a column that already has duplicates) everything is rolled back and nothing is saved. See Changing a field group safely.

Troubleshooting

Problem	Cause and fix
Saving a new Unique index fails	The column already holds duplicate values. Remove the duplicates, then save again.
`BLOB/TEXT column 'x' used in key specification without a key length`	An index on a `TEXT` column needs a prefix length. In the editor, switching to a type that cannot be indexed clears the index; through the REST API send `"indexed": false` too.
My validation rule did not stop a bad value	Min length and Step are browser checks only; Max length and Min/Max value are enforced by cutting or clamping.

Was this page helpful?

Still stuck? Contact support