Posted on by

Using the PDb_Template class in your custom templates

Participants Database 1.5 has a new utility class that was created to make templating much easier. The default templates used by the plugin are based on loops, much like the standard WordPress templates. Loops are the best way to deal with a situation where you don’t know the number of fields to be shown: the template just keeps showing fields in a repeating pattern until they have all been displayed. Loops are also an efficient way to represent many similar pieces of content.

That may be convenient, but displaying data in a meaningful way often demands you treat parts of the dataset differently. Some of those fields are just more important than others, or perhaps some pieces need to be arranged on the page in a way that best suits the content.

The PDb_Template Class

The PDb_Template class adds several convenient methods for displaying the data in a record. The class is instantiated once for each record, so if the page is a single record, this happens once at the top of the template. For a list of records, the class is instantiated in the loop after the record has been read from the database. I’ll show you an example of a single record template that uses the PDb_Template class for it’s layout.

This template takes several of the more important pieces of information from the record and presents it in a much more readable format. Other fields are logically laid out in groups below that. Below all that, the remaining fields are shown using a shortcode that prints a loop of the groups those fields are in.

This template starts with the instantiation of the Template class near the top, before anything is output. With that, the variable $this_business has all the data of the current record, as well as several convenient functions to help you set up your template.

The main method you will use is print_field('field_name'). Just give it the name of the field you want to print and the method will echo the value formatted for display. It’s mostly self-explanatory.

Raw values are available for calculations or custom formatting using the get_value('field_name') method, demonstrated where we show the number of years the business has been around. Dates are stored as UNIX timestamps, so the raw values from that field needs to be converted to a year for the calculation.

A method named has_content('field_name') can be used to skip over fields that are empty. You see that in use where we want to show the photograph if it exists.

At the end of the template, we use the WP function do_shortcode() to print out the rest of the fields, which are contained in the “More Details” field group. This shortcode uses a special template designed for this purpose: it just does not print the wrapper div because it will appear inside one.

There are a few more convenient methods you can use, which I will demonstrate in the next tutorial on using the PDb_Template utility class.

