List

List fields let users pick from a set of options, shown as a dropdown, radio buttons, checkboxes, or sortable pills. This page covers the options available when editing a list field in the Field Editor.

Basic options

Field label

The text displayed beside the field when editing a record.

Database Field

The name the database and program use to refer to the field. In viewers you reference it as:

<?php echo $record['fieldname'] ?>

If you rename an existing field, update any references to it in your viewers and Database Editor settings. Some field names have special built-in behavior. See Special Fieldnames.

Field type

The type of input the field accepts. Each field type has different options. Note that the separator field type doesn’t require a field label or field name.

Help tooltip

Displays a help icon after the field label; hovering over it shows this message as a tooltip.

Visibility

Show for

Limits who can see and edit the field: Everyone, Editors and admins, Admins only, or Nobody. Users without access don’t see the field when creating, modifying, or viewing records (new records save the default value), and the field isn’t shown as a list column.

Show if

Shows or hides the field on the record edit page based on another field’s value. Pick a field, an operator, and a value. Operators are equals, does not equal, contains, starts with, and ends with (is checked / is not checked for checkbox fields). Use | between values to match any of several (e.g. draft|pending); for multi-value fields, any matching value counts.

Select Custom expression for AND conditions and multi-field rules, using =, !=, *= (contains), ^= (starts with), and $= (ends with) as operators, e.g. type=article AND status!=draft|pending. AND binds tighter than OR, field= matches empty or unchecked, and field!= matches any value.

Field options

Options specific to the field type appear in this section. For list fields you will need to set the values for your list options.

Default value

The option selected by default when creating a new record. Enter the option’s saved value, not its display label.

Existing records

Shown only when adding a new field. Check “Update all existing records with the default value above” to fill the new column for existing records; otherwise existing records get NULL.

Field prefix

Text displayed before or above the field.

Field description

Text displayed after the field.

Display as

How the list is presented:

• dropdown — a dropdown menu
• radio buttons — radio button options
• checkboxes (multi value) — checkbox options, each with its own value
• pills (multi value, sortable) — selections display as pills that can be dragged to reorder

Multi-value fields let you store multiple pieces of data in a single field.

List options

There are three ways to enter list options:

Use options listed below

The simplest method: enter your options one per line.

Tip

Use the pipe character (|) to give an option a value separate from its label, in the format option value|option label. The label is what the user sees; the value is what’s saved to the database. To include a literal pipe character, escape it by doubling it: ||.

Get options from database (advanced)

Select a database table, a field to use for values, and a field to use for labels (the two fields can be the same). This returns all the values from the specified field, useful for lists of categories or usernames. A typical categories dropdown uses the categories table with num as the value field and title (or name) as the label field, so records store the category’s record number while users see its name.

Get options from MySQL query (advanced)

For users comfortable with MySQL, enter a SELECT query. Make sure the query returns two columns.

The query can use the :: placeholder to insert the table prefix, and <?php ?> tags to insert other values. Available variables: $ESCAPED_FILTER_VALUE, $CURRENT_USER, and $RECORD.

An advanced filter, “Refresh list when this field changes”, reloads the options whenever another field in the record changes. Insert that field’s escaped value into the query like this:

<?php echo $ESCAPED_FILTER_VALUE ?>

Validation

Required

Requires the user to enter a value for the field, showing an error if the field is left blank.

Unique

Requires the user to enter a unique value for the field, showing an error if another record has the same value.

Advanced options

System field

System fields cannot be edited and have no modify or erase link unless “System Field Editing” is enabled (under Advanced Commands on the field list page). This prevents accidental changes to fields the program relies on.

MySQL column type

The MySQL column type used to store the field. Auto (the default) picks a type appropriate to the field type; you can also choose from preset text/string, numeric, and date/time types, or enter a custom column type.

MySQL indexing

Creates a MySQL column index for the field, which speeds up sorting and some searches but slows down adding and saving records.

Data encryption

Automatically encrypts data stored in the column. Requires a database encryption key (set on the Security settings page) and the MySQL general query log to be disabled; enabling encryption also sets the column type, which can’t be changed while encryption is on. Back up the database before encrypting, and back up the encryption key. Without it the data is unrecoverable.

In viewers

Single-value lists (dropdowns and radio buttons) store the selected option’s value, so $record['fieldname'] holds that value directly. Multi-value lists (checkboxes and pills) store all selected values in one tab-separated string; display them with the array pseudo-fields instead:

<?php echo $record['region'] ?>
<?php echo join(', ', $record['cities:labels']); ?>

Pseudo-fields

fieldname:label

Single-value lists: the display label for the stored value. The label is resolved for all three options sources (hand-typed options, options from a database table, and options from a MySQL query), so a category dropdown storing record numbers displays the category name with <?php echo $record['categoryNum:label'] ?>.

fieldname:values

Multi-value lists: array of the selected values.

fieldname:labels

Multi-value lists: array of the display labels for the selected values.

Pseudo-fields can be turned off with the loadPseudoFields viewer option. See the Pseudo-field Reference.