List Shortcode Filters

The [pdb_list] shortcode has a “filter” attribute that you can use to determine which records get shown in the list that shortcode displays. It’s a little complicated, but once you get how it works, you’ll find it is extremely flexible and can tailor your list to show exactly what you want.

The general format of the parameter is this: field operator value. So, for instance, if you wanted to show all records from the state of New York, you would put [pdb_list filter="state=NY"] . “state” is the field (it must match exactly the field name as listed on the Manage Database Fields page in the plugin) “=” is the operator and “NY” is the value. The filter is grabbing all records where the state is equal to “NY.”

Operators

The filters work by comparing two values: the value in the filter is compared against the value in the record to determine if that record should be shown or not. How the comparison is made is determined by the operator. Here are the operators and what they do:

Symbol Operator What it does Example
=  equals  filter value matches the record value exactly  state=NY
~  contains  finds the filter value in the record value  interests~yoga
!  not in  filter value is not found in the record value  interests!hiking
!= not equals  filter value does not equal the record value  state!=CA
>  greater than  record value is greater than the filter value  amount_due>10
>=  greater than or equal to  record value is greater than or equals the filter value  balance>=100.00
<  less than  record value is less than the filter value  last_name<b
<=  less than or equal to  record value is less than or equals the filter value  last_name<=z

Chaining Filters

You can use more than one filter by stringing them together like this: [pdb_list filter="last_name>c&last_name<h"] (note ampersand between filter statements) This gives you all records with last names that start with d through g. Upper case or lower case doesn’t matter. The ampersand “ands” the two filters together, for instance if you want all the unemployed applicants from New York, you’d use employed=no&state=NY

Filters can be also be chained by an “or” operator by using the | (pipe) character. For instance, to get all the records with a city of either “New York” or “Brooklyn” you could use: filter="city=New York|city=Brooklyn" And they can be combined: filter="color=red|color=orange&amp;size=large" will give all large items in red or orange. Note that items separated with an “or” operator will be parenthesized (put in parentheses), meaning that the above example would not return a list of all the red items plus all large orange items. This is because the parenthesized part is resolved first, so “red or orange” is resolved as a unit before the rest of the filter is included.

Using Wildcards

Filters accept search wildcards so you can set up a shortcode to show, for instance, all the entries beginning with a certain letter. This could be useful for breaking a list up into alphabetical groups. The wildcards you can use are *, which means “any string of characters” or ? which means “any single character.” To filter for all last names that begin with “J” you would use a filter like this: filter="last_name=j*"

Filtering for Blank Data

You can use the filter to exclude records that are missing a field or have a blank value by using the not operator and no value: [pdb_list filter="phone!"]That will show all the records that have a phone number (in other words: the phone field is not empty). You can of course chain this with other filters, just remember all you’re doing is omitting the “value” part of the filter statement: [pdb_list filter="photo!&state=OR"] gives you all the people in Oregon that have uploaded a photo.

Filtering Dates

To correctly compare dates, the field must be defined as a date field form element on the manage database fields page. Date values should be a regular date string like this: [pdb_list filter="date>jan 3,2012"]Filtering for a range of dates requires two filters: [pdb_list filter="date>=jan 1,2012&date<jan 1,2013"] gives you all the records for the year 2012.

It’s best to use a name for the month (and maybe you have to use English month names) because the date/month/year order is different on different servers. If you really want to use numbers for the date, just try it to see what the correct order for your web server is. The “Strict Date Format” setting affects how the shortcode filters are interpreted, so if this is checked, the date format in your filter argument must match the date format set in your WP General Settings.

Filtering Numeric Values

If you need to compare or filter values based on their numeric value, you must use a “numeric” type field. This means you cannot include units, commas, or denomination marks in the values. Using numeric fields, you can filter by numeric range: income>20000&amp;income<=50000

Filtering with Multiselect and Link fields

When using filters with fields that store their values as arrays, you must use the ~ operator because the values are stored with other information (technically, the array is serialized). A = will never work because of that additional information.

Fields that use arrays to store their values are:

  • Multislect Dropdown
  • Multiselect Checkbox
  • Multiselect Other
  • Link