This post is about how to construct a link that when followed, shows a specific search result in the Participants Database list display.
So, first of all you need to set up your base URL. This is the URL that takes you to the page that shows the [pdb_list] shortcode.
In the following examples, you would add the
? and everything after that to your base URL to get the URL to use on your site.
Important: if your base URL has a
? in it, then to use the examples, replace the
? in the example with a
& so that the variables will be added to the variable that is already in your base URL.
Let’s say you have a list of people who have specific skills. They’ve filled in their information using a “multiselect” to indicate which skills they have. Now, you want to show a link on your site that will show all the people with a particular skill.
This is easy to do, because it’s possible to include simple search parameters in a URL to a page with the [pdb_list] shortcode.
Let’s say the name of your skills field is “skills” and you want to show all the web designers. First, take a look at the values you have defined for your Skills multiselect so you know the exact string to look for. In this case, it’s ‘web designer’. The case is not important.
In a URL, the search parameters are ‘search_field’ and ‘value’ so we tell the list which value we are seeking in which field. Now, our search term has a space in it, so because we are using the term in a URL, we need to convert that space into a URL-encoded value. The value for a space is %20, so this will be what you will add to the URL for the search result page:
And that will show you all the people who checked “Web Designer” in their skills.
You can only do simple searches this way: on a single field with a single search term. If you want something more complex than that, you’ll need to create a custom WordPress template that can process a more complex search from the URL and build those into the filter attribute of the list shortcode.
You can use the wildcard characters (*?) in the search value. For instance, if you want the URL to match just the first letter, you could set up a URL like this:
That will show all the records with a last name that begins with “a”.
Advanced Use: Operators
If you need to tweak the results some, you can use an “operator” to change how the search is performed. If an operator is not specified, it defaults to matching the record if the serch term is found within the field data. If you need it to show only exact matches, you can add an operator to the URL, like this:
That will match only a thing value of “car” and not something like “cart” (Note: you can’t use wildcards with the “eq” operator.)
Other operators you can use are:
|~||like (find within the data)|
Using Filter Links with Multi-Search
Links like these will work with the Multi-Search feature of the Combo Multisearch add-on. Note that this only works with fields that are configured in the Multisearch section of the add-on, also operators in the URL won’t change how the search works. This is because the URL is simply preselecting the multi-search fields and submitting the search.
It’s also possible to create a URL that filters on multiple fields with a syntax like this:
Note the brackets which allow multiple values for “search_field” and “value.” In order for this to work, the “search_field” value must be paired with a “value” value and in the same order.
Sorting The List
It is also possible to set the sort of the list in the URL. The variable names to use for that are ‘sortBy’ and ‘ascdesc’ which should hold the field name and the direction of the sort, respectively. For example, to sort by last name in normal alphabetical order, you’d use a URL with variables like this:
Of course, this can be combined with sort terms by using the & symbol…for example:
If you find that you’re not getting the expected results, there are several things to check.
The most common culprit: page caching. Make sure page caching is off for the page you’re showing your search results on. A page cache will often show an un-updated page, so it looks like you didn’t get any result at all. The page with the
[pdb_list] shortcode should be exempt from page caching.
(You should never use page caching, or any kind of site acceleration at all when developing and setting up a site. Once the site is doing what you want it to do, turn the cache or accelerator plugin on, then test the site to make sure it works with it on.)
Another common source of problems is the use of the
[pdb_search] shortcode. If you have both the search shortcode and the list shortcode on a page, you won’t get the results displayed correctly when using a search result URL. It is best to use the list shortcode alone. Details here…
Next, make sure the spelling in your URL is correct. The name of the field must exactly match the name as shown on the Manage Database Fields page. Don’t try to use the field’s title, it won’t work. If the search terms contain things like spaces or punctuation, you probably need to “urlencode” the value.
If you’re sure the URL is correct, you’ll need to look deeper to understand the results. First, turn plugin debugging on. This is in the Participants Database settings under the Advanced tab. What this will do is record the database query that was used to produce the result.
When using the debugging log, it is important to clear the log before performing a test. Then check the log right away after you do the test so that the only messages in there will be caused by your test. What you’re looking for is the list query, it will be a MySql query that is pretty easy to understand.
If you understand the query, and it looks correct, but the results are not what you expect, you need to look at the database data directly. Open your database using phpMyAdmin or a similar tool. The table you want to look at is named wp_participants_database (your “wp_” prefix may be different), in there you will see the raw data. Sometimes the actual data is different than you expect it to be, this will tell you what’s really going on.