Using the Participants Database Plugin

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 [pdb_signup] shortcode.

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 the 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, it is referred to as the “single record page.”

The Single Record Link

To show a single record, a special URL is used that includes the id number for the record. The easiest way to set this up is to configure 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 can set this up by creating your single record page, 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: [pdb_single groups="main,address"]

The “fields” attribute works the same way, but it is a list of field names. For example: [pdb_single fields="first_name,last_name,email,phone,address,city,state,country"]

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 [pdb_record] shortcode.

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.

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.

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 shorttt 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 shorttt. 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 shorttt 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 shorttt to display the thank you message. This is not needed if you have them just go back to the signup page, the signup shorttt 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 shorttt 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

One application for the list filtering option allows you to control whether a record gets displayed, giving you an approval process for new records.

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.

Configuring an “approved” field

With the Approved field in place, use a shortcode like this to display your list:

[pdb_list filter='approved=yes']

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:

[pdb_list filter='approved!=no']

The Search Shortcode

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:

Using the Search Shortcode

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.

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:

There are [pdb_total filter="approved=yes"] signups so far!

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_single] and [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:

[pdb_single groups="main,address,personal"]

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.

Shortcode Templates

All shortcodes use a template to determine how they are presented.

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.

>>How to use custom shortcode templates…

The default and example template files include comments to help you develop your own templates easily.

Image and File Uploads

Images and files can be uploaded through the “image upload” or “file upload” form element types. The allowed file types are set globally in the settings (General tab) or they can be set for each field by listing the allowed file extensions in the attributes for the field.

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.

Setting the Allowed File Types on a Per-Field Basis

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:

allowed::jpg|jpeg|png|gif

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.

Importing Records

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.

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.

Exporting Records

The plugin can also export a CSV file from the admin “List Participants” page. The same fields that are selected to import with the CSV will be exported. 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 setting under the “Signup Form” tab is set to overwrite matching records and that the matching field is “Record ID.”

Multiple-page Forms

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.

Plugin Support

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.