The Signup Form
To give your users a way to create a new record on the frontend of your site, you must use the “signup” form, which is placed using the
You can define which fields are included in the signup form on the Manage Database Fields page. Each field has a “Signup” checkbox that must be checked to be included in the form.
This is explained in detail on this page:
Configuring the Signup Form
Showing a List of Records
You use the
[pdb_list] shortcode to show a configurable list of Participants Database records on your site. To do that, type the list shortcode into the content where you want it to appear.
For a detailed explanation of the use of the list shortcode visit this page:
Using the List Shortcode
Showing a Single Record
To show an individual record on the website, use the
[pdb_single] shortcode. In a typical setup, you would create a page on your site to display the record. This is often referred to as a “detail” display because it can show all the details contained in a record. In the plugin settings (under the List Display tab), it is referred to as the “single record page.”
The single record shortcode requires a special URL to show a record, which contains the record id as a variable in the URL, like this:
The Single Record Link
The plugin is set up to generate links to the single record and show them in the list of records. This is set up by configuring the List display to provide a link to the detail page for each record in the list.
While a list is a good way to show a lot of records, you can only show a limited amount of data from each record. A good way to deal with this is to add a clickable link to each record in the list that, when clicked, takes the user to all the details contained in that record. You can see this in action on the Demo Page, where there is a link on “View Details” that takes you to show all the values in the record.
You will need to create a page for showing the single record, then put the
[pdb_single] shortcode on that page. In the plugin settings, under the List Display tab, look for the “Single Record Page” settings and set that to the page where your
[pdb_single] shortcode is. Then, in “Single Record Link Field” choose which field will be the link to the single record page. You can set the link on any text field or an image field.
Setting up a “View Details” Link
If you want to make a field that is just for linking to the record, create a new field for that purpose. Make it a “Placeholder” type field and put as the default value the text you want to use for your link. In the demo, it has “View Details” there. Now, in the plugin settings under the List Display tab, select your placeholder field in the Single Record Link Field setting.
Configuring the Single Record Display
This shortcode has two templates available to it: the default, which uses a table-based layout and “bootstrap” which uses a more responsive layout, and is used with a shortcode like this:
[pdb_single template="bootstrap"]. Custom templates are also possible.
By default, all fields that are in public groups will be shown by the single shortcode. You can also determine which fields are shown using the “groups” or “fields” attribute of the shortcode. The “groups” attribute lets you determine the field groups to show in the shortcode, for example:
The “fields” attribute works the same way, but it is a list of field names. For example:
You cannot combine the fields and groups attributes in a single shortcode.
Showing an Editable Record
A Participants Database record can be edited on the frontend by showing the record as an editable form using the
This form is accessed by using a special URL called the “private link” which contains an access code to a particular record. Typically, the private link would be provided to the user by email when they register so they can return and edit or complete their form. the private link will look something like this:
You set this up by creating a page for the
[pdb_record] shortcode. This is called the “Participant Record Page” and it is configured in the plugin settings under the “Record Form Settings” tab.
Fields in administrative groups will not be shown by this shortcode. You can limit which fields are shown in this shortcode by using the “fields” or “groups” attributes, for example:
Resending a Lost Private Link
If you want to give the user the ability to receive their private link again, check “Enable Lost Private Link” under the Resend Link tab on the settings page. Check the other settings there to complete setting it up. The user will be asked to supply a piece of information that will identify their record, usually an email. Their private link will be sent to the email address saved with the record
The private link request form will normally replace the “signup” form on the same page, but you can put the private link request form on another page if you want. Select that page in the “Lost Private Link Page” setting and place the
[pdb_request_link] shortcode on that page.
Shortcodes this Plugin Uses
This plugin uses a number of different shortcodes to place it’s functionality in your content. Here is a list of all the shortcodes with a brief description:
- [pdb_signup] – This prints out the signup form including only those fields selected for inclusion. On submission, it creates a new record and optionally notifies the admin and the person signing up by email.
- [pdb_list] – This shortcode prints out a list of records from the database. Which records get displayed and how can all be determined in the settings or in the shortcode. You can optionally show a search and/or sort control with the list.
- [pdb_single] – This shows a single record as determined by the record ID present in the URL used to access the page. It is possible to set a link to the single record in the record list, allowing for a detail display of a single record.
- [pdb_record] – This shortcode only displays when accessed with a URL including the record “private id” number. It allows the user to edit and add to their own record, while others won’t have access to it. A private link to this record can be included in the “thank you” email they will receive on submission.
- [pdb_signup_thanks] – If you want to send the people who use the signup form to another page after they submit, you can use this shortcode to display the thank you message. This is not needed if you have them just go back to the signup page, the signup shortcode will take care if it.
- [pdb_search] – used if you want to place the search form in a separate location from the list. When the search is performed, the user is taken to a page with a list shortcode and shown the result of their search.
- [pdb_request_link] – shows a form for requesting the private link to be resent.
- [pdb_total] – shows the either the number of records matching a given filter or the numeric total of a given column of values.
Take a look at this article for a full explanation of all the shortcode attributes you can use: Shortcode Attributes
Approving Records for Public Display
The List shortcode can be configured to filter which records are shown. You can use this to prevent unwanted records from appearing to the public.
In the default set of field provided with the plugin, there is a field in the Administrative group named “Approved” (If you don’t have this field, create one the the Administrative group. Call it “approved” and make it a checkbox type field.)
Put this in the options for the field:
Yes::yes,No::no with a default value of ‘no’.) You can also set the default value to “yes” if you want to use it as a “disapproval” function. The part in front of the :: is the visible title of the checkbox, the second part is the value that is saved to the database.
With the Approved field in place, use a shortcode like this to display your list:
Now, only records that have been approved will be included in the list display. You may need to do something like this if you get a problem with spam, for instance.
If you’re using it as a “disapproval” function, set the filter the opposite, like this:
The Search Shortcode
The best way to show a search input for the list display is to enable it in the List shortcode like this:
If needed, it is possible to show a list search control that is detached from the list display. This might be used if you want to send users to another page to show the results of a search.
You don’t need this shortcode if you just want the search control to appear above the list display. It’s best to do that by enabling the search control in the shortcode.
A full explanation of how to use the search shortcode is found here:
The “Total” Shortcode
This shortcode provides an easy way to show stats and totals from the database. In it’s simplest form , it shows the total number of records, but you can use the filter attribute to show other totals such as the totals from a certain location, or just to show only approved records and stuff like that.
This shortcode can also be used to show a calculated total from the data stored in any field. Put the name of the column to be totaled in the “fields” attribute and all the numbers stored in that field will be summed and displayed.
The “filter” attribute can be used to limit which records are included in the total. This works exactly the same as is does for the
[pdb_list] shortcode. More detail on how to use the filter shortcode attribute: List Shortcode Filters
The shortcode template is where all the math happens, and this gives you the flexibility to show things like cumulative standings, earned totals, or the time elapsed since a date stored in the database (for instance, an age based on the birthday field). Because it’s in a custom template any kind of calculation that you can think of is possible. Take a look at the template file for this shortcode (pdb-total-default.php) for a simple demonstration of how that can be done.
The output of this shortcode is simply a number, so it can be used inline or you can put a bunch of them on a page to show several things at once. For instance:
Using Field Groups
All of the database fields are divided into groups to help keep things organized and easier to understand for the user. Field groups are particularly important when there are a large number of fields defined.
Groups can be used to control the layout of
[pdb_record] shortcodes. When enabled, each field group can show a title and a description from the group’s configuration. These can be used to guide the user and to visually separate blocks of fields on the page.
Field groups have a View Mode setting that determines where the fields in that group are visible:
- Public: the fields will be shown in all frontend and backend displays.
- Private: the fields are only shown in the record edit form and the backend.
- Admin: fields are only shown in the backend.
Field groups are configured on the Manage Database Fields page under the Field Groups tab. You can add/delete or edit your field groups there.
The “Groups” Attribute
The “groups” shortcode attribute greatly simplifies managing which fields are shown when you need to do this in the shortcode.
The groups attribute is a comma-separated list of group names. Don’t try to use the title of the groups, it won’t work. For example:
For the ‘signup’, ‘record’, and ‘single’ shortcodes, when the “groups” attribute is defined, only those fields contained in the groups named will be shown. For the signup form, the fields must also have the “signup” checkbox checked to appear in the form.
All shortcodes use a template to determine how they are presented. Take a look at this page for a detailed description of all the templates and their options:
Plugin default template files are found in the “templates” directory in the plugin directory. There are several examples to show you a little of what is possible. I have created a page to guide you through the process of creating a plugin template here. Please note that using custom templates will require some understanding of HTML, CSS and PHP.
Check this article on the use of custom templates: Using Participants Database Custom Templates
Image and File Uploads
Images and files can be uploaded through the “image upload” or “file upload” form element types.
There are 3 main settings to configure file uploads: File Upload Location, File Upload Limit and Allowed File Types. Check these settings and make sure they are correct for your purposes. In most cases, you will not need to change the File Upload Location.
The File Upload Limit sets the maximum size allowed for a file upload, but it is important to make sure that your system file upload limit is high enough to allow whatever setting you have here. The php settings you need to check are: upload_max_filesize and post_max_size. These are usually accessed in your hosting control panel. Consult your web host if you cannot set these yourself.
File Upload Limit and Allowed File Types can be set on a per-field basis also. The Allowed File Types global setting should include all the extension you want to accept in all upload fields. Then in the individual field, you can set which extensions are allowed in the field, for example:
Please note that file uploads can present a security risk. The plugin offers some protection from malicious use by renaming the uploaded files to insure that only an allowed file extension is present in the filename. It is important to make sure your web server is configured so that your allowed file types cannot be executed as scripts. Ask your web host tech support if you are unsure about this.
Image and file uploads can be stored anywhere in the WP install directory. The ‘File Upload Location’ setting will always determine the location for the images and files.
Remember, however, that if your users have uploaded files and you then change the File Upload Location setting, the files uploaded before the change will no longer be properly linked. You must move those files to the new location.
IMPORTANT: Don’t store images or any other custom information in the plugin directory because they will be deleted by automatic upgrades. The default location for plugin uploads is in “wp-content/uploads/participants-database/” and for most installations this is a good place to keep them.
If you need to restrict which types of file can be uploaded for a particular field, you do that by adding an “allowed” attribute. This is done in the attributes setting for the field. The value of the attribute should be a pipe-separated (the “pipe” character is |) list of file extensions. For example:
It is a good idea to clue your users in to what is expected using the Help Text setting for the field. While you’re at it, it’s helpful to tell them the maximum file size they can upload.
Importing & Exporting CSV Files
CSV is a common file format for exporting or importing databases and spreadsheets. You can export a CSV file from your spreadsheet or database and import the records into the plugin. It can be a tricky process, so I’ll offer a few hints here on getting it to work.
To import a CSV file reliably:
- The CSV file should have it’s fields delimited by a comma and the text enclosed by double quotes. (this is strictly only required for a field that contains a delimiter character).
- The first row should be a header row containing the column names (which must match your field names).
- The encoding of the file must be UTF-8. This is very important, and many spreadsheet apps (looking at you, Excel!) need to be configured to export in this format.
On the CSV import page is a button to export a blank CSV file in the correct format to get you started. It is critical that your database or spreadsheet application be able to export the CSV in the proper format for the process to work.
In some cases, you may have to open your CSV file (as exported from your spreadsheet or database) in a text editing application for further modification to get everything working. This must be a plain-text editor, don’t try this with a word processor!
In particular, if your data has both double and single quotes (which are also apostrophes!) in it, it will be very difficult to import because one of the two will need to be used as the text delimiter. This does not apply to “curly” quotes and apostrophes, which are not enclosure characters. I suggest you convert quotes and apostrophes that are part of blocks of text into their HTML equivalents: ' for apostrophes and single quotes and " for double quotes. This way, the text delimiter can do its job without other characters interfering.
The “Image Upload Location” setting in the plugin is important here because that is where the plugin will place the uploaded CSV. The default setting for this is ‘wp-content/uploads/participants-database/’ If the plugin does not find the directory specified in the “Image Upload Location” setting, it will attempt to create it. It should notify you if it fails, and you may have to create the directory manually (using an FTP client, for instance) to get the CSV import to work.
As of version 1.9.8, CSV imports are processed in the background. This means that when you upload the CSV, the page will refresh and the number of records that were found in the file is printed to the screen. The data in the file is loaded into the database in the background. When the page is refreshed, the import status will be displayed.
Importing in the background means that you can import a large number of records and it won’t go over the time limit imposed on operations by the php configuration. There is still the limit to the size of the file you can upload, but the most time-consuming part of the operation is performed by the server on its own. You can do other things with the site while the import is getting processed.
When the process is complete, a report is displayed when the import page is loaded again.
If you need to import records from another database, take a look at this article: Migrating an Existing Database into Participants Database
The plugin can also export a CSV file from the admin “List Participants” page. All fields that have the “CSV” checkbox checked in the field definition (Manage Database Fields page) will be included in the export. You can assign or unassign multiple fields from the CSV export on the Manage Database Fields page by selecting the fields and using the “with selected” control to add or remove the fields from the CSV export. This does not affect imports: any valid field in the CSV import can be imported, regardless of the CSV setting of the field.
You can choose with records to export by using the list filter: if the list is getting filtered (for instance, with a date range) only those records will be exported.
If you are planning to export records from the plugin and then re-import them (for instance, if you wanted to edit them in a spreadsheet application) you should export them with the record ID numbers. Then, when you re-import them, make sure the CSV import setting is set to overwrite matching records and that the matching field is “Record ID.”
Multiple-page forms are now easily implemented using the new “action” shortcode attribute. When a signup or record form is submitted, the user will be taken to the page named in the “action” attribute. If that page has a
[pdb_record] shortcode, it will show an edit form for the same record, but by configuring each shortcode to show a different set of fields, the whole form is broken up into separate pages. The user can even leave the form and return to finish it, each page updates the database when it’s completed.
Check this post for a tutorial: Creating Multiple-page Forms in Participants Database.
I do monitor the WP forums and comments page on my own website for support requests. I very much appreciate bugs being brought to my attention, so please let me know if things are broken or not working as expected. I only ask that you read the documentation before posting with support requests because it will save us both valuable time. Many of the issues people have are due to improper setup or use of the plugin…this is partly due, I know, to shorcomings in the documentation. It is a complex plugin with lots of options, so it can be difficult to explain how it works in a way that everybody will understand.
About Plugin Display and CSS
I get a lot of questions about how to make the plugin’s output look like the site it’s on or how to make things look different. I have made efforts to set up the plugin output to work most of the time out-of-the-box, but with so many themes out there and so many ways to control how things look, things don’t always look right. While I try to answer specific questions about formatting the output of the plugin, most questions about CSS are far too general for me to answer with a fix. If you are responsible for what things look like on a website, I think you should have an understanding of how the CSS and stylesheets work on the site. The single most helpful thing you can do if you want to understand how the CSS is working is use Firefox with the Firebug extension. It will show you what CSS rules are affecting any element of the page and also allow you to edit the CSS and see the effects of your changes right away without breaking the display for other users. You can learn a lot that way. If you want to get help with a particular aspect of the display, be specific, say what you want to see, and if possible provide a link for people to see what you’re talking about. Questions like “things are messed up, something’s wrong” will probably be ignored.