For any kind of deep customization of a shortcode’s output, you will need to create a custom template to control the display and functionality of the plugin. This will require some programming knowledge, so I’m going to assume you have some basic understanding of editing php files. The plugin templates are very similar to the templates a WordPress theme uses, so if you’re comfortable with that, you’ll be good. If that’s over your head, at the very least, you’ll probably need to find and walk through a good tutorial on editing WP templates in order to proceed with this.
Where to put your custom template?
I am recommending that anyone wanting to use custom templates download the free Custom Templates Folder add-on. This plugin makes it easy to put your custom template where Participants Database will find it.
Participants Database custom templates are by default found in your current theme, in a folder named “templates.” This can be tricky to determine, and it really has to be in a “child” theme unless you’re using your own custom theme. For this reason, I recommend using the Custom Templates Folder plugin instead of using the plugin’s default template location.
Creating the template
In order to do this, you will need direct access to your files, you can’t do this in WordPress. This means using either an FTP client (normally used to upload files to your web server) or a file manager in your hosting control panel.
The plugin has it’s own set of templates that it uses to display the shortcodes. These templates are in the plugin directory named “templates.” (
wp-content/plugins/participants-database/templates/) For each of the list, signup, record and single shortcodes, there is a template to display that shortcode. For instance, for the [pdb_list] shortcode, the default template is ‘pdb-list-default.php’ and you’ll find that file in the templates directory. These templates are an easy place to start in making your own templates, and are commented to explain how they work. In several cases, there are multiple examples of templates for a particular shortcode to get you started.
All we have to do to make a custom template is to copy one of the plugin’s templates into the currently active theme directory (represented by “THEME NAME” in the examples), into a directory named “templates.” You can find out which directory is the currently active theme directory by visiting the “appearance/themes” page in the WP admin. Hover over the “Customize” button, and look at the browser status bar where the URL of the button is shown…the name of the theme directory will be after “theme=” in that URL.
For the list shortcode, the path to your custom template will be something like
The plugin will look there first for the template to use. If there is no directory named “templates” in your theme, create one. If one already exists, you can add your template to it.
Use a Child Theme or the Custom Templates Folder Plugin
Please note that theme updates may delete this directory and any other theme modifications, so you should use a child theme to hold all your modifications. I also have available a free utility plugin that provides a location in the plugin folder for your custom templates. Check that plugin’s instructions for how to place the template when using that.
Setting up a child theme is easy, most commercial themes include instructions for setting one up, and there are several WP plugins that can do the job for you. The use of child themes is explained more fully here.
Editing the template
These plugin templates are very much like WP theme templates. They use loops like WP, only the data objects are different and there are two nested loops. For the list shortcode, the outer or top loop cycles through each record. For the rest of the shortcodes, the top loop cycles through the field groups. The inner loop in all cases cycles through the data fields themselves.
There are several approaches to modifying the output of the shortcode. When the template is called everything is in the
$this object. (If you’re into it, you can put
<?php echo print_r($this,1) ?> at the top of the template to see the whole data object. Don’t do this on a live site!) You can alter the object directly before it is looped through, but most of the time, it’s more convenient to insert your modifications into the loop.
Shortcodes and Their Templates
Each shortcode uses a template to display it’s output. First, it will look in the theme directory for the template to use, and if it doesn’t find it there, it looks in the plugin directory to use a default template provided by the plugin. It looks for the template based on the name of the file. Part of the file name designates which shortcode it is for and part of it is a name to identify the template so you can have multiple templates for each shortcode if you want. If you don’t specify a name, it is assumed to be “default.”
- [pdb_list] -> pdb-list-default.php
- [pdb_signup] -> pdb-signup-default.php
- [pdb_single] -> pdb-single-default.php
- [pdb_record] -> pdb-record-default.php
If you want to specify the name of the template, you can do it like this:
- [pdb_list template=wide] -> pdb-list-wide.php
Troubleshooting your Custom Template
The #1 problem people face with using custom templates is that the custom template is not getting used. If the plugin can’t find the template, it will use a default template, so it can be difficult to see that the custom template isn’t getting used.
When you are setting up a custom template, you should turn Participants Database debugging on. (This is found in the plugin settings under the advanced tab) When you do this, the page source will show the template that you are using in an HTML comment, like this:
Advanced Template Techniques
In some cases, you want to abandon the loop construction completely or partially. For instance, if you wanted to show some data fields in a special way that a simple loop modification can’t accomplish. For that, we have the PDb_Template class which gives you another set of tools and techniques you can use to build your custom templates.
Take a look at this article if you’re interested in learning about using the PDb_Template class: