Tutorial: A Custom Single Record Template

The Tutorial

There are many, many ways to use Participants Database custom  templates. As one example, 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
 */
?>

<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><?php $this->field->print_label() ?></dt>

      <dd><?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!