Upload Field

Upload fields let users attach files and images to a record. This page covers the options available when editing an upload field in the Field Editor. See Displaying Uploads for how to show uploads in your viewers.

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, 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

Field prefix

Text displayed before or above the field.

Field description

Text displayed after the field.

Validation

Required

Requires the user to upload at least one file, showing an error if the field is left blank.

Uploads

Upload order

Whether new uploads are added to the top or bottom of the upload list. To re-order existing uploads, drag them in the record editor.

File extensions allowed

A comma-separated list of file types (by extension) that can be uploaded. Users uploading a file with an extension not on the list get an error message.

Maximum uploads

The maximum number of uploads allowed for the field. Uploading past the limit triggers an error; removing earlier uploads makes room for new ones. Leave unchecked to allow unlimited uploads, or set to 0 to allow none.

Maximum upload size

The maximum file size allowed per upload. Leave unchecked to allow any size.

Resize images larger than

When enabled, uploaded images larger than the specified dimensions are automatically resized down to fit. The width and height define a maximum bounding box: larger images are scaled down proportionally until they fit inside it, and smaller images are left untouched (never scaled up).

Create thumbnail

When enabled, a smaller thumbnail is automatically generated for each uploaded image. Up to four thumbnail sizes can be configured (“Create thumbnail” through “Create thumbnail (4)”), each with its own dimensions, a crop option, and a recreate link for regenerating existing thumbnails. Each size is available in viewers via thumbUrlPath through thumbUrlPath4.

The width and height (both required, default 150×150) define a maximum bounding box: images are scaled down proportionally to fit inside it, so thumbnails keep their aspect ratio and only one dimension usually matches the setting exactly. Images already smaller than the box are copied unscaled. To constrain only one dimension, such as thumbnails 300px wide at any height, set the other dimension to a value larger than any image you expect.

With crop checked, larger images are instead scaled until one side matches the thumbnail size, then the excess is cropped from the center, producing the exact width and height configured. Images smaller than the box are cropped without scaling up.

Upload fields

Upload fields store additional text for each uploaded file, such as titles, captions, or alt text. Five fields (info1 through info5) are available, each with its own label, input type (text field or text box), and required option. They’re displayed on the upload form and referenced in viewers as:

<?php echo $upload['info1'] ?>

Upload directory

By default files are stored under the program’s uploads/ folder. Checking “Use custom upload directory” reveals Directory Path and Folder URL inputs for storing this field’s uploads and thumbnails in a custom location.

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.

Media Library

When the Media Library is enabled, a Select from media library link will be added to upload fields, which enable inserting a file from the media library into that field.

Files uploaded directly to an upload field belong only to that field, and will not be added to the media library.

In viewers

With the loadUploads viewer option on (the default), $record['fieldname'] is an array of upload rows, each carrying the file’s URL, dimensions, thumbnails, and info fields. Viewers loop over them:

<?php foreach ($record['photos'] as $upload): ?>
  <?php echo $upload['urlPath'] ?>
<?php endforeach ?>

See Displaying Uploads for the full list of upload attributes and thumbnail examples.