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. Hi Roland,

    Really great plugin. We’re using it to display Organizations and their logos. Nice that this DB plugin has the ability to upload images on signup.

    I’ve been using the PDb_Template class to customize the display of records.

    My question pertains to website fields which contain both “Link Text” and “Url” information. How does one extract the individual components of this field type?

    For example if use the get_value or print_field methods it just provides the “Link Text” component of the field. How do I get the value of the URL?

    Thank-you,
    Charles

    1. When you use get_value you’ll get an array of the two values, the first of which is the URL.

      1. Hi Roland,
        Just tried this code as a test to access the two values of the array:
        $website_address = $this_swrecord->get_value(‘website’);
        echo “website URL = ” . $website_address[0] . “”;
        echo “website Link Text = ” . $website_address[1] . “”;

        The result was the first two letters of the Link Text i.e. which was “Link” so it came out:
        website URL = L
        website Link Text = i

        Can you help me with the syntax here?

        Regards and Thank-you,
        Charles

        1. I’m very sorry it took me so long to get back to you on this. The correct code to use to get the URL from a link field is something like this:

          $this_swrecord->get_field_prop('website','link');

        2. Hi Roland,
          Thanks for your response and apologies for my tardy reply. May I humbly suggest that all the methods and variable types associated with the PDb_Template class be documented somewhere…sorry if they already are and I just couldn’t find it.

          Because I only had around 70 records I ended up creating a new text field for holding website url manually copied them over. Then I deleted the website field…It was troublesome on signup because people were often confusing the URL and Link Text field anyways. Now there’s only one field, i.e. just the URL.

          Thank-you and Regards,
          Charles

  2. Hi Roland,

    Thanks again for the great plugin. This might seem like a simple question, but I’ve been digging through the plugin files for hours for a clue and haven’t gotten it to work yet. I am looking for a way to print a URL that points to a custom single record template I created. I’ve used get_edit_link(‘/custom-template/’); ?> to print the edit link successfully, but I’m looking for the record ID (“?pdb=xxxx”) instead of the private ID (“?pid=xxxxxx”). Am I missing something?

    Thanks in advance!

    1. I’m assuming this is something your are doing in a custom list template. You will have to build that URL using the permalink for the page you want them to go to, and adding the record ID to the URL as '?pid=' . $this->record->id

      It’s also possible to set the custom destination for all single record links in the list by using the ‘single_record_link” attribute in the shortcode: [pdb_list single_record_page="custom-single"]

  3. I need to get the value of a field and use it within another shortcode to play a audio file. Here’s what I’ve got so far, but it’s not working (the do_shortcode works if I put a url within the “” but I want the value to change for each participant so the url value needs to come from the audio field.)

    ?php $audio = $this_chart->participant_values[‘audio’]; echo do_shortcode( ‘[sc_embed_player fileurl=”‘.$audio.'”]’); ?>

    The shortcode would be [sc_embed_player fileurl=”URL OF THE MP3 FILE”]

    Thanks!

    1. You’re very close… to get the value from the record, you need to use $this->participant_values['audio']

      1. Thanks so much for the speedy reply, we’re up and running.

  4. I have the same issue as Kevin, I’m using numeric value for one field (a year) but it’s not a required field as we don’t always have the info, so it defaults to “0” . I am adapting a template for my single record page which is working as I need, except this field. What I would like is:

    (in english!)
    if the value is equal to 0 then return nothing and print “.” ,
    else print “in” and then return the value

    I tried the following:

    (‘year_arranged’) ==0 ) : ?> .
    in print_field(‘year_arranged’) ?>

    I’ve also tried =0 =”0″ and Null instead of zero, etc.

    Is there a way to achieve this? Otherwise I think I have to add a new text field to replace the numeric then it’s much simpler to ask if the field (has_content)? I’ve looked at your other templates but can’t find enlightenment.

    Other code I have which works includes:

    KEY: print_field(‘key’) ?>
    SOLOS: print_field(‘solos’) ?>
    has_content(‘feature’)) : ?>FEATURE: print_field(‘feature’) ?>

    1. The system as missed out most of the code … Here it is without the sharp brackets replaced by ( )to to see if it works this time.

      (?php if ($this_chart->has_content(‘year_arranged’) >0 ) : ?)
      (?php $this_chart->print_field(‘year_arranged’) ?)
      (?php endif ?)

    2. I’m sorry, the comment system doesn’t do code too well.

      Something like this should work:

      get_value('year_arranged') != '0' ) : ?>
      in print_field('year_arranged') ?>
      
      .
      
      1. Thanks very much Roland, it works a treat! Just what I needed.

  5. Hi,

    I love this plugin, it works really really nice for me.
    I’ve one question, how can i change the date field style? I would like to have it as a instead of .

    Thanks a lot for you help and keep up the good work.

    1. The plugin uses the global date format, which is set in your WordPress General Settings.

      1. Thanks for your command Roland, i meant that i would like to change date from a text field to a calendar field. People are typing in the wrong dates at this moment. With a calendar date they wont type, they would choose a date. Thats more foolproof for me.

        Thanks in advance.

        1. OK, I get it: try the Datepicker add-on.

  6. Great plugin! I’m a novice with PHP and am having difficulty hiding a div tag when the field is empty.

    1. Sorry, I just realized I left something off.

      I need to hide div tag when field value is null, empty or 0. I tried the “has_content”, however it’s not working. I assume because my values default to 0.

    2. Kevin, I’m sorry I can’t be of much help without seeing your code. You can do this with CSS, you don’t need to use a custom template. Take a look at the HTML, you’ll see that empty fields have a classname that you can use to hide them.

      1. I guess the problem I’m having is because I’m using a numeric field and it’s defaulting to ‘0’. Furthermore, with the template I created, the ‘blank-field’ class doesn’t appear even when I change the field to text.

        Is there a way to hide the div based on a value of ‘0’?

        1. Kevin,

          The easiest way to do this is with a custom template that inspects the value and adds a classname based on that. It could also be done with javascript. CSS can’t handle a situation like this. I have a tutorial that shows how to add the empty field class. The tutorial is for a different purpose, but you can see how that can be done.

  7. Roland,
    What about using this in the combo multisearch? Is it possible to modify the multisearch template so that we can format the results in a customized format for readers?

    1. Yes, you can use a custom template for combo multisearch.

  8. Hi,
    Thank you for your very useful plugin.
    I have a problem with it.
    I created a custom template using pdb-list-default.php.
    However when I use the shortcode calling it, twice in the same page, the php fails entirely in the page. It works fine when called only once.
    Can you imagine a reason why I cannot use the pdb-list shortcode more than once?

    Thanks again
    Daniel

    1. Hi again,
      I have found the culprit. I created and used a function in the template php code. I suppose the problem is related to the Object Oriented PHP.
      Is there a way to write functions and use them in the php template files ?
      Thank you
      Daniel

      1. If you are embedding functions in your templates, and you will be using that template more than once on a page, you need to wrap it in a conditional so that it does not get declared twice…for instance:

        <?php
        if ( ! function_exists( 'my_function' ) {
        function my_function() {}
        }
        ?>

        That way it will only try to define the function if it hasn’t been defined before.

        1. Thank you very much.
          I should have thought of it, the template code being included.

  9. Hello,

    Your plugins is really useful, it helps me a lot. Thank you.

    Currently, I’m using it as a database to store my guests information.

    I have a question.

    After I set “[pdb_list search=true display_count=true template=detailed list_limit=100] on “page1” on my website, I used [pdb_single] to display the single record on “page2”. How can I update the data displayed on “page2”?
    I don’t use signup option or any other option as the list can be accessible and update by anyone.

    Thank you.

    1. This is explained in the “Setup Guide”

      Look at the settings under the “list display settings” tab, set the “Single Record Link Field” to the field you want them to click to go to the single record page. Then set the “Single Record Page” to the page where your [pdb_single] shortcode is. Now, when someone clicks on the link in the list, they will go to the single record page and see all the record’s information.

  10. Hi,

    I used this plugins for somethig else… and its really nice. I had to modify the templates a bit too, and this guide comes really handy.

    Now i have one question.

    I have one field which can be common to more than 2 participants. that field is called ‘member_age’,

    In this single list view, i want to display all the other member who have the same age as the person being displayed here. Is it possible to attain this?

    If so how will i code it to do the same? to list only the names of the people sharing the same age.

    Thanks

    1. OK, since you already know how to work with custom templates, I’ll show you how you can do this in the single record template.

      In the template, you can use the list shortcode, and use the age value to show only those other persons of the same age.

      You will have to change this to fit the details of your setup, but it will print the list, so put this where you want the list to go. If you want to give the list a special format, you can use a custom template for the list, too. Just includes that in the list shortcode.

      <?php
      $age = $this->participant_values['age'];
      echo do_shortcode( '[pdb_list filter="age=' . $age . '&id!' . $this->particpant_id . '" fields="first_name,last_name"]' );
      ?>

Leave a 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. Hi Roland,

    Really great plugin. We’re using it to display Organizations and their logos. Nice that this DB plugin has the ability to upload images on signup.

    I’ve been using the PDb_Template class to customize the display of records.

    My question pertains to website fields which contain both “Link Text” and “Url” information. How does one extract the individual components of this field type?

    For example if use the get_value or print_field methods it just provides the “Link Text” component of the field. How do I get the value of the URL?

    Thank-you,
    Charles

    1. When you use get_value you’ll get an array of the two values, the first of which is the URL.

      1. Hi Roland,
        Just tried this code as a test to access the two values of the array:
        $website_address = $this_swrecord->get_value(‘website’);
        echo “website URL = ” . $website_address[0] . “”;
        echo “website Link Text = ” . $website_address[1] . “”;

        The result was the first two letters of the Link Text i.e. which was “Link” so it came out:
        website URL = L
        website Link Text = i

        Can you help me with the syntax here?

        Regards and Thank-you,
        Charles

        1. I’m very sorry it took me so long to get back to you on this. The correct code to use to get the URL from a link field is something like this:

          $this_swrecord->get_field_prop('website','link');

        2. Hi Roland,
          Thanks for your response and apologies for my tardy reply. May I humbly suggest that all the methods and variable types associated with the PDb_Template class be documented somewhere…sorry if they already are and I just couldn’t find it.

          Because I only had around 70 records I ended up creating a new text field for holding website url manually copied them over. Then I deleted the website field…It was troublesome on signup because people were often confusing the URL and Link Text field anyways. Now there’s only one field, i.e. just the URL.

          Thank-you and Regards,
          Charles

  2. Hi Roland,

    Thanks again for the great plugin. This might seem like a simple question, but I’ve been digging through the plugin files for hours for a clue and haven’t gotten it to work yet. I am looking for a way to print a URL that points to a custom single record template I created. I’ve used get_edit_link(‘/custom-template/’); ?> to print the edit link successfully, but I’m looking for the record ID (“?pdb=xxxx”) instead of the private ID (“?pid=xxxxxx”). Am I missing something?

    Thanks in advance!

    1. I’m assuming this is something your are doing in a custom list template. You will have to build that URL using the permalink for the page you want them to go to, and adding the record ID to the URL as '?pid=' . $this->record->id

      It’s also possible to set the custom destination for all single record links in the list by using the ‘single_record_link” attribute in the shortcode: [pdb_list single_record_page="custom-single"]

  3. I need to get the value of a field and use it within another shortcode to play a audio file. Here’s what I’ve got so far, but it’s not working (the do_shortcode works if I put a url within the “” but I want the value to change for each participant so the url value needs to come from the audio field.)

    ?php $audio = $this_chart->participant_values[‘audio’]; echo do_shortcode( ‘[sc_embed_player fileurl=”‘.$audio.'”]’); ?>

    The shortcode would be [sc_embed_player fileurl=”URL OF THE MP3 FILE”]

    Thanks!

    1. You’re very close… to get the value from the record, you need to use $this->participant_values['audio']

      1. Thanks so much for the speedy reply, we’re up and running.

  4. I have the same issue as Kevin, I’m using numeric value for one field (a year) but it’s not a required field as we don’t always have the info, so it defaults to “0” . I am adapting a template for my single record page which is working as I need, except this field. What I would like is:

    (in english!)
    if the value is equal to 0 then return nothing and print “.” ,
    else print “in” and then return the value

    I tried the following:

    (‘year_arranged’) ==0 ) : ?> .
    in print_field(‘year_arranged’) ?>

    I’ve also tried =0 =”0″ and Null instead of zero, etc.

    Is there a way to achieve this? Otherwise I think I have to add a new text field to replace the numeric then it’s much simpler to ask if the field (has_content)? I’ve looked at your other templates but can’t find enlightenment.

    Other code I have which works includes:

    KEY: print_field(‘key’) ?>
    SOLOS: print_field(‘solos’) ?>
    has_content(‘feature’)) : ?>FEATURE: print_field(‘feature’) ?>

    1. The system as missed out most of the code … Here it is without the sharp brackets replaced by ( )to to see if it works this time.

      (?php if ($this_chart->has_content(‘year_arranged’) >0 ) : ?)
      (?php $this_chart->print_field(‘year_arranged’) ?)
      (?php endif ?)

    2. I’m sorry, the comment system doesn’t do code too well.

      Something like this should work:

      get_value('year_arranged') != '0' ) : ?>
      in print_field('year_arranged') ?>
      
      .
      
      1. Thanks very much Roland, it works a treat! Just what I needed.

  5. Hi,

    I love this plugin, it works really really nice for me.
    I’ve one question, how can i change the date field style? I would like to have it as a instead of .

    Thanks a lot for you help and keep up the good work.

    1. The plugin uses the global date format, which is set in your WordPress General Settings.

      1. Thanks for your command Roland, i meant that i would like to change date from a text field to a calendar field. People are typing in the wrong dates at this moment. With a calendar date they wont type, they would choose a date. Thats more foolproof for me.

        Thanks in advance.

        1. OK, I get it: try the Datepicker add-on.

  6. Great plugin! I’m a novice with PHP and am having difficulty hiding a div tag when the field is empty.

    1. Sorry, I just realized I left something off.

      I need to hide div tag when field value is null, empty or 0. I tried the “has_content”, however it’s not working. I assume because my values default to 0.

    2. Kevin, I’m sorry I can’t be of much help without seeing your code. You can do this with CSS, you don’t need to use a custom template. Take a look at the HTML, you’ll see that empty fields have a classname that you can use to hide them.

      1. I guess the problem I’m having is because I’m using a numeric field and it’s defaulting to ‘0’. Furthermore, with the template I created, the ‘blank-field’ class doesn’t appear even when I change the field to text.

        Is there a way to hide the div based on a value of ‘0’?

        1. Kevin,

          The easiest way to do this is with a custom template that inspects the value and adds a classname based on that. It could also be done with javascript. CSS can’t handle a situation like this. I have a tutorial that shows how to add the empty field class. The tutorial is for a different purpose, but you can see how that can be done.

  7. Roland,
    What about using this in the combo multisearch? Is it possible to modify the multisearch template so that we can format the results in a customized format for readers?

    1. Yes, you can use a custom template for combo multisearch.

  8. Hi,
    Thank you for your very useful plugin.
    I have a problem with it.
    I created a custom template using pdb-list-default.php.
    However when I use the shortcode calling it, twice in the same page, the php fails entirely in the page. It works fine when called only once.
    Can you imagine a reason why I cannot use the pdb-list shortcode more than once?

    Thanks again
    Daniel

    1. Hi again,
      I have found the culprit. I created and used a function in the template php code. I suppose the problem is related to the Object Oriented PHP.
      Is there a way to write functions and use them in the php template files ?
      Thank you
      Daniel

      1. If you are embedding functions in your templates, and you will be using that template more than once on a page, you need to wrap it in a conditional so that it does not get declared twice…for instance:

        <?php
        if ( ! function_exists( 'my_function' ) {
        function my_function() {}
        }
        ?>

        That way it will only try to define the function if it hasn’t been defined before.

        1. Thank you very much.
          I should have thought of it, the template code being included.

  9. Hello,

    Your plugins is really useful, it helps me a lot. Thank you.

    Currently, I’m using it as a database to store my guests information.

    I have a question.

    After I set “[pdb_list search=true display_count=true template=detailed list_limit=100] on “page1” on my website, I used [pdb_single] to display the single record on “page2”. How can I update the data displayed on “page2”?
    I don’t use signup option or any other option as the list can be accessible and update by anyone.

    Thank you.

    1. This is explained in the “Setup Guide”

      Look at the settings under the “list display settings” tab, set the “Single Record Link Field” to the field you want them to click to go to the single record page. Then set the “Single Record Page” to the page where your [pdb_single] shortcode is. Now, when someone clicks on the link in the list, they will go to the single record page and see all the record’s information.

  10. Hi,

    I used this plugins for somethig else… and its really nice. I had to modify the templates a bit too, and this guide comes really handy.

    Now i have one question.

    I have one field which can be common to more than 2 participants. that field is called ‘member_age’,

    In this single list view, i want to display all the other member who have the same age as the person being displayed here. Is it possible to attain this?

    If so how will i code it to do the same? to list only the names of the people sharing the same age.

    Thanks

    1. OK, since you already know how to work with custom templates, I’ll show you how you can do this in the single record template.

      In the template, you can use the list shortcode, and use the age value to show only those other persons of the same age.

      You will have to change this to fit the details of your setup, but it will print the list, so put this where you want the list to go. If you want to give the list a special format, you can use a custom template for the list, too. Just includes that in the list shortcode.

      <?php
      $age = $this->participant_values['age'];
      echo do_shortcode( '[pdb_list filter="age=' . $age . '&id!' . $this->particpant_id . '" fields="first_name,last_name"]' );
      ?>

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