Using the List Shortcode

You use the [pdb_list] shortcode to show a list of Participants Database records. To do that, type the list shortcode into the content where you want it to appear.

The columns (or fields) that will appear in the list display are configured on the Manage List Columns page in the admin.

The global configuration for the list display is found in the plugin settings under the “List Display” tab.

The settings for a specific shortcode can be set in the shortcode itself, using attributes.

Determining Which Columns Show in the List

Which columns are shown by the shortcode is globally set up on the Manage List Columns page. On that page you’ll find a handy drag-and-drop interface for setting up the columns for the frontend list display and also the admin Participant List display.

Sorting the List

The order in which records are shown in the list is determined globally by the settings under the “List Display” tab in the plugin settings. Look for “List Default Sort” settings.

List Shortcode Attributes

The list shortcode (like all Participants Database shortcodes) can include many settings that will only affect the display for that shortcode, overriding the global settings. These settings are called attributes and they are added to the shortcode by typing in the name and value for the attribute into the shortcode.

Multiple attributes can be set by separating each attribute with a space. For example, to enable the search and sorting controls for the list display, you can add those attributes like this:

[pdb_list search="true" sort="true"]

Attribute values only need to be quoted if there is a space in the value. This is so the space doesn’t get interpreted as a new attribute. This why you will see some attributes with quoted values and others not.

Here is the full list of attributes you can use with the [pdb_list] shortcode:

  • search – set to ‘true’ to show a list search control.
  • sort – set to ‘true’ to show a list sort control.
  • fields – a comma-separated list of field names (not titles) to show. This is only needed if you want to override the setting on the Manage List Columns page.
  • list_limit – sets the number of records to list per page. If there are more than this number of records to show, a pagination control will appear. To show all records, use a value of -1.
  • template – allows you to select the template that is used to show the list of records. This is also where you would select a custom template.
  • filter – lets you determine which records are shown (see List Shortcode Filters for a detailed explanation).
  • orderby – order the list by one of the columns, use the field name here.
  • order – determines whether the list is ordered in ascending (asc) or descending (desc) order.
  • display_count – if set to ‘true’ will show the number of records. This is configured in the “List Count Template” setting.
  • suppress – prevents the list of records from showing at all until a search is performed.
  • search_fields – a comma-separated list of field names to be offered in the search selector
  • default_search_field – the name of the field to set as the default value for the search field selector

Setting the List Columns in the Shortcode

You can also set the columns to display for an individual shortcode by including a list of the names (not Titles!) of the fields you want to show in the order you want to show them:

[pdb_list fields="last_name, city, email, photo"]

Setting the List Sorting in the Shortcode

It is also possible to set the sort of the list in the shortcode using the “orderby” and “order” attributes. For example:

[pdb_list orderby=last_name order=desc]

You can also sort by multiple columns with a comma-separated list of field names, like this:

[pdb_list orderby=date_recorded,last_name order=asc,desc]

That example will sort the list according to when the record was created in ascending order, then by the last name in descending order.

Numeric Sorting

If you need a field to be sorted numerically, you must use one of the numeric form element types: Numeric (integers), Decimal, or Currency.

These form element types will only store numeric characters, including the decimal point. No commas, spaces, or any kind of unit or denomination characters can be stored in numeric fields.

Showing Units or Denominations

You can configure a field to show a units or denomination character in the field configuration. This is done in the attributes setting for the field, using the “data-before” or “data-after” attributes. For example, to show a currency field with a US dollar sign before it, use an attribute like this:

data-before::$

Let Your Users Search and Sort The List

You can activate list searching and/or sorting for your users with the search and sort attributes. These attributes will enable a search form and/or sort form displayed above the list. For example to enable both:

[pdb_list search="true" sort="true"]

For a fully configurable and comprehensive search control, take a look at the Combo Multisearch add-on.

User List Searching

The search control provided in the base installation of Participants Database is a simple control consisting of a field selector and a text input. The user can select which field they want to search using the field selector dropdown, then type in something to search for.

Which Fields are Searched On?

By default, only fields that are displayed in the list will be available in the search selector. You can override this by using the search_fields attribute with a comma-separated list of field names. If you configure only one field to search on, the field selector is not shown.

There is also the default_search_field attribute where you can name the field that comes in as the default selected field.

Search Modes

There are two search modes for the list: strict or not strict. If the “Strict User Searching” setting (this is in the plugin settings) is checked, the search term must match exactly the whole contents of the field in order to be found. If unchecked, the search will show any records where any part of the searched field contains the search term.

Search Wildcards

The search text input will accept wildcards for more control over the results. The asterisk * stands for any string of characters, while the question mark ? stands for a single character. To search for all entries that begin with the letter “b” for instance, you would use the search term “b*”

If you want the list of records to only appear as a search result, add the “suppress” attribute to the shortcode like this:

[pdb_list search=true suppress=true]

User List Sorting

For the sort control, the fields offered for sorting will be those checked as “sortable” (on the Manage Database Fields page) and also be present in the list display.

The user can select to sort “ascending” in value or “descending.” This will be alphabetical, using standard English. You can set this to other languages by changing the “collation” in your database. Get help from your web hosting provider if unsure about how to do this.

For numeric fields, sorting will be numeric.

Filtering which Records Get Shown in the List Shortcode

Each list shortcode can have a filter or multiple filters that determine which records are shown in that list. This is explained fully here: List Shortcode Filters

List Display Templates

The list shortcode has four built-in templates which provide the basic display framework for showing the list of records.

  • default – shows the list in a standard WordPress table. The number of columns is determined by the number of fields you have set up to show in the list.
  • bootstrap – shows the list of records in a table, but with standard “bootstrap” formatting. Best used with themes based on Bootstrap.
  • responsive – a template designed for responsive displays, meaning it tries to look good on a mobile display. Instead of using a table, the records are shown each as their own block of field values. This is so the display can “collapse” when viewed on a small screen.
  • flexbox – this template uses the powerful Flexbox layout system implemented in modern browsers. This one is fairly technical to use, but it provides a lot of possibilities.

Templates are selected by placing the name of the template in the list shortcode. (This is also how Custom Templates are used.) For example:

[pdb_list template=responsive]

Customizing the List Layout

The main way to set the layout and style of the list is by using list templates. Your theme will do most of the work in styling the list. If you want to get into the details of the layout, you’ll need to use CSS rules to make the changes you want.

Take a look at this article if you’re unfamiliar with CSS or want to learn some handy tools to use when working with CSS rules on your site: Simple CSS Techniques for WordPress

Back to the main Participants Database documentation page…