- Field Group Tabs
- Field Definitions
- Selecting Fields and “With Selected” Actions
- Editing a Field
- Adding a New Field
- Field Groups
- Form Element Types
Note: This page is for Participants Database version 1.9.0 and later; instructions for using the pre-1.9.0 version are here…
The Manage Database Fields Interface
This is where all your database fields are defined. Each piece of information stored in the database is stored in a “field,” and there are many different kinds of fields (called form element types) that are used to store information in various ways. The different form elements present specific user controls such as text fields, dropdowns, radio buttons, etc.
This page explains how to use the Manage Database Fields interface to add, configure or delete your database fields.
Field Group Tabs
At the top of the page is a series of tabs. Participants Database fields are organized into groups, and each tab (except the last two) represents a group of fields.
The last two tabs provide access to edit field groups and provide a quick help page.
Below the field group tabs is the list of fields defined for the currently selected group as shown in the screenshot above. Each line represents one field, and in this view, the fields can be re-ordered, deleted, and selected.
Open/Close the Field Editor
At the far left of each field there is a chevron iconto open and close the field editor. When the field editor is open, all the parameters of that field may be edited. Closing the editor gives you a simple, compact display. At the top is the “Open/Close All” button…click that to set all the fields to open or closed.
You can change the order of the fields by click-dragging the blue “up-down” icon and moving the field into a new position.
Individual fields can be deleted by clicking the red for the field you want to delete. Multiple fields can be deleted at one time by selecting the fields you want deleted and using the “with selected” action to delete the fields.
Selecting Fields and “With Selected” Actions
Each field has a checkbox on the left where fields can be selected to perform operations on multiple fields.
When one or more fields are edited, the “with selected” control is visible so the operation can be selected. Click “Apply” to perform the operation.
Operations available in the core plugin:
- Assign Group
- Add/Remove Signup
- Add/Remove CSV
Editing a Field
With the field editor open, the parameters of the field can be edited. (shown in the screenshot above) The parameters that are available for any field depend on the “Form Element” type for that field.
Please Note: for administrators familiar with the pre-1.8.5 version Manage Database Fields interface, the “Values” parameter has been split into two parameters: Options and Attributes. In the old system, the Values parameter was filling two different roles. To make it more clear how it works, and to make it possible to add attributes to form elements with options, the former Values parameter was split into two different parameters. The Options parameter is only available for fields that use options. The Attributes parameter is available for all fields.
Field Parameter Descriptions
- Name – this is set when the field is created and can’t be changed. This name is used for all configuration references (such as shortcode attributes) to the field.
- Title – This is the label for the field, and can be changed at any time. It is what will be shown to the user.
- Group – every field belongs to a group. You can change which group a field belongs to by changing this parameter. You should update the fields after changing this so that the field can be moved to the new group.
- Form Element – this is the form element type of the field: it determines what element is used to represent the field in a form, how the data is stored in the database, and can also determine other functionality for the field. If you change a field’s Form Element, you should update the fields before making any more changes to the field.
- Options – for form elements that need a list of options, this parameter provides the place to define all your options. Take a look at the Field Options section for details. This was known as “Values” in pre-1.8.5 versions of the plugin.
- Attributes – this provides a space to set custom HTML attributes for the field. There are many possibilities here, this is an advanced feature and you will have to know something about how the HTML works to use this. There are many examples in the instructions and tutorials. This parameter was known as “Values” in versions older than 1.8.5.
- Validation – this setting determines whether the field is required and can also determine what inputs are acceptable for the field.
- Validation Message – provides the custom message that is shown if the field does not validate. If this is blank, a generic message will be shown.
- Default Value – if the field is supposed to be pre-set with a value, set that here. If the field is one that has options, this should be the option value, not the value title.
- Help Text – when used in a form, this is text that is shown next to the field to provide user help specifically for that field.
- Signup – when checked, the field is to be included in the signup form.
- CSV – when checked, the field’s data is to be included in a CSV export. Has no effect on CSV imports.
- Read Only – when checked, the field can only be changed by an administrator. Read-only fields are always editable in the Signup form.
- Sortable – the field is available in list sorting controls.
- Persistent – the field’s value will be carried over from the previous record when editing or creating a series of records in the admin.
Changing the Form Element of the Field
The Form Element setting determines how the field will be displayed in a form and how the data is stored in the database. The form element types that are provided with Participants Database are described here…
After changing the form element parameter of a field, you should update the fields (blue button marked “Update Fields”) so the display can show the correct parameters.
Generally speaking, it is best to avoid changing the form element of a field once data has been collected. You will be warned if you try it, and you should understand the impact on the stored data: it is possible to lose data stored in a field if you change its form element. This is explained in detail here…
Certain kinds of fields require a defined list of values (known as options) for the user to choose from. This includes dropdown selectors, radio buttons, checkboxes, etc.
Field options are defined in the “Options” setting with a comma-separated list of values.
For example if you had a “State” selector, putting
AL, ME, AZ, NM, CA in the Options parameter would give the user a choice of those five US states.
It’s also possible to use labels (or “value titles”) for your options. To do that, set your options like this:
Alabama::AL, Maine::ME, Arizona::AZ, New Mexico::NM, California::CA
For each pair, the first string is used to display the value to the user, while the second is what will actually be stored in the database. Note that spaces are allowed, but leading and trailing spaces will be removed. You can also put simple HTML tags in your value titles.
The value title is also filtered for translation, so that you can show your values in different languages, while the value that is saved will be the same for all languages.
Checkboxes only need one value, which is what will be saved if the box is checked. If the box is unchecked, nothing will be stored in the field value.
If there are two values, the second value will be saved if the box is unchecked. For example:
Yes,No will save “No” if the checkbox is not checked.
For really long lists of values, it is possible to group them by adding a group title which can be added using a label with a value of “optgroup.” Here is an example of a list of options that are organized with optgroups:
Eastern States::optgroup,Alabama::AL,Maine::ME, Western States::optgroup,Arizona::AZ,New Mexico::NM,California::CA
This can help the user find the option when there is a lot to choose from. Each group is wrapped in an HTML element so that it can be styled as a group.
The “Nothing Selected” Option
It’s also possible to define the “nothing selected” option. This is an option that essentially clears the value of the field. It is also used as a prompt that is shown by default, but does not save a value if the record is saved like that.
To set that up, put something like
null_select::Choose… at the beginning of the list of options. It must have the “null_select::” part, the part following the :: is what will be shown in the selector and that can be anything you want. If the field is required, the null select will not validate, forcing the user to make a real selection.
In some cases, you may want to prevent the null select option, which you can do with
Determining the Default Option Selection
If there is a “default” setting for the field, that will determine which option is selected by default. You need to the data value in there, don’t use the value title.
If there is no default defined, but a “null select” has been defined, the null select will be selected by default.
If neither a “null select” or default value has been defined, the first item on the list will be chosen by default. It’s a good idea to have either a null select or default defined for all dropdown fields. Null selects can also be used to give users a way to select “none,” but you can’t make such a field required. If you want to force them to make a selection in a field where “none” is an option, just add an item with the value “none” to the field values.
Selectors with an “Other” Option
Some types of selector will allow the user to type in a value that is not present in the list of options. If they select “other” they can type their value in to the text input provided for that purpose.
The “other” selector that can be named by adding an item specifying a title for the “other” value. For example:
Note that for multi-select selectors, only one “other” value can be stored.
This is an advanced setting for situations where you want to customize the behavior or appearance of the field.
To set an HTML attribute, type in the name of the attribute, paired with the value using a double colon to separate the two, like in this example when you want the link on the field to open in a new tab:
In the displayed HTML, that will include a
target="_blank" in the element.
To define multiple attributes, separate each attribute pair with a comma, like this: (this example can be used to configure a numeric field)
You can do this with any HTML attribute, but it’s important to remember this is a complex functionality and you may need to consult an authoritative source to understand how to use it.
For File-Upload and Image-Upload field types, you can also set the allowed file extensions here with an entry like this:
That will only allow files with those three file extensions to be uploaded to that field. Remember that this is not a security feature, it is only used to help the user upload the correct type of file.
Showing Units or Denominations
You can configure a field to show a units or denomination character in the field configuration. This is done in the attributes setting for the field, using the “data-before” or “data-after” attributes. For example, to show a currency field with a US dollar sign before it, use an attribute like this:
Any field that gets user input can be validated. The validation setting sets the type of validation to use.
- Required – the user is required to type something into the field or make some selection.
- Email – the user must type in a valid email address.
- CAPTCHA – only available for the CAPTCHA-type field, validates the user input.
- Regex/Match – this selection requires an additional value: either the regex pattern to use or the name of a field to match.
The “Match” validation is used to verify user input by making them repeat it. A common example is an email address: set up two text inputs for the email address: one is the normal field used to hold the email address, the second is a check. On the second field use “regex/match” validation and put the name of the first field in the parameter. This forces the second field to match the first.
Regex validation allows for a very flexible validation for specific values. It is a fairly technical subject, but I have provided a guide to help your through it: Using RegEx Validation
Each field can have a message that is shown if the field does not validate. If provided, this message overrides the global validation message that is defined in the Participants Database settings.
Adding A New Field
At the top of the list of fields is the “Add Field” button. Clicking that button the opens the Add Field form where you type in the Title of the field and the form element. The name of the field will be based on the title. That name can’t be changed later, but the title (which is the visible label for the field) can be changed at any time.
Because the “name” can’t be changed, you may want to use a short title to create the field. That will give you a simple, short field name, and you can change the title to something longer later.
After you type in your field title, select the form element type to use, then click the blue “Add Field” button to add the field. Once added, you can complete the configuration of the field by opening the field editor for the new field.
Recovering Deleted Field Data
When a field is deleted, the data that was stored by the field is not deleted from the database. What is deleted is the definition of the field itself. This means that you can recover data from an accidentally-deleted field by re-creating the field.
In order to do that, you must give it the exact same name as the field that was deleted. You can do that when creating a new field, just enter the name (not title!) of the deleted field and select the same form element type as the old field. A new field will be created that will assume the data in the main database.
Form Element Types
- 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 one 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. If the “Use WP auto format” setting is set, the content of this field will be passed through the “the_content” filter, meaning things like shortcodes will be processed.
- 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 if you want date searches and sorts to work correctly. 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.
- Radio Buttons – for showing several choices, only one of which may be selected. This is better than a dropdown for a small number of choices.
- Dropdown List – the is the familiar dropdown control, allowing only one item to be selected at a time. This is better for long lists of options.
- Dropdown/Other – this is a special type of dropdown that presents a text field when “other” is selected, allowing for a write-in choice.
- Multiselect Checkbox – this presents a multiple-choice series of checkboxes, any number of which may be selected.
- Radio Buttons/Other – like the Dropdown/Other, only better suited to a few choices because all the options are visible.
- Multiselect/Other – like the Multiselect Checkbox, several choices can be made, plus a write-in choice. Not good for large numbers of choices.
- Link Field – this is a special field for defining a link, it allows the link text to be defined along with the URL. If only the URL is provided, the link text will be the URL.
- 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. Enhanced image upload capabilities are available using the Image Expansion Kit add-on.
- File Upload Field – this provides a general file upload control. Any file type appearing in the “allowed file types” setting will be accepted as long as it is under the maximum file size. The accepted file types may also be defined on a per-field basis by entering a list of allowed file extensions in the field attributes.
- Numeric – good for storing numbers, integers only. You can set up limits and step values in the “values” field, like this:
max::100, min::0, step::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 configuration values as in the numeric field.
- Currency – allows for numbers with two decimal places, like most currency values. Currency symbols are not allowed, it’s just the number part. Uses the same configuration values as in the numeric field. You can define a currency symbol using the data-before attribute. For example:
- Password Field – this is a special-use field for developers so that a hashed password can be stored with the record. The Participant Login add-on makes use of the password field to create a secure way for the user to edit their record.
- 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. For more robust bot registration prevention, check out the reCaptcha Add-On.
Form Element Type Special Settings
Some form element types have special settings available to them.
Numeric Form Element Types
This includes, Numeric, Decimal, and Currency form elements. You can define a symbol to be shown before or after the number by using the “data-before” or “data-after” items in the attributes of the field. For example:
Will place a US dollar sign before the number. This is helpful because it is not possible to place text characters in the data for numeric fields.
All the database fields are part of a field group. The purpose of field groups is to help organize your fields into logical sections (this makes a better interface for your users) and also helps you manage the fields when there are a large number of fields.
Field groups are also how you control the visibility of fields, as explained below.
Field groups are managed under the “Field Groups” tab on the Manage Database Fields page:
Field groups have a View Mode setting that controls the visibility of the fields it contains. Here are the settings explained:
- admin – only administrators can see these fields
- private – the fields in a private group can only be seen by admins and in the frontend record edit display
- public – fields in a public group can be seen by anyone.
It is important to understand that content visibility is also controlled by WordPress, so for instance, public groups can only be seen by the public if you place a plugin shortcode on a publicly-visible page.
Field visibility can be overridden in the shortcode by using the “fields” attribute.
The “Record Info” group is special, it can’t be deleted, and stores metadata about the record that is set by the plugin when records are created and updated.