For any kind of deep customization of a shortcode’s output, you will need to create a custom template to control the HTML and functionality of the shortcode display. This will require some knowledge of php, HTML and possibly also CSS and Javascript.
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?
The best place to put your custom templates is:
/wp-content/participants-database-templates/
You will need to use FTP or your file manager (usually found in your hosting control panel) to upload your custom template to the correct location. Create the participants-database-templates folder if you need to.
For Multisite installs, each blog in the network will have its own folder based on the ID of the site, for example:
.../wp-content/participants-database-templates/blog-18/pdb-list-custom.phpCreating a custom template
The plugin has its own built-in 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 plugin 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 plugin templates directory. The “default” template is the one that will be used if the shortcode does not specify a template.
These built-in 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.
The custom templates must be located in the /wp-content/participants-database-templates folder.
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.
All we have to do to make a custom template is to copy one of the plugin’s templates into the Participants Database custom template directory.
For example, with the list shortcode, the path to your custom template will be something like this:wp-content/participants-database-templates/pdb-list-default.php
The plugin will look there first for the template to use, so in this example, the template in the custom template folder will get used, not the built-in template.
If you create a custom template, it is a good practice to give it a unique name so you will know at a glance that it is different from the built-in plugin templates.
Naming the Template File
It is very important to understand how template file naming works. Each template file name begins with “pdb-” and then the name of the shortcode that the template is for. This will be something like “list” or “single” preceeded by a hyphen.
The last part of the name is the name of the template. This can be anything that is a legal name, so most text characters and numerals are allowed (including things like accented or asian characters). What will not be allowed is punctuation and symbols. The only symbol character you can use is hyphen -. This is determined by the file naming restrictions of the server.
The “name” of the template will be what you use in the shortcode to to use a particular template. For example, if your template file is named pdb-list-my-custom-template.php you would call that in the shortcode like this:
[pdb_list template="my-custom-template" ]
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: