Field Types

Participants Database provides a variety of different field types (known as the field’s “Form Element”) that you can use in your forms and displays. Each one has specific ways of displaying and storing data. It is also possible for other plugins to define new field types.

The form element type is determined in the field definition, which is configured on the Manage Database Fields page. When a new field is created, the type is selected at that time, but you can change the form element in the field definition at any time.

Bear in mind that the field type determines how the data is stored in the database, so it is possible to lose data when changing the form element type. It is best to avoid changing the form element type of a field once it has started storing data. You will be warned if you try it.

Form Element Type Descriptions and Usage Notes

Text Line

Simple text field, limited to 255 characters.

Text Area

A simple text box with a character limit of 65,000.

Rich Text

This presents a text editor box like the “classic editor” used to edit content in WordPress pages and posts. The rich text editor will only be shown on the frontend if allowed in the settings (the “Use Rich Text Editor” setting under the Advanced tab).

Example of setting the
editor height to 30 rows

You can set the height of the editor using the “rows” attribute in the field definition. Each row is (approximately) one line of text. The default is 20, so at that height, ther user will be able to type in about 20 lines of text without scrolling. For the best UI, set this to a height that will accommodate the amount of text most users will be typing in for the field you are creating.

If you are having problems with the display of this field, Check the “Use WP auto format” setting (also under the plugin settings advanced tab), which determines how the content of the rich text field will be processed before display.

The default is to use the “the_content” filter, which is the global filter used by all WordPress posts and will provide auto paragraphs and process shortcodes. You can use this setting to control how WordPress and other plugins affect the rich text content. The “the_content” filter is commonly used by other plugins that alter or add content, so there may be some unintended effects. To prevent other plugins from altering the displayed content of the field, try using the “auto-paragraphs + shortcodes” setting.

Date Field

This is a field specifically for date values. Dates entered as text will be converted to a UNIX timestamp for storage. You must use this field type for dates if you want date searches and sorts to work correctly.

To set an initial date value, set the “Default” to a dynamic date key like “current_date.”

Date fields can have their UI enhanced with the Datepicker Add-On.

Checkbox

A single checkbox that may have one or two values, the second value represents the “unchecked” value for the field. If there is no second value defined, the “unchecked” value will be saved as an empty string.

You can use the option to label the checkbox. With the setting shown here, the word “yes” will be stored if the checkbox is checked, “no” if it is unchecked.

This field type uses the Options attribute to define its values.

Radio Buttons

For showing several choices, only one of which may be selected. This is better UI than a dropdown for a small number of choices because all the choices are visible.

This field type uses the Options attribute to define its options.

Radio Buttons/Other

Shows radio buttons with the addition of an “other” button and text input.

This field type uses the Options attribute to define its options.

This is the familiar dropdown selector control, allowing only one item to be selected at a time. This is better for long lists of options.

This field type uses the Options attribute to define its options.

Dropdowns can have their UI enhanced with the use of the Chosen Selector add-on. This is especially helpful for very long lists of options.

This is a special type of dropdown that presents a text field when “other” is selected, allowing for a write-in choice.

This field type uses the Options attribute to define its options.

Multiselect Checkbox

This presents a multiple-choice series of checkboxes, any number of which may be selected. This form element is not well suited to a large number of options, try Multiselect/Other for that. For an even better UI for a large number of options, try the Chosen Selector add-on.

This field type uses the Options attribute to define its options.

Multiselect/Other

Like the Multiselect Checkbox, several choices can be made, plus a write-in choice. Not good for large numbers of choices, the Chosen Selector add-on is much better for that.

Note that only a single “other” value can be stored per record for a multiselect/other field.

This field type uses the Options attribute to define its options.

This is a special field for defining a link on clickable text. It shows two text inputs which allows the link text to be defined along with the URL. If only the URL is provided, the link text will be the URL.

The provided example will display like this:
xnau webdesign

Image Upload Field

This provides an upload field for an image file. The allowed types and maximum file size are determined in the plugin settings (General Settings tab, “File Upload Limit” and “Allowed File Types”).

Setting the allowed file types for an individual field.

You can also set the allowed types on a per-field basis by adding an “allowed” attribute, separating the allowed file extensions with the pipe character.

As shown, you can also use the “maxsize” attribute to limit the file size. The number represents the number of kilobytes…so 400 means 400k.

Note that limiting the file types is not a security feature, the files are not tested to make sure they really are the right type, it only looks at the filename extension.

All plugin uploads will be stored in the location designated by the “File Upload Location” setting. In almost all cases, the default setting is a good one to use. Only change this if you know what you’re doing and know where your files will end up. If you change this after files have been uploaded, the plugin will no longer be able to find them unless you move the files to the new location.

Enhanced image upload capabilities are available using the Image Expansion Kit add-on. This add-on is highly recommended if your application gets lots of uploads from users, as it gives you better ways to manage uploaded files.

File Upload Field

This provides a general file upload control. Any file type appearing in the “Allowed File Types” setting (under the General tab) will be accepted as long as it is under the maximum file size. The accepted file types and maximum file size may also be defined on a per-field basis as described in the Image Upload Field above.

While the standard security precautions are taken with these uploads, if you’re site is not configured correctly, this could lead to a serious vulnerability if malicious files are uploaded to your website where they can be executed.

Hidden Field

This is generally used to store system information not requiring user input, such as an IP number or user name. It can also be used as a way to add a fixed value to a record, or as a convenient way to allow client-side javascript to add a value to the submission. The values stored in hidden fields can be shown only as “read only” values on the frontend.

Hidden field configured to capture the name of the page the form is on.

The hidden field has the ability to acquire system values to be saved with the form submission. There are many possibilities, but a simple, commonly used example is collecting the name of the page the signup form is on. This is done by creating the hidden field, assigning it to the signup form, then typing in the code for the value you want to collect. To get the page name, you would use post->post_name in the “Default” setting for the field. When the form is displayed, the name of the page will be filled in to the hidden field and saved with the signup submission.

The objects you can access this way are:

  • post (information about the current page or post)
  • current_user (information about the current logged-in user)
  • SERVER (information about the current state of the web server)
  • other php superglobals

More information on configuring hidden fields can be found here.

Numeric

Good for storing numbers, integers only. If you want a field with numeric content to be sorted numerically, you must use a numeric field of some kind (there are 3 available). You cannot store non-numeric data in a numeric field.

You can set up limits and step values in the field attributes, like this:

This example sets the field parameters so the maximum value is 100, the minimum is 0 (no negative numbers allowed), and each click on the increment control will move the value by 5.

Decimal

Allows for numbers with decimals, defaults to 10 places on the left of the point, and 4 to the right. Also uses the same configuration attributes as in the numeric field.

The “step” attribute can be used to change the number of decimal places shown. For example step::.001 will give you 3 decimal places, step::.1 will give you one.

Currency

Allows for numbers with two decimal places, like most currency values. Currency symbols are not allowed, only the numeric part is stored. Uses the same configuration values as in the numeric field. You can define a currency symbol to be displayed with the number using the “data-before” attribute. For example:

This places a US Dollar sign before the number, limits the increment to one cent, and sets the maximum value of the field to 10,000. Negative values are not allowed.

There is also a “data-after” attribute you can use if you need the symbol to appear to the right of the number.

Password

This is a special-use field for developers so that a hashed password can be stored with the record. The Participant Login add-on can be configured to use a password field to create a secure way for the user to edit their record by entering a password instead of using a private link.

Note that with this field, you will never be able to see what the password is…that’s the whole point of hashing, it makes it difficult to steal the password, all the hacker will get is an indecipherable string.

CAPTCHA

This provides a simple way to include a human test for your form submissions. There is only one type of CAPTCHA provided with the plugin: one that asks the user to solve a simple randomly-generated arithmetic problem.

A CAPCHA field cannot prevent all spam registrations, human-powerd spam cannot be blocked this way, but it is essential for limiting script-driven registrations.

For more robust bot registration prevention, check out the reCaptcha Add-On.

Placeholder

The placeholder field is mainly used to provide a clickable link in list displays. It is a utility field and does not save anything to the database. The Placeholder field can only be created by using the “Add Field” control on the Manage Database Fields page, it is not possible to convert an existing field to a Placeholder field.

The “Display” setting for the field is the content that is displayed. If the field has a link placed on it (for example if it is designated as the “single record link field”) the content will be clickable.

Some simple HTML is allowed in here. For example, to show a Dashicons icon, you can use a value like this:

This will show the “cog” icon as a clickable element.

Placeholder fields are also useful for placing other links in lists of records when using a custom template, such as adding a link to edit a record, as described in this tutorial: Adding a Record Edit Link to the List Display.

Heading

This is a utility field you can use the help make your forms more readable. All it does is print a block of HTML-formatted text, so you can use it to explain things, or help organize the form (in addition to possibly using Field Group Tabs).

The Heading field is a utility field and does not save anything to the database. It can only be created by using the “Add Field” control on the Manage Database Fields page, it is not possible to convert an existing field to a Heading field.

This field simply displays the content of the “Heading” attribute of the field definition. For example:

This field type does not present your users with a place to type something in, you would probably use a “Rich Text” field for that.

Media Embed

This form element shows an embedded video or other hosted media, using WordPress’ built-in media embedder. The value of the field must be the full URL to the media itself. The linked article explains this in detail and provides a list of supported sources, it’s really worth reading to understand how this field works.

This field type can also simply display an externally-hosted image. If the the value of the field is the absolute URL to an image file, it will display the image.

Regex validation to only allow a Vimeo or YouTube embed

It is suggested that you explain to your users exactly what is expected. If you want to restrict the input to particular source or set of sources, you can use a regex validator to enforce a URL from a specific host or hosts, file type, etc. You will need to understand how to use regular expressions to use this feature.

String Combine

This is a form element that displays a combination of values from the record. To set this up, the field definition uses a “Template” that determines which values are used to make up the displayed string.

The classic example of this is a field that combines the first and last names into a single field. For that, you can use a template like this:

Which results in an inverted order name like this: “Barker, Roland.” The way this works is like other text templates in Participants Database, the bracketed “value tags” are replaced by the record’s value of the same name. If the value is missing or blank in the record, the value tag is removed from the display.

The resulting string is also saved to the database, so it can be used in search and sort procedures.

It is possible to define a default value for the field, which is displayed if all the fields in the template are blank. This is done in the field Attributes with a setting such as this: default::no name

Shortcode Field

This field type is for displaying any shortcode. To configure the field, place the shortcode to be displayed in the “Shortcode” setting for the the field. To insert the field’s value into the shortcode, use the “%s” token.

This example creates a field that will show an audio player for the linked mp3 audio file using the built-in WordPress audio shortcode. The field stores the URL to the audio file, which must be publicly hosted on a server, and displays a player for the audio. You can use a “regex” validation to enforce a specific file type.

You can also use it to place “wrapped” content, for example:

There are two options you can enable for this field type: “preview” which affects how the field is displayed when editing the record. If “preview” is set as an attribute in the field definition, the field will show a preview of the shortcode’s display. The “show_value” option is applied when the record is getting displayed using the single record display. When “show_value” is set as a field attribute, the URL will be displayed along with the shortcode’s display.

You can potentially put any shortcode in here, but shortcodes that generate formatted output may not fit into the display correctly. Shortcodes that have big, complex outputs may not work well or at all. It’s not really meant for that, but you can try it. Using a Custom Template can help if this is what you want to do.

What if the display shows nothing? If the shortcode does not get processed, the field will display a blank (instead of showing the broken shortcode). This can be because the plugin that adds the shortcode is disabled, or there is some kind of syntax error in the shortcode setting for the field. Make sure you understand how the shortcode works and what it expects for the dynamic value. If inserting the field’s value into the shortcode causes a syntax error, it could result in the field displaying nothing. A good example of that is if the field’s value contains a double quote, that will often result in a syntax error.