Using Participants Database Custom Templates

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.

>>Jump to the tutorial…
>>Which template to use?

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 either an FTP client or a file manager in your hosting control panel.

The plugin has it’s own set of templates that it uses. 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 your theme directory, into a directory named “templates.” For the list shortcode, the path to your custom template will be something like
wp-content/themes/YOUR_THEME/templates/pdb-list-default.php
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.

Please note that theme updates may delete this directory, so unless you don’t plan to use automatic updates on your theme, or your current theme is a child theme, you should use a child theme to hold all your modifications. This 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 <pre><?php echo print_r($this,1) ?></pre> 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.

The Tutorial

There are many, many ways to customize these templates, but I will walk you through a simple customization so you can set one up that works and better understand the basic process.

A common request is how to hide fields from users unless they are logged in. I’ll show you how to do this with the [pdb_single] shortcode. We will set it up so that the email address will only be shown if the user is logged in.

  1. Create your template file by copying the file from the plugin to your theme. To do this, you must use your FTP or “file manager” in your hosting control panel. The file you are looking for is in /wp-content/plugins/participants-database/templates/pdb-single-default.php. In your theme directory /wp-content/themes/YOUR_THEME/ create a folder named “templates” if one does not already exist. Copy the template file into this folder so you end up with: wp-content/themes/YOUR_THEME/templates/pdb-single-default.php
  2. Edit your new template. You can do this in WordPress in the “appearance/editor” or you can use whatever method you prefer to edit website files. The plugin will be using this file to display the [pdb_single] output.
  3. Find the place to put your edit. The template loops through the field groups, then in each group, it loops through the fields to show. We insert our code just before the template would display the field so we can change how it displays. Look for a line that has: $this->the_field(); That is what defines the next field to display, and so we want to put our code right after that.
  4. See if the field is the one you want. We do this by checking the “name” of the field, which is certain to be the right one because it is a unique identifier. To do that, we use: if ($this->field->name == 'email') so we are matching the name of the current field to the field we are looking for.
  5. Change the display of the field. If we find the field, now we can do something with it. In this case, we check to see if the user is logged in and then alter the field’s display accordingly: if (! is_user_logged_in()) $this->field->value = 'Registered Users Only'; This replaces the field’s normal value with the text given so non-registered users can’t see the email address.

So, the final template will look this this:

<?php
/*
 * custom template for displaying a single record, hiding the email address from non-logged-in users
 */

// define an array of fields to exclude here
$exclude = array();

?>

<div class="wrap <?php echo $this->wrap_class ?>">

  <?php while ( $this->have_groups() ) : $this->the_group(); ?>

  <div class="section" id="<?php echo Participants_Db::$css_prefix.$this->group->name ?>">

    <?php $this->group->print_title( '<h2>', '</h2>' ) ?>

    <?php $this->group->print_description( '<p>', '</p>' ) ?>

      <?php while ( $this->have_fields() ) : $this->the_field();

          // here is our custom code
          if ( $this->field->name == 'email' ) {
            if ( ! is_user_logged_in() ) $this->field->value = 'Registered Users Only';
          }

          // skip any field found in the exclude array
          if ( in_array( $this->field->name, $exclude ) ) continue;

          // CSS class for empty fields
	  $empty_class = $this->get_empty_class( $this->field );

      ?>
    <dl class="<?php echo Participants_Db::$css_prefix.$this->field->name.' '.$this->field->form_element.' '.$empty_class?>">

      <dt class="<?php echo $this->field->name.' '.$empty_class?>"><?php $this->field->print_label() ?></dt>

      <dd class="<?php echo $this->field->name.' '.$empty_class?>"><?php $this->field->print_value() ?></dd>

    </dl>

    	<?php endwhile; // end of the fields loop ?>

  </div>

  <?php endwhile; // end of the groups loop ?>

</div>

This is an extremely simple example, but it gives you the basics. Now you can create your own customizations!

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

Leave your comment

Please note: comments are moderated by someone who is usually pretty busy and may not appear for several hours.

Required.

Required. Not published.

If you have one.



css.php