Note: this documentation is for the Manage Database Fields UI for versions of Participants Database before version 1.9.0. Please see Manage Database Fields for versions 1.9.0 and later.
The Participants Database stores data in a set of user-definable fields. The plugin installs with a default set, and these can be deleted or edited depending on what you need the plugin to do. You can also add new fields. All this is done on the Manage Database Fields Page.
The Manage Database Fields Page
Each “field” in the database is defined by several parameters such as a name, a title, a type of field, etc. For the database to work as expected, each field in the database must be correctly defined. The main page for setting up your data fields is the Manage Database Fields page. On this page, each field is listed, organized by groups.
Editing Existing Fields
The plugin comes pre-loaded with a set of fields to get things started. You can edit all the parameters of these fields (except the name) so they are tailored to your needs. These fields can also be deleted if they are not needed.
If there are fields defined that you don’t need, it’s a good idea to delete them. To delete a field, click the red “X” on the left side of the field, then confirm the deletion in the box that pops up. If any data was stored in this field, the data itself is not deleted, only the configuration of the field is removed. This is to prevent data loss.
Defining a New Field
When you create a new field, you start by defining the title for your field. The “name” of the field will be generated from the title. The name serves as a unique identifier for the field, and cannot be changed once defined. When a field is referred to in the code or in shortcodes, this name is what you will use to identify the field. The title is the visible name of the field and can be changed any time, it is only for display purposes.
The Field Title
Every field has a title, which is the main label for the field. The title is the name of the field that is visible to the public. It can be changed any time.
The field’s default value is used to pre-populate the field in the signup form. If it has the “persistent” flag set, it will also fill in any empty fields in the record edit forms, both in the backend an in the record edit form on the frontend.
All the fields in the database belong to a particular group of fields. These provide you with a way to logically organize your fields. When the forms and records are presented, the group title will appear over the fields in that group. Optionally, a group description can be shown under the group title. For good usability in long forms, it’s best to divide your form into logical sections which helps keep the user oriented to the task of filling it out.
The field group dropdown is where you can assign the field to any of your defined groups.
Each field may have a block of text attached to it, providing a good place to explain what is expected for the field. This block of text is only displayed where fields are displayed in editable form, such as the signup form or the record edit form. It won’t be seen in lists or single record displays.
Each field has a type definition that determines what kind of data can be stored in the field and how it will be presented. It is a good idea to choose the right type at the beginning, before data gets entered, because it can cause problems with existing data if you try to change it later because the data is stored differently for different types of field.
A list of the field types with a brief description and configuration instructions as needed can be found here.
Some form element types require a defined set of values. For instance, a dropdown or radio selector where the user is expected to choose from a list. In some cases, the “values” field is used for additional configuration information for the field. This is fully explained in the “Form Element Types” section below.
For all dropdown-, radio button-, checkbox-type fields, you must define a list of options. They are defined with a comma-separated list of values, such as “AL, ME, AZ, NM, CA” which would give the user a choice of those five states. It’s also possible to use labels for your selection lists like this: “Alabama::AL, Maine:ME, Arizona::AZ, New Mexico::NM, California::CA” Note that spaces are allowed, but leading and trailing spaces will be removed. In this example the second value is what is actually saved to the database, the first value is only the visible label for the selection.
Checkboxes only need one value, which is what will be saved if the it is checked. If there are two values, the second value will be saved if the box is unchecked.
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.” For instance: “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. The group is wrapped in a HTML element so that is can be styled as a group.
It’s also possible to define the “nothing selected” option with “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. If the field is required, the null select will not validate, forcing the user to make a real selection.
If there is no chosen value for the field, and 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.
For elements with an “other” input, the selector that chooses it can be named by adding an item specifying a title for the “other” value: “Something Else?::other”.
Find some possibly useful values settings for your dropdowns on the Useful Selector Values page.
This determines how the submitted value will be handled. You would set this to “required” to force the user to put something (anything except a space) in the field. If you want the input to be an email address, select “email” as your validation.
You can also put in a “regex” to check the content of the submission to make sure it follows a specific format. Select “regex/match” and an input field will be provided for your regex string. Creating regexes is an advanced art, but plenty of examples and tutorials exist around the web if you need to make use of this feature. Note that the regex string must include “delimiters.” I have written an article explaining in greater detail how to use regex validation: Using RegEx Validation
It is also possible to force the input to the field to match another field by typing the name of the other field into the space provided when you select “regex/match.” This is good for double-checking email addresses, for instance.
Display Column and Admin Column
These numbers tell which column a field will appear in in list displays. However, the best way to set up the display columns for both the backend (admin) and frontend (pdb_list shortcode) list displays is to the use the new Manage List Columns page in the admin.
If you want to set the values here, this is how it works: These numbers provide a global way to define which fields will be shown in record list displays. The number indicates which column to put the field in. A zero means the column is not displayed in the list. This does not affect single record displays. “Display” is for the frontend list and “Admin” is for the list as shown in the admin.
This defines a field as being one on which a list display may be sorted. This means that it will be included in the list of choices in the sorting controls on the frontend list displays.
This designates the field as one that will be included in a CSV export from the database. It does not affect which fields can be imported. Any column in an imported CSV file that matches a defined field name will be included in the imported data.
This designates the field as one that will be pre-filled in admin record edit and also frontend record edit forms. If a field is designated as “presistent,” and no value is defined for the field in the record, the default value will be filled in. If the record is saved, that value will be saved with the record.
In the admin side, if you are manually creating a series of records (using the “next” button) any persistent fields will carry over the value from the last record. This is a convenience when entering in a series of records which may have field values in common.
This designates a field as one that will be present in the signup form. This is a global setting which can be overridden in the shortcode using the “fields” attribute.
This designates the field as one that cannot be edited in the frontend record edit form ([pdb_record]). Such fields will always be editable in the admin record edit form.
When showing a frontend record edit page that contains readonly fields, the value of the field will be shown as uneditable form elements or plain text (in the case of HTML elements that do not have a “readonly” mode such as file uploads and dropdown elements.
Fields are organized into groups and it’s a good idea to think of each field as belonging to a group of related fields. This helps you organize the information and helps the user understand the form, especially if there are a lot of fields. Each group has a title, of course, but there is also a description which allows you to insert a block of text at the top of each group of fields.
Field groups are managed under the “Field Groups” tab on the Manage Database Fields page.
For each of the main forms, (signup and record edit) you can select whether group descriptions are shown or not. It is possible to have a blank title if you don’t want the group title shown at all. Field groups have a couple of checkboxes that determine where they are shown. Only groups marked “display” will show their fields in the frontend, but in the backend, all groups will be shown. This allow you to have fields that are for administrative use only. Groups marked “admin” will be shown to admin users only, and hidden from backend users with only an “editor” role.
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.
- 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 drodown 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.
- 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.
- 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 configuration values as in the numeric field.
- 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.
- 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 putting a comma-separated list of allowed file extensions in the “values.”
- Password Field – this is a special-use field for developers so that a hashed password can be stored with the record. The plugin does not make use of passwords unless custom code has been created to use them.
- 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. This is adequate spam control for most installations. Stronger spam controls will probably be needed for more popular sites, and can be easily implemented by a developer using the API.