59 thoughts on “Using the PDb_Template class in your custom templates

  1. Hi Roland,

    Happy to have another recuse to use your amazing plugin. I’ve made a custom template using which I want to use for the pdb_list – it’s currently running as the pdb_single for this list of entries http://henriettab3.sg-host.com/works/ Please could you explain how to go about this: “For a list of records, the class is instantiated in the loop after the record has been read from the database”. Is there an existing template file I use to find this code or some other trick? Thanks so much.

  2. Hey Roland,
    Loving this plugin! Thanks.
    I’m wanting to extend the single-value shortcode so if a tag-type (e.g. div, span, h2…) and class/id are entered, then the value will be output wrapped in that.
    e.g. [pdb_single template="wrap-value" record_id="1" fields="first_heading" tag="h2" tag_class="bold-heading" tag_id="first-heading"]

    … will output :

    first heading field value here

    I see aspect of it here: participants-database\classes\PDb_Field_Group_Item.class.php line 74
    public function print_description( $start_tag = ”, $end_tag = ”, $echo = true ) {
    ….
    allowing:

    $this->group->print_description( ”, ” );

    Can you give hints or direct me to how to implement additional parameters in the shortcode?
    Thanks kindly

    1. Probably the easiest way to do this is to create your own shortcode. This is because the attributes that the pdb_single shortcode can accept are controlled, and there isn’t an easy way to add new attributes. It’s easy enough to add a shortcode that calls another shortcode…for example:

      <?php
      add_shortcode('wrapped_value', 'xnau_wrapped_value' );
      function xnau_wrapped_value( $atts ) {
         $html = '<' . $atts['tag'] . '>';
         $html .= do_shortcode( '[pdb_single record_id=' . $atts['record_id'] . ' fields=' . $atts['fields'] . ' template=bare-value ]' );
         $html .= '</' . $atts['tag'] . '>';
      
         return $html;
      }
      ?>

      The you can use the attributes “record_id” “fields” and “tag” in your custom [wrapped_value] shortcode.

      1. Thank you. I just saw this reply now. I’ll give it a go.

      2. Thanks again Roland. I’ll leave this here for others to learn from also.
        I added the following to my child theme functions.php

        <?php // Flexible wrapping and styling of PDB value
        add_shortcode('wrapped_value', 'xnau_wrapped_value' );
        function xnau_wrapped_value( $atts ) {
           vTag = sanitize_text_field( $atts['tag'] );
           vClass = sanitize_text_field( $atts['class'] );
           vId = sanitize_text_field( $atts['el_id'] );
        
           $html = '';
           $html .= do_shortcode( '[pdb_single record_id=' . $atts['record_id'] . ' fields=' . $atts['fields'] . ' template=bare-value ]' );
           $html .= '';
           
           return $html;
        } ?>

        Then, an example of the shortcode useage:

        [wrapped_value record_id=”1″ fields=”your_title” tag=”h1″ class=”frog” el_id=”frogID”]

  3. Hi, Roland. I’ve found you have ways to get rid of the loop and use separate fields on pdb_list and pdb_single but not the pdb_signup or pdb_record templates? Or do you have a way to do this? Thanks.

    1. Yes, it’s possible to use the PDb_Template class in record and signup templates. The critical difference is you need to use a different method to print the form elements.

      <?php 
      $record = new PDb_Template($this);
      $record->print_form_element('first_name');
       ?>
  4. HI Roland, i have a simple question. I already search in this post/forum and i didnt see a answer.
    I check also the file class named “PDb_Field_Item.class” and i didnt find a answer.

    I use print_field(‘photo_cover_profil’) ?> to print a picture. Its work perfectly. The problem is when i see my code on the front-end i have . How could i remove these span class and just have the link value stored in the DB ?

    Sorry for my english and thanks in adv for your answer.

    1. i resolve the problem its oke now.

      it was in the file PDb_Image.class.php in the folder classes of the plugin.

      replace original fonction with this one

      public function get_image_html()
      {
      switch ($this->display_mode) {
      case ‘both’:
      $pattern =’%5$s %7$s’;
      case ‘filename’:
      $pattern = $this->image_wrap[0] . ‘%6$s’ . $this->image_wrap[1];
      break;
      case ‘none’:
      $pattern = ”;
      break;
      case ‘image’:
      default:
      $pattern = ‘%5$s %7$s’;
      }

      1. I don’t recommend you make changes to the plugin directly, you will lose them when the plugin is updated.

        If you make your changes in a custom template, it will be safe from updates deleting your work.

        If you want to show only the URL of a field, you should use the get_field_prop method of the PDB_Template class, like this:

        $record->get_field_prop('photo_cover_profil','link')

  5. Hi Roland, I hope you can help me. Customising the the ‘pdb-record’ template, I’m trying to skip a field from the table if it has no data. Using the has_content(..) or !empty(..) method.

    while ( $this->have_fields() ) : $this->the_field(); ?>
    has_content(‘reward_am’)) : ?>
    <tr class="<?php …

    1. Sorrry, I meant to show the if statement..

      while ( $this->have_fields() ) : $this->the_field(); ?>
      has_content(‘reward_am’)) : ?>
      <tr class="<? …

      1. It’s hard to show code in comments here, I’m sorry.

        You can use this method in the loop to determine if the field is empty: $this->field->has_content()

        However, that means that the user will not be able to fill in a field that was left empty previously.

        1. Thanks Roland. That worked.

  6. Is there any way (or plug-in) that I can use to change the default look of the registration form? It is very basic and hard to match to the “look” of my website. I would love to be able to change the colors and fonts of the form. Any help would be much appreciated.

    1. Hi Loren,

      Yes, I’m sorry, the plugin doesn’t have any design features like that, it tries to let the theme style the forms, but many themes don’t do a good job with this. I do have an article that helps you with the basic techniques you’ll need to style your forms:

      Simple CSS Techniques for WordPress

  7. I am willing to pay for anyone to help me build out a custom record page. I have an existing php page that displays data fields in a specific format. This page also includes a vertical menu which will navigate to separate pages based on the groups I have set up in Participant Database. Onced I can get the first page set up, I can duplicate for the others. I just need help getting that page started. If you are willing to help, please reply. I need help and just don’t know how to get this done. Anyone?

    1. Hi Gordon, You may have better luck with this on the WP support forum…I am sorry I cannot provide this kind of help due to constraints on my time.

  8. Love your application. I have used it several times. I have a custom php page that has a vertical menu and blocks for content. Is it possible to use this page as my record page to display the data fields and utilize the menu on this page? The page is at http://ibusinessresources.com/plan/userlog. This is a test site until the website is complete.

    1. Do you mean to use that vertical menu to show different groups of fields of the Participants Database record form? If so, it may be possible for you to use a different shortcode for each section, with each on showing only one group of fields. Each group would then be a separate form. For example: [pdb_record groups="main"]

  9. Hi Roland,

    I left a comment earlier it doesn’t look like it got through so apologies for any redundancy here.

    In summary I’m using the PDb_Template class and would like to know how to get the URL information in a website type of field (i.e. containing both Link Text and URL) using either the get_value or print_field methods. Currently when I use either one of these methods it seems to return the Link Text only. I would like to specifically get the URL value.

    Wonderful plugin
    Thank-you,
    Charles

    1. Hello Roland,

      I have the same question as Charles. The URLs aren’t working.

      Thank you,
      Kari

      1. When you are using the PDb_Template class, you can get the link property of the field using the get_field_prop method. For example, if the template object is in $record and your link field was named “website” you can access the URL like this:

        $record->get_field_prop('website','link')

        1. On the flip side, is there a way to

          $record->get_field_prop(‘website’,’link’)

          to print only the link text? Thanks

        2. $record->get_field_prop(‘website’, ‘value’)

          should do it.

