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. It is best to use a shortcode block to place the list shortcode.
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.
Additional sorting options are described below.
Linking to a Record Detail Page
Each record item in the list can be given a link to show the full details of that record. This is called the “Single Record Page” and you can configure the link to be placed on any field in the list record item. This configuration is found in the plugin settings under the “List Display” tab. Once configured, clicking on the field will take the user to a page that shows the record in detail.
A Dedicated Link
It is also possible to set up a field that is only for the purpose of providing a link to the record details. This is seen on the demo page as the “View Details” link.
You set that up by creating a new field (on the Manage Database Fields page) that is a “Placeholder” type field. The placeholder works by simply printing its “default” value from the field configuration.
By configuring that placeholder field as the “Single Record Link Field” (this is in the plugin settings under the List Display tab) the placeholder will provide a link to the single record page for the record. Remeber to visit the Manage List Columns page to place the placeholder field in your list.
The single record page and how to configure it is discussed in more detail here: Showing a Single Record
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.
- header_sort – set to true to enable a clickabe sort in the header of the list display. This only works when using a table (the default) type display.
- 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 Sort 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.
Random sorting is possible by setting the orderby attribute to “random,” like this:
[pdb_list orderby=random]
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.
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 list searching:
[pdb_list search="true" sort="true"]
There is also a “header sort” you can enable with the header_sort attribute in the shortcode. This only works for table-type displays, as used in the default list display template. For example:
[pdb_list header_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, and all searches will be performed on the one named field.
[pdb_list search=true search_fields="city, state"]
There is also the default_search_field attribute where you can name the field that comes in as the default selected field.
[pdb_list search=true default_search_field="last_name"]
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*”
See the list Only After Searching
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]Remote Searching
Normally, the list search control will be shown at the top of the list, but it’s possible to have the search control in different location, then show the result in the list whether it’s in a different place on the page or on another page. Take a look at this article for the details on how to set that up: Using the Search Shortcode
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. For example:
[pdb_list template=responsive]When using responsive templates, such as “responsive” or “flexbox” it is almost always necessary to add your own CSS to get the display to look the way you want. The plugin provides some very basic CSS, but in most cases this will need to be adjusted. See below for more on this.
Custom List Templates
If you’ve got some coding skills, the plugin has a custom template system (much like what WordPress has for content) that you can use to set up a custom layout with custom HTML and other functionality. Check out this page for the details: Using Participants Database Custom Templates.
If you’re interested in adding a link to the editable record in your frontend list, you can set that up with the use of a custom template: Adding an Edit Record Link to the Frontend List
Customizing the Appearance of the List
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…