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.

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

  1. Roland,
    I am working on a PBD-record-custom.php template where I will try to use the PDb_template class (I think) to place individual editable fields into a table. How do i display the field contents allowing the member to edit each field?

     $record->print_form_element(‘is_100_date’);?>

    This works for displaying the field, how do I allow it to be edited?

    Thanks for this plugin… I have used it before to display a large table but trying to make it interactive is a bit more involved.

    1. This tutorial is about setting up a way to display records, not edit them.

      In order to show a record that can be edited, you must use the [pdb_record] shortcode (which must be accessed in such a way as to be able to identify the user. Typically, this is with the user’s “private link”) You can customize that form by customizing the template for that shortcode. This template is required to provide all the data structures needed to present an editable record.

      I don’t offer any tutorials on doing this, it’s too challenging for novice coders, so you’ll be on your own there.

      1. I am not looking for a tutorial. I have been though the [pdb_record] shortcode. and have made changes to it. No big deal, it is very straight forward. What is missing is how to display and single editable field outside of the loops?
        Yes the user will access via their private link….

        How can I show the first_name field in that template and allow the user to edit that field? Independent of the loops used to display the fields generically?

        If this can not be done then I will look elsewhere for a solution.

        1. The method you had in your original comment should work to display the input. I thought you were having trouble because you were placing the input in the incorrect context, but it sounds like you got that. What exactly is happening when you use the print_form_element method?

        2. I got it…… I had to remove the two loops (groups, fields) so the field was not displayed twice, i think this was the issue. And, needed to have at least the 4 required fields also on the page. And of course the Submit button.
          I have a lot of coding to get where i need to be replicating an existing format but this gets me the tools i need to do it.

          Question, Where can i find all of the variables available in the PDb_template such as the field ‘title’?

          I appreciate your quick replies…. THANKS

        3. I have a page for the class here The Template Helper Class, but you may want to go to the code directly to really understand how it works. It’s way more complicated than it needs to be, I’m sorry, it had to be tacked on to existing code that wasn’t originally designed to be extended in this way.

        4. Hi Roland, i have made very good progress modifying your record-default template to fit our formatting requirements. Yes I renamed it!
          I have a question:
          One field is read only to be edited by editors not the member. Members do need to see this field.
          We do not wish to give an editor access to the WP ‘back-end’ but would prefer that the one field is edited via a front-end template. My custom record template would work, as editors need to see other member’s fields before modifying the field.
          Is there a way to either turn off the read only flag for that field in a template for editors OR change the field to read/write and display the field contents as read-only in the members (non-editor) record page.
          Possible?
          This looks like the perfect db for storing our data. Thank you.

        5. This is possible in the template. Just before the field is displayed, you can set the readonly of a field with

          $this->field->set_readonly(true);

          so, you’d first check the user role, then set this as needed.

  2. 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.

  3. 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”]

  4. 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');
       ?>

  5. 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')

  6. 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.

  7. 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

  8. 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.

  9. 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"]

  10. 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.

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

  1. Roland,
    I am working on a PBD-record-custom.php template where I will try to use the PDb_template class (I think) to place individual editable fields into a table. How do i display the field contents allowing the member to edit each field?

     $record->print_form_element(‘is_100_date’);?>

    This works for displaying the field, how do I allow it to be edited?

    Thanks for this plugin… I have used it before to display a large table but trying to make it interactive is a bit more involved.

    1. This tutorial is about setting up a way to display records, not edit them.

      In order to show a record that can be edited, you must use the [pdb_record] shortcode (which must be accessed in such a way as to be able to identify the user. Typically, this is with the user’s “private link”) You can customize that form by customizing the template for that shortcode. This template is required to provide all the data structures needed to present an editable record.

      I don’t offer any tutorials on doing this, it’s too challenging for novice coders, so you’ll be on your own there.

      1. I am not looking for a tutorial. I have been though the [pdb_record] shortcode. and have made changes to it. No big deal, it is very straight forward. What is missing is how to display and single editable field outside of the loops?
        Yes the user will access via their private link….

        How can I show the first_name field in that template and allow the user to edit that field? Independent of the loops used to display the fields generically?

        If this can not be done then I will look elsewhere for a solution.

        1. The method you had in your original comment should work to display the input. I thought you were having trouble because you were placing the input in the incorrect context, but it sounds like you got that. What exactly is happening when you use the print_form_element method?

        2. I got it…… I had to remove the two loops (groups, fields) so the field was not displayed twice, i think this was the issue. And, needed to have at least the 4 required fields also on the page. And of course the Submit button.
          I have a lot of coding to get where i need to be replicating an existing format but this gets me the tools i need to do it.

          Question, Where can i find all of the variables available in the PDb_template such as the field ‘title’?

          I appreciate your quick replies…. THANKS

        3. I have a page for the class here The Template Helper Class, but you may want to go to the code directly to really understand how it works. It’s way more complicated than it needs to be, I’m sorry, it had to be tacked on to existing code that wasn’t originally designed to be extended in this way.

        4. Hi Roland, i have made very good progress modifying your record-default template to fit our formatting requirements. Yes I renamed it!
          I have a question:
          One field is read only to be edited by editors not the member. Members do need to see this field.
          We do not wish to give an editor access to the WP ‘back-end’ but would prefer that the one field is edited via a front-end template. My custom record template would work, as editors need to see other member’s fields before modifying the field.
          Is there a way to either turn off the read only flag for that field in a template for editors OR change the field to read/write and display the field contents as read-only in the members (non-editor) record page.
          Possible?
          This looks like the perfect db for storing our data. Thank you.

        5. This is possible in the template. Just before the field is displayed, you can set the readonly of a field with

          $this->field->set_readonly(true);

          so, you’d first check the user role, then set this as needed.

  2. 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.

  3. 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”]

  4. 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');
       ?>

  5. 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')

  6. 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.

  7. 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

  8. 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.

  9. 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"]

  10. 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.