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.

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

  1. I really love this plugin and have been learning a lot about coding and stuff to try and set up the database for my boss’s website. I really appreciate all the tutorials and information you’ve provided to help us figure this stuff out :)

    Just wondering if there are any tutorials specifically for the pdb_single template customization aside from this one? I’m trying to set up a template for the single result page, but i’m running into trouble getting it to display correctly and I’d like to sort out what I’m doing wrong, but I only have this example to refer to. I figured if i could find another example for displaying customized results, I could compare the two to my in-progress template and figure out what i’m doing wrong.

    1. Hi Jennifer,

      I’m unsure about the exact nature of the issue you’re seeing, so I can’t be too specific…but if it is a display/formatting issue, chances are what you need to do is not so much look at using a custom template as work with the CSS to get it to display the way you want.

      A custom template is needed if you need to do things like dynamically determine which fields to show or change the way things are displayed based on the contents of the record…that kind of thing.

      1. Ah, yes. Sorry for the confusion. I’m not worried about colors or anything, just trying to get the fields to display in a certain layout/order. When i tried to customize this template, for instance, some of my fields disappeared entirely, but it depended on which field was in what order on the template as to which ones would then disappear when viewing the pdb_single page. Also, despite it starting with and moving down to , the results kept getting larger instead of smaller. I’m obviously implementing something wrong, so I had hoped to find another example of a pdb_single template to give me an idea of what’s amiss.

        Honestly, I was hoping to get the pdb_single records to display kind of like the pdb_list template example for doctors (https://xnau.com/using-the-pdb_template-helper-class-in-a-custom-list-template/) but I’m not having much luck getting it to look that way. I’m not an expert by any stretch of the imagination, so it’s probably quite simple and just eluding me.

        1. Sorry, of course it wouldn’t display the codes i used as examples, my mistake.

          ” Also, despite it starting with h1/h3 class and moving down to p class , the results kept getting larger instead of smaller.”

        2. You may know this, but setting the order of fields is done on the Manage Database Fields page. Also note that fields are always grouped, so it’s important to order the groups the way you want then to appear. It is difficult to arbitrarily set the order of the fields in the template.

          The sizing problem you’re seeing sounds like the tags are not getting closed in the HTML.

          From what I’m hearing you want to do, I would suggest you use the built-in “bootstrap” template for your single record shortcode, and then achieve the layout using CSS. It is possible using CSS Flexbox parameters.

  2. Hi Roland,



    This is a question is in regard to customising a record template so it is editable, as posed by Dennis Spiess on 17th March 2020 above.



    I have followed all his actions but I am having problems in finding where to place his code line
    ( $record->print_form_element(‘is_100_date’);?> ) in the custom template.

 (pdb-record-default)

    Would you have an idea on the best line to insert that code line? Or maybe Dennis may see this post and also offer assistance.

Thank you

    1. Hi Philip,

      I’m sorry, I can’t really help you with this, not only do I not know how to answer your question (too general), but I don’t provide support for custom code.

      1. Thank you mate,

        Maybe Dennis might see this post and offer his line of action.
        Cheers

      2. Hi again Roland,
        Thanks for your ongoing support and hopefully you could help with this issue.

        I have custom templates for the [pdb_record template=' '] shortcode. It seems when using the custom template and I save a record after editing it, , it deletes the all the data in that record and returns to the default values.

        Within the template I am also using…

        $record->get_value(‘fieldname’)
        $record->print_value(‘fieldname’)

        so I’m not sure if these code lines are affecting the saving function or if there is something else that you may have experienced to this effect that may help resolve this issue.

        Any ideas on what is the cause and possible solutions?

        1. Assuming you are certain there are no problems in your custom template (that part is up to you), you’d turn plugin debugging on, then test your record save. Check the log, you’ll see what happened.

          I don’t know of any issue that would cause this specific effect. Make sure the template is not missing any of the data, it sounds like maybe what is happening is it’s creating a new record, which it would do if the record ID was missing, for example. It is not at all normal to replace a records existing data with default data.

        2. There is no problem with the save function when using…
          [pdb_record fields='field1,field2,field3'] shortcode.

          I made a quick 2 minute screen recording to help with explaining.
          https://youtu.be/w0SXZDPaxAE

        3. As far as I can see from that, there is a problem with your custom template. You can use the debugging log to see what’s happening, but you need to make sure your custom template does not contain coding errors.

Leave a Reply to Roland Barker Cancel reply

Your email address will not be published. Required fields are marked *

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

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

  1. I really love this plugin and have been learning a lot about coding and stuff to try and set up the database for my boss’s website. I really appreciate all the tutorials and information you’ve provided to help us figure this stuff out :)

    Just wondering if there are any tutorials specifically for the pdb_single template customization aside from this one? I’m trying to set up a template for the single result page, but i’m running into trouble getting it to display correctly and I’d like to sort out what I’m doing wrong, but I only have this example to refer to. I figured if i could find another example for displaying customized results, I could compare the two to my in-progress template and figure out what i’m doing wrong.

    1. Hi Jennifer,

      I’m unsure about the exact nature of the issue you’re seeing, so I can’t be too specific…but if it is a display/formatting issue, chances are what you need to do is not so much look at using a custom template as work with the CSS to get it to display the way you want.

      A custom template is needed if you need to do things like dynamically determine which fields to show or change the way things are displayed based on the contents of the record…that kind of thing.

      1. Ah, yes. Sorry for the confusion. I’m not worried about colors or anything, just trying to get the fields to display in a certain layout/order. When i tried to customize this template, for instance, some of my fields disappeared entirely, but it depended on which field was in what order on the template as to which ones would then disappear when viewing the pdb_single page. Also, despite it starting with and moving down to , the results kept getting larger instead of smaller. I’m obviously implementing something wrong, so I had hoped to find another example of a pdb_single template to give me an idea of what’s amiss.

        Honestly, I was hoping to get the pdb_single records to display kind of like the pdb_list template example for doctors (https://xnau.com/using-the-pdb_template-helper-class-in-a-custom-list-template/) but I’m not having much luck getting it to look that way. I’m not an expert by any stretch of the imagination, so it’s probably quite simple and just eluding me.

        1. Sorry, of course it wouldn’t display the codes i used as examples, my mistake.

          ” Also, despite it starting with h1/h3 class and moving down to p class , the results kept getting larger instead of smaller.”

        2. You may know this, but setting the order of fields is done on the Manage Database Fields page. Also note that fields are always grouped, so it’s important to order the groups the way you want then to appear. It is difficult to arbitrarily set the order of the fields in the template.

          The sizing problem you’re seeing sounds like the tags are not getting closed in the HTML.

          From what I’m hearing you want to do, I would suggest you use the built-in “bootstrap” template for your single record shortcode, and then achieve the layout using CSS. It is possible using CSS Flexbox parameters.

  2. Hi Roland,



    This is a question is in regard to customising a record template so it is editable, as posed by Dennis Spiess on 17th March 2020 above.



    I have followed all his actions but I am having problems in finding where to place his code line
    ( $record->print_form_element(‘is_100_date’);?> ) in the custom template.

 (pdb-record-default)

    Would you have an idea on the best line to insert that code line? Or maybe Dennis may see this post and also offer assistance.

Thank you

    1. Hi Philip,

      I’m sorry, I can’t really help you with this, not only do I not know how to answer your question (too general), but I don’t provide support for custom code.

      1. Thank you mate,

        Maybe Dennis might see this post and offer his line of action.
        Cheers

      2. Hi again Roland,
        Thanks for your ongoing support and hopefully you could help with this issue.

        I have custom templates for the [pdb_record template=' '] shortcode. It seems when using the custom template and I save a record after editing it, , it deletes the all the data in that record and returns to the default values.

        Within the template I am also using…

        $record->get_value(‘fieldname’)
        $record->print_value(‘fieldname’)

        so I’m not sure if these code lines are affecting the saving function or if there is something else that you may have experienced to this effect that may help resolve this issue.

        Any ideas on what is the cause and possible solutions?

        1. Assuming you are certain there are no problems in your custom template (that part is up to you), you’d turn plugin debugging on, then test your record save. Check the log, you’ll see what happened.

          I don’t know of any issue that would cause this specific effect. Make sure the template is not missing any of the data, it sounds like maybe what is happening is it’s creating a new record, which it would do if the record ID was missing, for example. It is not at all normal to replace a records existing data with default data.

        2. There is no problem with the save function when using…
          [pdb_record fields='field1,field2,field3'] shortcode.

          I made a quick 2 minute screen recording to help with explaining.
          https://youtu.be/w0SXZDPaxAE

        3. As far as I can see from that, there is a problem with your custom template. You can use the debugging log to see what’s happening, but you need to make sure your custom template does not contain coding errors.

Leave a Reply to Roland Barker Cancel reply

Your email address will not be published. Required fields are marked *

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