- quick start
- list of plugin shortcodes
- defining and maganging the database fields
- showing a list of records
- showing a single record
- signup form
- the “total” shortcode
- the search shortcode
- the “groups” attribute
- form templates
- image and file uploads
- importing records using CSV files
- multiple-page forms
- plugin support
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 “thankyou” 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 [[pdb_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 Explained
Showing a list of records
You can use the
[[pdb_list]] shortcode to show the records on your site. Just put the shortcode where you want it to show up. Here is the full list of parameters you can use with the
- search – set to ‘true’ to show a list search field
- sort – set to ‘true’ to show a list sort field
- fields – a comma-separated list of fields to show (defaults to the display-column setting of the fields)
- list_limit – sets the number of records to list per page (defaults to the plugin setting value)
- class – lets you set the CSS class of the container (defaults to ‘participants-database’)
- filter – lets you determine which records are shown (see the usage notes for an explanation)
- orderby – order the list by one of the columns
- order – determines whether the list is ordered in ascending (asc) or descending (desc) order
- display_count – if set to ‘true’ will display a total of all records
- suppress – prevents any record from showing until a search is performed
You can set the number of records to show per page with the ‘list_limit’ setting.
Which columns are shown by the shortcode is set up on the fields management page. For each field there is a value called “display” that determines the order of the columns in your list display. You can also set the columns to display in the shortcode by including a list of the names (not Titles!) of the fields you want to show in the order you want to show them:
[[pdb_list fields="last_name, city, email, photo"]] If you want to get tricky with the CSS, each header column has a class name that corresponds to the name of the field, you can use CSS to lay out the listing exactly as you want.
Searching and Sorting The List
You can activate list searching and/or sorting for your users with these attributes:
[[pdb_list search=true]] or
[[pdb_list sort=true]] These attributes will enable a search form and/or sort form displayed above the list. The user can select which field they want to search through a dropdown and type in a search term. Only fields that are displayed can be searched. For sorting, the fields offered for sorting must be checked as “sortable” and also be present in the list display. There are two search modes for the list: strict or not strict. If the “Strict User Searching” setting (this is in the plugin settings) is checked, the search term must match exactly the whole contents of the field in order to be found. If unchecked, the search will show any records where any part of the searched field contains the search term. The search function is pretty simple, only searching only one field at a time. If you need more control over the search functionality you offer your users, you will need to create a custom search function for that purpose. I have created an API to make this kind of custom functionality easy to create, but knowledge of PHP and HTML will be needed to take advantage of that. In the future, I will be offering auxiliary plugins that can add enhanced search functionality.
The search from will accept wildcards for more control over the results. The asterisk stands for any string of characters, while the question mark stands for a single character. To search for all entries that begin with the letter “b” for instance, you would use the search term “b*”
Filtering which Records Get Shown with the List Shortcode
There are 3 parameters for the
[[pdb_list]] shortcode that allow you to determine which records get shown. It’s a little complicated, but here’s how you do it. There is a parameter called ‘filter’ which determines which records to show. The general format of the parameter is this: field operator value So, for instance, if you wanted to show all records from the state of New York, you would put
[[pdb_list filter='state=NY']] . “state” is the field (it must match exactly the field name as listed on the Manage Database Fields page in the plugin) “=” is the operator and “NY” is the value. The filter is grabbing all records where the state is “NY.” The operators can be ‘=’, ‘!’, ‘<‘, ‘>’ and ‘~’ only. ‘!’ means “NOT”, so if you wanted everything except a certain value. ‘<‘ and ‘>’ mean “less than” and “greater than” and can be used to compare values, like this:
[[pdb_list filter='last_name>k' ]] That would give you all the records where the last name began with any letter coming after ‘k’ in the alphabet. The ‘=’ operator looks for a strict match, and the ‘~’ looks for a string inside the value. Careful with this one, it can give unexpected results. These comparisons can be made with dates and numbers too, of course.
You can use the filter to exclude records that are missing a field or have a blank value by using the not operator and no value:
[[pdb_list filter="phone!"]] You can of course chain this with other filers, all you’re doing is omitting the “value” part of the filter statement.
You can use more than one filter by stringing them together like this:
[[pdb_list filter='last_name>c&last_name<h' ]] (note ampersand between filter statements) This gives you all records with last names that start with d through g. Upper case or lower case doesn’t matter.
Filters can be also be chained by an “or” operator by using the “|” (pipe) character. For instance, to get all the records with either “New York” or “Brooklyn” you could use:
filter="city=New York|city=Brooklyn" And they can be combined:
filter="color=red|color=orange&size=large" will give all large items in red or orange. Note that items separated with an “or” operator will be parenthesized, meaning that the above example would not return a list of all the red items plus all large orange items. This is because the parenthesized part is resolved first, so “red or orange” is resolved as a unit before the rest of the filter is included.
Filters accept wildcards (same as described above for user list searches) so you can set up a shortcode to show, for instance, all the entries beginning with a certain letter. This could be useful for breaking a list up into alphabetical groups.
To correctly compare dates, the field must be defined as a date field form element on the manage database fields page. Date values should be a regular date string like this:
[[pdb_list filter='date>jan3,2012']] It’s best not to use a number for the month (and maybe you have to use English month names) because the date/month/year order is different on different servers. If you really want to use numbers for the date, just try it to see what the correct order for your web server is. The “Strict Date Format” setting affects how the shortcode filters are interpreted, so if this is checked, the date format in your filter argument must match the date format set in your WP General Settings.
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. Create an administrative field (one that is not displayed or edited on the frontend) called “approved” that is a checkbox. Put this (without the quotes) in the values for the field: ‘yes,no’ with a default value of ‘no’. Then put this in the shortcode:
[[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.
Admin List Filter
The admin listing now allows a range of dates to be entered in the search field: just type in the first and last dates you want to see, separated by the word “to” like this:
July 1, 2013 to Aug 1, 2013
Showing a Single Record
To show an individual record on the website, use the
[[pdb_single]] shortcode. You must include the id of the record in the URL, so there must be ‘pdb=1333’ at the end of the page URL. The ‘1333’ in this example would be the actual id number of the record you want to show.
Adding a Link to the Single Record to 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 set this up by defining the page on which the
[[pdb_single]] is placed, and the column where you want the link to appear. In the plugin settings, under the List Display tab, look for “Single Record Page”: 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. If you want to make a field that is just for linking to the record, create a field called “link” or something and then put as the default value the text you want to use for your link like “VIEW”. You must use the “detailed” list template for this to work. If you are good with CSS, you can easily make the link look like a button.
The Signup Form
To create a new record on the frontend of your site, you must use the “signup” form. The fields included in this form are defined in the “signup” column on the Manage Database Fields page. It is also possible to define which fields are presented in the form in the shortcode itself using the “fields” attribute as described above. This is one way it is possible to have different types of signup form. When a user fills out a signup form, the can be sent a receipt email confirming the submission. This email may also contain a private link to a page where their record may be edited. It is also possible to have an email notification sent to an admin when a signup occurs. These actions are set up in the settings under the “Signup Form” tab. When a signup form is submitted, the user can be directed to a “thank you” page acknowledging their submission.
The Math CAPTCHA
If you need a simple way to stop registration bots from sending in spam submissions, there is a CAPTCHA field that asks a random simple math question. For coders, the plugin API provides an easy way to add your own custom test.
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. Their private link will be sent to the email address saved with the record.
Hidden Signup Fields
There is a field type called “hidden” that can be used to add dynamic values to the signup form submissions. For instance, if you had the signup form in multiple locations on your blog, you could know which page the user was on when they signed up because the page name would be placed in a hidden field. Here is a quick tutorial showing how to add a field that tracks the page the signup form is on:
- Add a new field with a descriptive name, like “source page”
- Make that field a hidden type
- For the default value, put “post->post_title”
- This will fill in the title of the page the signup form appears on.
When the form is submitted, the information in the hidden field will be included. At the moment, only two WordPress objects are available:
$current_user. You can look these up in the codex to see what properties you can access. The way this works is simple: just put the name of the property in the default value field for the hidden field. For instance “current_user->user_login” will put in the user login of a logged-in user. You don’t need the dollar sign, it will ignore it if you do put it in.
You can also access some PHP “Superglobals.” For instance, to get the IP of the user, put this into the default: “SERVER:REMOTE_ADDR” You can access these superglobals: POST, GET, REQUEST, COOKIE, SERVER, SESSION. This means you can get a value from a cookie and put it into the form, saving it when the form is submitted. You don’t need the ‘$_’ that is used in PHP. The PHP site has a good reference for using superglobals. Superglobal arrays can be accessed with an index like this COOKIE:location[city] where “city” is the index in the array $_COOKIE[‘location’].
If you just want to put in a fixed value, the hidden field will include any string you put into the “default” for the field. This can be useful as a place to put links in a list or single record display.
[[pdb_record]] shortcode. These fields are visible and editable in the admin edit page.
Setting Up the Signup Form “Thank You” Page
To have your visitors go to another page after they submit a signup, go to the settings page and set the “Signup Thanks Page” setting to point to your page. Place the
[[pdb_signup_thanks]] shortcode on that page to display the thank you message. You don’t have to use the shortcode, but it gives you a way to thank them using their name. It’s also possible to use this feature to make filling out the signup form required in order to get to another (hidden) page on your website.
It’s also possible to determine which page the user goes to after a successful submission in the shortcode, by using the “action” attribute. For instance, of you were using more than one signup form, this makes it possible to send users to a different thank you page depending on which signup form was used.
The Search Shortcode
This shortcode gives you a way to show a search form on it’s own and send the user to another page (or a different part of the same page) to see the results of their search. This shortcode is not needed if you want to place your search just above the list. Use the “search=true” attribute in the [[pdb_list]] shortcode in that case.
The shortcode has an attribute named “target_page” which tells the search form where the search results page ([[pdb_list]] shortcode) is. You don’t need to use this if the search shortcode is on the same page as the target list, but if you put the search shortcode into a widget that can be on any page, you’ll need it.
If the target page has more that one Participants Database shortcode on it, you’ll need to tell the search shortcode which “instance” to update with the search results. This is done using the “target_instance” attribute. To find the instance number of your target list, take a look at the HTML of the page where your result list is shown. Wrapping your result list will be a “div” tag with a class containing something like “pdb-instance-2” That “2” is the instance number for that list, so you’ll need to put a 2 for the target_attribute value in the search shortcode.
If you have the search shortcode on the same page as your list shortcode, you will need to use this attribute in order for the search to work correctly.
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:
The Groups Attribute
The “groups” shortcode attribute greatly simplifies managing which fields are shown. 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” forms, the fields must also be enabled for the signup form.
All shortcodes use a template to determine how they are presented. Plugin default templates 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 templates will require some understanding of HTML, CSS and PHP.
Single Record Templates
Templates for the single record shortcode include an array that can be used to prevent some fields from displaying. Let’s say you wanted to exclude the city, state and postcode. In that case the array would be filled with those names like this:
$exclude = array('city','state','postcode'); These fields will now be excluded from the display. Of course it is also possible to determine which fields are shown in the shortcode using the “fields” attribute. The template offers many other opportunities to customize the output of the
[[pdb_single]] shortcode to match your theme.
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 “values” field 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, and can be moved without breaking image sources and links. The ‘File Upload Location’ setting will always determine the location for the images and files. 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.
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.
The import will work most reliably if the CSV file has it’s fields delimited by a comma and the text enclosed by double quotes. (this is actually only required for a field that contains a delimiter character) The first row should be a header row containing the column names (which are the same as 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 it’s job without other characters interfering. You will probably have to use a text editing application to make these substitutions.
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.
The plugin can also export a CSV file from the “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 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, allowing additional data to be added to the record. 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.