This page provides a compendium of help notes pertaining to the main settings in Participants Database. It is a work-in-progress, new notes are added as needed.
General Settings
File Upload Location
This establishes the path to all file, CSV and image uploads for the plugin. By default, the plugin places all uploaded files in the path wp-content/uploads/participants-database/ which will be preceded by the server’s path to your WordPress install to complete the file upload location path.
In most cases, you should be using the default value here, unless you have a specific reason to put it in another location or want to give the folder (participants-database) a different name.
Do not use the advanced setting “File and Image Uploads Use WP Content Path” setting with the default “File Upload Location” setting, see below for details.
“The configured uploads directory for Participants Database is not writable.“
If you are seeing this message, it is important to first test the functionality to see if it really isn’t working. If it is not working, check this setting to make sure the path is correct. For the vast majority of WordPress installs, the default location will work. If you want to modify this because you want to organize your uploaded files in a different way, make sure the new path you are using is correct. On some systems, the character case will matter here.
If you’re getting a notice that the directory could not be created, and you are certain the path to the uploads directory is correct (or it is the default) then you will need to check to see if the directory exists. You can do this using your File Manager or FTP. If, for some reason, the plugin could not create the directory for you, and the directory does not exist, you can create it manually.
If the directory does exist, check the ownership and permissions to make sure it is correct. They should be the same as all the other directories you see there. Do not set the permissions to “777” that usually will not work and may create a security issue. Ask your web hosting provider for help if you cannot get this working.
If your WordPress install uses a non-standard directory structure, you can usually get things working by using the File and Image Uploads Use WP Content Path setting.
Always “dismiss” (click the “X” in the upper right corner) the message after changing the setting so you will know that the problem still exists if the message is shown again.
Testing the File Uploads Location Setting
To test to see if this is working, try uploading an image or other file (if your form is configured to allow a file upload) and check to see that it was successfully uploaded. If it was not uploaded, or you see an error message, then it’s possible there is a problem with the file uploads location setting. This setting also affects CSV imports, so you can test it by doing that as well.
If the uploads are working, you can safely ignore this message, by dismissing it and using the “Don’t Show File Uploads Location Warning” setting found in the plugin settings under the advanced tab.
Allow File Delete
When this switch is checked, files that have been uploaded can be deleted. Uploaded files will be deleted if this setting is checked and the following conditions occur:
- A new file is uploaded to a file or image upload field, the previously uploaded file for that field will be deleted.
- The “delete” checkbox is checked when the record is updated, this provides a way to remove or blank out an upload field.
If this is unchecked, files that have been uploaded are not deleted by the plugin.
Show Delete Switch
This simply controls whether the “delete” checkbox is shown with file- and image-upload fields. The main reason for including this is to give the user a way to “blank out” an upload field. If you don’t want your users doing this, you can uncheck this option.
It is important to know that this switch does not determine whether a file is deleted or not. If “Allow File Delete” is unchecked, all this switch does is blank out the field value if it is checked when the record is updated, the file itself is untouched.
This switch doesn’t do anything if a new file is uploaded to the field, the new file name will replace the previous one whether it has been checked by the user or not.
If you want to show/not show the delete switch only for some fields, you should keep this checked, then use CSS to hide the checkbox on fields where you don’t want it to show. This might be desirable on “required” fields, where you want to force the user to upload a new file if they need to change it.
For example, if the field you wanted to hide the delete checkbox on was named “photo” you could use CSS like this to hide the delete checkbox:
.photo-input-group .file-delete { display: none; }Signup Form Settings
Record Form Settings
List Display Settings
Resend Link Settings
Admin Settings
Advanced Settings
Allow HTML in Text Fields
When this is checked, HTML tags will be allowed in “text” and “textarea” type fields. This setting can be overridden in the field definition by using the “allow_html” attribute. If this attribute is present or true, HTML tags will be allowed in the field, if set to false, HTML tags won’t be allowed in that field.
If HTML tags are allowed, they will be filtered to screen out any dangerous html tags or attributes. This includes things like scripts, script events, or iframes.
CSV Imports in the Background
When this is enabled, data that is imported with a CSV file is processed and saved to the database in the background. What this means is that after the file is uploaded, the page is reloaded and you can close the page or go to other pages while the data is being processed.
This setting is enabled by default. This setting allows for much larger imports because the data waits in a queue, allowing the server to do other things at the same time…basically, it allows the server to multitask and so it doesn’t matter how much data is getting imported, it keeps working on the queue until it is finished. When you refresh the CSV Import page, a progress report will be displayed.
Please note: server caching can prevent background imports from working. If you have problems with background imports, you may need to adjust your server caching configuration to get things working. This specifically applies to “object” or “database” caching because the queue is kept in the options table.
If your imports are pretty small you may prefer to disable this so the import happens immediately. Also, in cases where it proves impossible to get background processing to work, this setting provides a workaround.
Another reason background imports are better is if you are using calculated fields or add-ons such as Participant Log or Directory Tools, there is a lot more processing to be done for each record as it is imported. This means it takes more time to import data, and if you’ve got background imports disabled and the import is too much to handle on a single page refresh, the operation will time out, causing problems such as an overloaded server and lost data.
This setting does not override php file size limits. Your server’s php configuration will set a limit to the size of file that may be uploaded. If you need to upload files that are larger than the php configuration allows, you can in most cases change the configuration to allow it. Ask your hosting provider about this if you don’t know how to do this yourself.
CSV Background Imports Not Allowed by Server Configuration
In some cases, the server configuration doesn’t allow background imports. This is usually for security reasons.
In some cases, to secure the web server, access to the ajax script is restricted to prevent unwanted access. This script is part of your WordPress install and is found at wp-admin/admin-ajax.php. Most of the time, you can safely enable this access for your server only by whitelisting the IP of your site server. If you don’t know how to do this, ask your hosting provider.
If you are using a security plugin, you can usually whitelist your server IP in the plugin configuration. This is not the IP of the computer accessing the site, it is the IP of the server that hosts your WordPress site. If you are successful in allowing the access, the warning message will not return.
If the plugin can’t post the imported data to the admin-ajax.php script, the background import will silently fail.
Use the Private ID for the Single Record Link
This setting enables the use of the Private ID in single record links. When this is enabled, all single record links presented by the plugin will use the ?pid={private_id} format to open the record on a page with the [pdb_single] shortcode on it.
When this setting is active, the normal numeric ID links with the format ?pdb={record_id} will no longer work.
This setting can prevent users from viewing records by guessing the ID.
Be careful with this setting: it is important to understand that the Private ID value used here is the same for opening a record for editing on a page with the [pdb_record] shortcode, so it will be necessary to think about how this might expose records to editing by unauthorized persons.
Strict Date Format
This setting forces users to use a specific date format when inputting dates. For most sites this is not needed, by default the date parser can deal with a wide range of date formats.
If you are in a locality where a commonly used date format is not parsed correctly, or if there is some special type of format you want your users to use, it may help to use this setting so that format can be correctly parsed.
This setting will affect all “Date” fields used by Participants Database, including fields that use the Datepicker extension.
Input Date Format
When using “Strict Date Format,” this defines the format that users must use when entering a date. This setting must be a valid php date format string. (Click the link for a full explanation of the format.) This is the same type of format string that is used by WordPress in its date formatting settings.
It is advised that you give the user specific instructions about the format they need to use. You can use the field help text for that.
This setting is only active when “Strict Date Format” is enabled.
Enable the Participants Database external API
When this is checked it will be possible to send REST requests to the server to interact with Participants Database.
When this is unchecked, no access to the plugin REST API will be possible.
Check this page for the details: Participants Database REST API
Enable Limited Public Access to Plugin API
When this is checked, limited public access using only GET requests will be enabled. This allows an anonymous requester to get information about the database. Read the seaction on GET requests on the Participants Database REST API page for the details.
Selecting this will not allow anonymous requests that change the database in any way, it only allows getting information such as the contents of a record.
Use Cache-Busting Query Variables
Participants Database, like many plugins that generate dynamic content, can sometimes run into problems with caching. The root of the issue is that caching and site accelerators work by serving cached content that is much more rapidly provided than content that is dynamically generated. This works great for things that don’t change a lot, but when dealing with things like form submissions, the content must be generated dynamically.
Caches don’t always know when it’s necessary to generate dynamic content, and this can cause problems. One of the ways that caches can know that the content must be generated dynamically is if there is a “query variable” in the URL.
This setting, when checked, adds a query variable to the return URL from a signup submission, signaling the cache to serve the dynamically-generated content and not cached content.
Use Alternate Session Method
As of Participants Database version 1.8.2, we offer this setting to give site operators an alternative to the use of php session cookies. If php sessions are not working on your site, or you just prefer not to use them, checking this box will invoke the alternate method that does not rely on a cookie.
Common symptoms of sessions not working are signup thanks messages not displayed and receipt emails not going out, issues with multi-page forms, and list search results and pagination using AJAX.
The way this alternate method works is simply that the session ID is passed to the next page in the URL. This will only happen as needed, so most of your site URLs will remain unchanged. The session ID is only valid for a short time, so re-using the URL with the ID will not expose sensitive data.
File and Image Uploads Use WP Content Path
The default base path (the path that the “File Upload Location” setting is added to) is usually the WordPress root: the directory that contains wp-content, wp-admin, etc. in a standard install. In some cases, a non-standard directory setup is in use and it is more convenient (and sometimes necessary) to use the defined content directory (typically wp-content) as the base for file uploads instead.
To help clarify how this works, by default, the “File Upload Location” setting is wp-content/uploads/participants-database/ If the “File and Image Uploads Use WP Content Path” setting is checked that same setting would need to be uploads/participants-database/ because the new base is wp-content, so it is no longer needed in the path setting.
Note: When you change this setting, you may need to change both the “File Upload Location” and the “Default Image” settings (under the “General” tab) to get the correct path.
It’s best not to enable this setting unless you have been unable to get the default setting to work, in the majority of WordPress installs, this will not be needed.
Allow Record Timestamps to be Edited
Record timestamps are the “Date Recorded,” “Date Updated,” and “Last Accessed” fields. Normally, these values are set automatically, but you may have a specific need to change them. This setting allows you to change these values.
Remember that you will lose the original values when you change them manually.
Sync php Timezone
This setting sets the php timezone to match the timezone from the WordPress settings. This is helpful in cases where php is reverting to the server’s timezone instead of using the timezone set in the WordPress timezone setting. Uncheck this to let php determine the timezone.
This setting will only affect user-created “date” type fields, it does not affect the timezone used for record timestamps.
See: Date Shifting and Other Timezone-related Issues in Participants Database
Record Timestamps Use Local Time Zone
Select this to use the timezone set in the WordPress settings for your site when setting a timestamp on a Participants Database record. Record timestamps include “Date Recorded,” “Date Updated,” and “Last Accessed” fields of the record. User-defined date fields are not affected by this setting.
This setting is unchecked by default, and when unchecked, the record timestamps will be set using the normal UTC (or GMT) timezone.
Allow Javascript Attributes
Normally, javascript action attributes (such as “onclick”) are blocked for security reasons. If you need to use a javascript attribute in one of your form fields, checking this will allow its use. This switch enables a list of the most commonly-used attributes in forms:
onblur, onchange, oncontextmenu, onfocus, oninput, oninvalid, onreset, onsearch, onselect, onsubmit, onkeydown, onkeypress, onkeyup, onclick, ondblclick, onmousedown, onmousemove, onmouseout, onmouseover, onmouseup, onwheel
If you need to use an attribute that is not in this list, you can add it with a bit of custom code called on the pdb-allowed_html_form filter.
Enable Debugging
Selecting this will enable plugin debugging messages to be written to the plugin debugging log. While this is enabled (not “off”), there will be a “Debugging Log” item in the admin menu where you can see the debugging statements.
- “off” no debugging
- “plugin debug” debugging messages from the Participants Database plugin will be written to the log
- “all errors” general errors plus plugin debugging messages will be written to the log
- “verbose” in addition to capturing all errors, the plugin will add status messages to the log
Debug logging will also be enabled if the site-wide WP_DEBUG constant is set.
Read this article for some best practices when using the debugging log: Using the Participants Database Debugging Log
It is a good idea, for reasons of performance and security, to leave this in the “off” position unless you are actively trying to solve a problem.