Using Dropdown Values in the List Search

In this tutorial, I’ll explain how to modify the Participants Database list search so that instead of typing values into a text box, the user will select values from a dropdown. The values of this dropdown will be gathered from the defined values of the field being searched. The search will take place on that field alone.

This requires setting up a custom plugin template. You will probably need some familiarity with PHP and HTML to make this all work, although you won’t need to write any code if you don’t want to.

For an explanation of how to set up a custom template, take a look at this article:

Using Participants Database Custom Templates

For this example, we will be starting with the list template “pdb-list-responsive.php” found in the plugin’s templates directory. You can use the default template of you want a table layout, the process is the same. Copy this template to your theme “templates” directory (as explained in the article above) and edit that copy.

Be sure to put the name of the template in the list shortcode so your custom template will be used. Also, of course, the shortcode must have “search=true” so the search form will be shown.

Our modifications go at the top of the template where the search form is generated. Here is the code for the search form in the template before we make any midifications (starting on line 21 of the template):

<?php $this->search_sort_form_top( false, 'form-horizontal' ); ?>

<?php if ( $filter_mode == 'filter' || $filter_mode == 'both' ) : ?>

  <div class="control-group">
    <label class="control-label"><?php _e('Search', 'participants-database' )?>:</label>
    <div class="controls">
    
    <?php
      /* 
       * you can replace "false" with your own text for the "all columns" value
       * for more info on using the column_selector method, see pdb-list-detailed.php
       */
      $this->column_selector( false );
    ?>
  
      <?php $this->search_form() ?>
    </div>
    
  </div>
<?php endif ?>

First, we replace the field selector with a hidden field so that the search will always be performed on that field. In the default fieild set provided with the plugin install, there is a dropdown/other field named “interests.” We will use that for our example here, so the field selector is replaced with a hidden field named “search_field.” The value of the hidden field names the field we will be searching on. In this case, that will be “interests.” You will use the name of the field you want the search to be preformed on.

Here is what the code looks like with the field selector replaced with the hidden field:

<div class="control-group">
  <label class="control-label"><?php _e('Search', 'participants-database' )?>:</label>
  <div class="controls">
    <!-- this selectd the field to search on -->
    <input type="hidden" name="search_field" value="interests" />

    <?php $this->search_form() ?>

  </div>
</div>

In order to place our custom dropdown, we need to build the rest of the search form as separate pieces. We do this by replacing the template function $this->search_form() which generates the rest of the search form, with the pieces we’ll need: the hidden field that provides that search operator and a function that displays the submit buttons:

<div class="control-group">
  <label class="control-label"><?php _e('Search', 'participants-database' )?>:</label>
  <div class="controls">
    <!-- this selectd the field to search on -->
    <input type="hidden" name="search_field" value="interests" />
    <!-- this provides the search operator -->
    <input name="operator" type="hidden" class="search-item" value="LIKE" />

    <?php echo $this->search_submit_buttons(); ?>
  </div>
  
</div>

OK, at this point we have the search form ready to have the dropdown inserted. An HTML dropdown control needs a list of values to present in the dropdown. In Participants Database, s dropdown field has a defined set of values (this is what is in the “values” space for the field definition on the Manage Database Fields page in the plugin admin) that the user can select when they are filling out a form. We need to get those values and make them into our dropdown search control.

First, to get those values, we get the set of defined properties for our field from the plugin configuration. Let’s write a simple function to get that done, and we can put our function at the top of the template. I’m not going to explain each step we take in this function, but what it does is this: given the name of a dropdown field, it provides an array of the defined values for that field.

/**
 * provides an array of dropdown values
 * @param string $name of the field
 * @return array
 */
function pdb_dropdown_values($name) {
  $field = Participants_Db::$fields[$name];
  if ($field) {
    $values = $field->options();
  }
  if (is_array($values)) {
    return $values;
  } else {
    return '';
  }
}

Now, we need to build our dropdown field. The plugin can do that for us, we just need to use the built-in function that it uses to print form elements. We give that function our values, such as the name of the field, what type of field it is and the values to use for the dropdown. Here’s what that looks like. Notice we’re giving it the result of our dropdown value function so it will display those values in the dropdown.

<?php
PDb_FormElement::print_element(
  array(
    'type' => 'dropdown',
    'name' => 'value',
    'options' => pdb_dropdown_values('interests'),
    'class' => 'search-item',
    'value' => filter_input(INPUT_POST, 'value', FILTER_SANITIZE_STRING)
    )
  );
?>

The “value” parameter is using a filter function to get the last selected value of the dropdown. The filter is necessary to secure the form submission against malicious use. This replaces the old not-secure method for using values from the POST array: $_POST['value'] Careful coders generally don’t do it that way anymore.

So, this gives us our completed custom template, which I am providing here in it’s entirety:

Note: this post was updated August 20, 2019 to use the current Participants_Db::$fields value.