Leave a Reply
You have to agree to the comment policy.

Would you like to be notified of followup comments via e-mail? You can also subscribe without commenting.

59 thoughts on “Using the PDb_Template class in your custom templates

  1. Hi Roland,

    Happy to have another recuse to use your amazing plugin. I’ve made a custom template using which I want to use for the pdb_list – it’s currently running as the pdb_single for this list of entries http://henriettab3.sg-host.com/works/ Please could you explain how to go about this: “For a list of records, the class is instantiated in the loop after the record has been read from the database”. Is there an existing template file I use to find this code or some other trick? Thanks so much.

  2. Hey Roland,
    Loving this plugin! Thanks.
    I’m wanting to extend the single-value shortcode so if a tag-type (e.g. div, span, h2…) and class/id are entered, then the value will be output wrapped in that.
    e.g. [pdb_single template="wrap-value" record_id="1" fields="first_heading" tag="h2" tag_class="bold-heading" tag_id="first-heading"]

    … will output :

    first heading field value here

    I see aspect of it here: participants-database\classes\PDb_Field_Group_Item.class.php line 74
    public function print_description( $start_tag = ”, $end_tag = ”, $echo = true ) {
    ….
    allowing:

    $this->group->print_description( ”, ” );

    Can you give hints or direct me to how to implement additional parameters in the shortcode?
    Thanks kindly

    1. Probably the easiest way to do this is to create your own shortcode. This is because the attributes that the pdb_single shortcode can accept are controlled, and there isn’t an easy way to add new attributes. It’s easy enough to add a shortcode that calls another shortcode…for example:

      <?php
      add_shortcode('wrapped_value', 'xnau_wrapped_value' );
      function xnau_wrapped_value( $atts ) {
         $html = '<' . $atts['tag'] . '>';
         $html .= do_shortcode( '[pdb_single record_id=' . $atts['record_id'] . ' fields=' . $atts['fields'] . ' template=bare-value ]' );
         $html .= '</' . $atts['tag'] . '>';
      
         return $html;
      }
      ?>

      The you can use the attributes “record_id” “fields” and “tag” in your custom [wrapped_value] shortcode.

      1. Thank you. I just saw this reply now. I’ll give it a go.

      2. Thanks again Roland. I’ll leave this here for others to learn from also.
        I added the following to my child theme functions.php

        <?php // Flexible wrapping and styling of PDB value
        add_shortcode('wrapped_value', 'xnau_wrapped_value' );
        function xnau_wrapped_value( $atts ) {
           vTag = sanitize_text_field( $atts['tag'] );
           vClass = sanitize_text_field( $atts['class'] );
           vId = sanitize_text_field( $atts['el_id'] );
        
           $html = '';
           $html .= do_shortcode( '[pdb_single record_id=' . $atts['record_id'] . ' fields=' . $atts['fields'] . ' template=bare-value ]' );
           $html .= '';
           
           return $html;
        } ?>

        Then, an example of the shortcode useage:

        [wrapped_value record_id=”1″ fields=”your_title” tag=”h1″ class=”frog” el_id=”frogID”]

  3. Hi, Roland. I’ve found you have ways to get rid of the loop and use separate fields on pdb_list and pdb_single but not the pdb_signup or pdb_record templates? Or do you have a way to do this? Thanks.

    1. Yes, it’s possible to use the PDb_Template class in record and signup templates. The critical difference is you need to use a different method to print the form elements.

      <?php 
      $record = new PDb_Template($this);
      $record->print_form_element('first_name');
       ?>
  4. HI Roland, i have a simple question. I already search in this post/forum and i didnt see a answer.
    I check also the file class named “PDb_Field_Item.class” and i didnt find a answer.

    I use print_field(‘photo_cover_profil’) ?> to print a picture. Its work perfectly. The problem is when i see my code on the front-end i have . How could i remove these span class and just have the link value stored in the DB ?

    Sorry for my english and thanks in adv for your answer.

    1. i resolve the problem its oke now.

      it was in the file PDb_Image.class.php in the folder classes of the plugin.

      replace original fonction with this one

      public function get_image_html()
      {
      switch ($this->display_mode) {
      case ‘both’:
      $pattern =’%5$s %7$s’;
      case ‘filename’:
      $pattern = $this->image_wrap[0] . ‘%6$s’ . $this->image_wrap[1];
      break;
      case ‘none’:
      $pattern = ”;
      break;
      case ‘image’:
      default:
      $pattern = ‘%5$s %7$s’;
      }

      1. I don’t recommend you make changes to the plugin directly, you will lose them when the plugin is updated.

        If you make your changes in a custom template, it will be safe from updates deleting your work.

        If you want to show only the URL of a field, you should use the get_field_prop method of the PDB_Template class, like this:

        $record->get_field_prop('photo_cover_profil','link')

  5. Hi Roland, I hope you can help me. Customising the the ‘pdb-record’ template, I’m trying to skip a field from the table if it has no data. Using the has_content(..) or !empty(..) method.

    while ( $this->have_fields() ) : $this->the_field(); ?>
    has_content(‘reward_am’)) : ?>
    <tr class="<?php …

    1. Sorrry, I meant to show the if statement..

      while ( $this->have_fields() ) : $this->the_field(); ?>
      has_content(‘reward_am’)) : ?>
      <tr class="<? …

      1. It’s hard to show code in comments here, I’m sorry.

        You can use this method in the loop to determine if the field is empty: $this->field->has_content()

        However, that means that the user will not be able to fill in a field that was left empty previously.

        1. Thanks Roland. That worked.

  6. Is there any way (or plug-in) that I can use to change the default look of the registration form? It is very basic and hard to match to the “look” of my website. I would love to be able to change the colors and fonts of the form. Any help would be much appreciated.

    1. Hi Loren,

      Yes, I’m sorry, the plugin doesn’t have any design features like that, it tries to let the theme style the forms, but many themes don’t do a good job with this. I do have an article that helps you with the basic techniques you’ll need to style your forms:

      Simple CSS Techniques for WordPress

  7. I am willing to pay for anyone to help me build out a custom record page. I have an existing php page that displays data fields in a specific format. This page also includes a vertical menu which will navigate to separate pages based on the groups I have set up in Participant Database. Onced I can get the first page set up, I can duplicate for the others. I just need help getting that page started. If you are willing to help, please reply. I need help and just don’t know how to get this done. Anyone?

    1. Hi Gordon, You may have better luck with this on the WP support forum…I am sorry I cannot provide this kind of help due to constraints on my time.

  8. Love your application. I have used it several times. I have a custom php page that has a vertical menu and blocks for content. Is it possible to use this page as my record page to display the data fields and utilize the menu on this page? The page is at http://ibusinessresources.com/plan/userlog. This is a test site until the website is complete.

    1. Do you mean to use that vertical menu to show different groups of fields of the Participants Database record form? If so, it may be possible for you to use a different shortcode for each section, with each on showing only one group of fields. Each group would then be a separate form. For example: [pdb_record groups="main"]

  9. Hi Roland,

    I left a comment earlier it doesn’t look like it got through so apologies for any redundancy here.

    In summary I’m using the PDb_Template class and would like to know how to get the URL information in a website type of field (i.e. containing both Link Text and URL) using either the get_value or print_field methods. Currently when I use either one of these methods it seems to return the Link Text only. I would like to specifically get the URL value.

    Wonderful plugin
    Thank-you,
    Charles

    1. Hello Roland,

      I have the same question as Charles. The URLs aren’t working.

      Thank you,
      Kari

      1. When you are using the PDb_Template class, you can get the link property of the field using the get_field_prop method. For example, if the template object is in $record and your link field was named “website” you can access the URL like this:

        $record->get_field_prop('website','link')

        1. On the flip side, is there a way to

          $record->get_field_prop(‘website’,’link’)

          to print only the link text? Thanks

        2. $record->get_field_prop(‘website’, ‘value’)

          should do it.

Leave a Reply
You have to agree to the comment policy.

Would you like to be notified of followup comments via e-mail? You can also subscribe without commenting.