Participants Database API

I have created a Developer’s API (a series of filters, hooks and public methods) for Participants Database partly so I can extend the plugin’s functionality for clients, but these may be of use to developers who also want to extend the functionality of the plugin. These are offered without support and are intended for experienced WP developers only.

This document covers all API features as of version 2.5

Display Templates

For customization tasks that need to alter the display HTML for any shortcode, there is the Participants Database Templating System that gives you the ability to create a custom output for any shortcode.

This is also a good way to include Javascript, which will be needed any time dynamic interactions with the user are called for.

Filters

With a filter, data is passed through an external function and returned to the plugin to complete whatever task it is performing. The external function must return the provided data in the correct form for the plugin to continue functioning.

Submissions Processing

• pdb-before_submit_signup
  called when a signup form is submitted on the frontend, and provides access to the raw post array before it is processed and submitted to the database.
• pdb-before_submit_update
  provides access to the raw post array before it is processed and saved to the database. This filter is active for both frontend and admin record updates.
• pdb-before_submit_add
  the posted data from a new record added in the admin is available through this filter, works the same as the previous filter.
• pdb-validation_methods
  adds a custom validation method to the list of available methods in the field definition
• pdb-validation_error_messages
  supplies the array of validation error messages to be added to or altered
• pdb-error_css
  passes in the error CSS used to highlight empty or invalid fields so that it can be altered
• pdb-field_validation_message
  provides access to the field validation error onject that controls the CSS selector and error message on a -per-field basis
• pdb-check_submission
  all form submissions to the plugin are checked through this filter before anything is done with them. Expects a boolean in return; false to abort processing the submission. Good for spam filtering by inspecting the $_POST array, which can also be altered at this time.
• pdb-incoming_record_match
  the matching status of an incoming record is passed into a filter so an alternate matching method can be used. This is active for both new record submissions (signups) and CSV imports.
• pdb-process_form_matched_record
  this filter allows for an alternative update matching method on record submissions and CSV imports
• pdb-find_record_match
  Gives access to the record matching that is used when retrieving a private link. The filtered value is the matched record ID, also passed in are the column names checked for a match and the submitted (unsanitized) post array.
• pdb-captcha_validation
  Allows a filter callback to set the validation regex used against the user input. Passes in the stock regex and the post array. Expects a valid regex in return.
• pdb-files_location
  sets the location for storing uploaded images and files. Passes in the currently configured location, by default that is wp-content/uploads/participants-database.
• pdb-update_thanks_message
  sets the on-screen thanks message after submitting a record update. Only used if the record shortcode is set up to go to a separate page after submission. That page must have the [pdb_update_thanks] shortcode.
• pdb-file_upload_filename
  provides a way to set the name of an uploaded file, passes in the normal filename, the field definition object, and the record id. This filter expects the string fieldname (without an extension) in return.

Plugin Emails

• pdb-before_signup_thanks
  this action gives access to the record values, email body and feedback messaging for alteration before it’s presented or emailed to the user
• pdb-receipt_email_template
  pdb-receipt_email_subject
  allows the outgoing receipt email template to be altered before sending the email
• pdb-before_send_retrieve_link_email (action)
  This action gives access to the email subject and body for a retrieve private link email.
• pdb-email_headers
  gives access to the outgoing email headers for alteration before sending any plugin email
• pdb-template_email_tag_map
  array that maps specific tags againd data values. This can be used to create new template tags to use in emails.

List Searching/Filtering

• pdb-list_filter
  this passes in the shortcode filter string so it can be altered by a callback. This is one of a couple of ways of implementing a custom search.
• pdb-list_query
  the complete query used to display the list ([pdb_list] shortcode) can be altered before it is used to retrieve the records for display. This query does not include pagination limits, but the filter will be applied for each page of records.
• pdb-list_query_object (action)
  This filter provides access to the list query object before it’s used to generate the list.
• pdb-search_error_check
  Provides access to the search error check so you can set up the error feedback on a custom search
• pdb-search_error_style
  when a search error occurs, a set of CSS rules is added to the display so that search error feedback can be shown. This filter gives access to the style element so you can set your own CSS rules.
• pdb-search_control_html
  filters the output of the PDb_List::search_form() method to allow plugins to insert a custom search control.
• pdb-search_sort_form_output
  filters the whole search/sort form HTML (including error messages)
• pdb-pagination_configuration
  filters the configuration array for the list pagination module. See the PDb_List class for details on instantiating the PDb_Pagination class.
• pdb-loading_spinner_html
  filters the HTML for the spinner graphic that is shown while an AJAX request is getting processed.
• pdb-whole_word_match_list_query
  when set to true, all searches will be match whole words only. i.e.: a search for “part” would not match “partial”.
• pdb-list_query_parens_logic
  normally, in a complex search query, “OR” statements are parenthesized, this filter allow you to change that so that “AND” statements are parenthesized. This is helpful in situations where a “filter” type search is in use.
• pdb-search_input_attributes
  provides a way to add attributes (such as input validation) to the search input field.
• pdb-list_anchor_name
  provides a way to change the list anchor string that is used to scroll the page back to the top of the list

Form Elements

• pdb-form_element_build_{$type} (action)
  this action allows the construction of custom form element types, or modification of built-in types. This action is used to build the form input element.
• pdb-set_form_element_types
  allows for alteration of the list of form elements types
• pdb-before_display_form_element
  advanced filter for preparing the form element value display when simply displaying the value.
• pdb-form_element_html
  allows direct modification of the form element HTML string just before display
• pdb-before_display_form_input
  provides access to the PDb_Field_Item object before displaying the form input element.
• pdb-dynamic_value
  when a hidden field has no stored value, the default value is used to determine the value to set the hidden field to. This filter gives access to the value and the default value of the field so that a custom callback can be used to determine the final value.
• pdb-captcha_setup (action)
  this action passes in the PDb_Captcha object to allow a plugin or theme to define a custom captcha.
• pdb-value_title_match_pattern
  when looking for a “value title” this regex is used to find the value in the field options array for an element like a dropdown. It might be necessary to alter this when using a multilingual plugin.
• pdb-image_source
  gives access to the full filepath of an image and the name of the plugin module displaying the image.
• pdb-form_element_datatype
  allows custom form elements to determine the datatype used in the main table
• pdb-before_display_form_input (action)
  this action gives access to the PDb_Field_Item object before the form input is printed.
• pdb-stringify_array_glue
  when a field that stores it’s value as an array has it’s value displayed, it is as a comma-separated list of values. This filter lets you change the character that joins the list items together. The default is a comma followed by a space.
• pdb-image_wrap_template
  provides access to the HTML template used to generate an image display
• pdb-field_options_pair_delim
  pdb-field_options_option_delim
  Field types such as Dropdowns, Radio Buttons, Multi-Checkboxes, etc. have a set of values (called “options”) that determine what can be selected. These are defined with a formatted string in the field definition. These filters give you a way to change the characters that are used to format that string. The pdb-field_options_pair_delim defaults to :: and the pdb-field_options_option_delim defaults to ,
• pdb-calculated_field_calc_value
  Provides a way to perform a custom calculation for a Numeric Calculation or Date Calculation field.

CSV Import/Export

• pdb-csv_export_value
  passes each value as the CSV file is assembled, allows for custom formatting. The PDb_Field_Item object is passed in as the second argument.
• pdb-csv_import_value
  passes each value as the CSV file is imported, allows for custom formatting. The field name is passed in as the second argument.
• pdb-allow_imported_empty_value_overwrite
  passes in bool false, return true to allow an empty value in the CSV to overwite the value in the record
• pdb-before_csv_store_record
  provides access to the assembled data array before storing it to the database.
• pdb-after_import_record
  this action is triggered after each record is imported, it gets the record data, the record id, and a status value that tells whether the record was updated, added, skipped or there was an error.

Output Formatting

• pdb-template_select
  passes in the name of the currently selected plugin shortcode template file, and expects in return a template filename or valid absolute file path. Providing just the filename causes the plugin to look for the template in the usual locations. Providing a full path gives you a way to get your custom templates from any location, also handy for other plugins that need to use their own Participants Database custom template.
• pdb-shortcode_call_{$tag}
  this filter passes in the attributes of any plugin shortcode tag, allowing the parameters to be altered before the shortcode is rendered. The $tag value will be the complete shortcode tag: i.e., ‘pdb_list’, ‘pdb_signup’, etc.
• pdb-{$module}_shortcode_output
  this filter receives the output HTML of the named plugin shortcode before printing to the page. For instance to filter the output of the list shortcode, use ‘pdb-list_shortcode_output’ as your filter tag.
• pdb-rich_text_auto_formatting
  rich text is passed through this filter before display when “Use WP Auto-Formatting” is not enabled.
• pdb-before_include_shortcode_template
  the shortcode class instance is provided to this action so that the object can be altered before the template renders the output.
• pdb-single_record_link_field
  determines which fields have the single record detail link
• pdb-allowed_html_form, pdb-allowed_html_post
  Fillter makes it possible to alter the list of restricted form elements and attributes.

Miscellaneous

• pdb-translate_string
  all plugin display strings are passed through this filter, so it can be used to implement multi-lingual strings.
• pdb-parse_date
  passes in the raw date string to be parsed into a valid UNIX timestamp.
• pdb-select_database_table
  passes in the name of the database table or WP setting for customization.
• pdb-access_capability
  all internal plugin capability checks are passed through this filter for possible modification. A context value is also passed in so the capability can be set according to the action it controls access to.
• pdb-nonce
  provides access to the generated nonce string, useful for implementing an alternate nonce, also includes a context value.
• pdb-verify_nonce
  passes in the result of wp_verify_nonce() and provides a way to implement an alternative nonce verification for the main submission nonce.
• pdb-nonce_key
  provides access to the key string used in all plugin nonces, can be used to know context
• pdb-translate_string
  provides a general filter for all user-defined display strings (like field titles) so they may be filtered for translation.
• pdb-private_id_length
  sets the length of the generated private ID
• pdb-generate_private_id
  makes it possible to alter or create a custom private ID
• pdb-value_title_match_pattern
  filters the regex used to match a value to a “value title” used in a selection-type control.
• pdb-record_edit_page
  passes in the record edit page permalink for modification
• pdb-timezone_assertion
  filters the timezone string that is sent to PHP to set the default timezone. This defaults to the WordPress timezone setting.
• pdb-before_admin_delete_record
  Filters the list of ids before the records are deleted.
• pdb-custom_template_location
  Normally, custom templates are located in the current active theme in a directory named “templates” This filter allows the plugin custom templates to be located anywhere.
• pdb-single_record_url
  filters the URL used in the “single record link” typically seen in the list display

Hooks or Actions

Hooks (also known as actions) provide data to a handler function at a specific point in the execution of the plugin. They do not require or make use of a return value.

• pdb-after_submit_signup
  after the frontend signup form is submitted and saved, provides access to the processed new participant record, raw values as stored in the database
• pdb-after_submit_update
  triggered after a record is updated (frontend or backend), provides the record values as stored in the database
• pdb-after_submit_add
  triggered after a new record is added from the backend, provides the record values as stored in the database
• pdb-shortcode_active
  triggered the first time a plugin shortcode is instantiated, happens only once per page load and only if there is an active plugin shortcode on the page
• pdb-shortcode_set
  triggered each time a shortcode is instantiated, the shortcode object is passed in. If there are multiple shortcodes on a page, each one will fire this action as it is instantiated.
• pdb-before_field_added_to_iterator
  passes in the field object before it is added to the main field loop generated by a shortcode. This is to allow for any late-stage changes to the field object.
• pdb-before_display_form_input
  this action gives access to the PDb_Field_Item object before the form input is printed.
• pdb-form_element_build_{$type}
  this action allows the construction of custom element types, or modification of built-in types by giving access to the PDb_FormElement object’s output property.
• pdb-before_validate_field
  this action supplies the field values used to validate a submitted field so that a custom validation can be performed.
• pdb-captcha_setup
  this action passes in the PDb_Captcha object to allow a plugin or theme to define a custom captcha.
• pdb-before_send_retrieve_link_email
  This action gives access to the email subject and body for a retrieve private link email.
• pdb-list_query_object
  This filter provides access to the list query object before it’s used to generate the list.
• pdb-list_ajax_complete
  fired after the list AJAX search/sort callback completes. Supplies the post array.
• participants-database_activated
  fired after the initial setup of the plugin. This is primarily used by other scripts and plugins that are dependent on Participants Database as an initialization/enabling hook.
• pdb-field_defs_updated
  fired after a field definition is updated, passes in the action key and the query used to update the field definition.
• pdb-before_signup_thanks
  this action gives access to the record values, email body and feedback messaging for alteration before it’s presented or emailed to the user
• pdb-before_update_thanks
  this action gives access to the record values, email body and feedback messaging for alteration before it’s presented or emailed to the user

Public Methods

There are, of course, many public functions available to developers who wish to delve into the code. Functions in the main script, if public, are all called statically, so they are simple to access. Here are some of the more generally useful examples:

Participants_Db::get_participant($id) – gets a record from the database by it’s ID number. Returns an associative array of raw values.

Participants_Db::write_participant( $data, $id ) – provides a way to update or insert a record. Omit the $id to insert a new record.

Participants_Db::get_column($name) – gets the attributes of a column, given it’s name. Returns an object with all the field’s properties.

Participants_Db::get_id_list($config) – provides a list of record ids with filtering and sorting

Participants_Db::get_participant_list($config) – provides a list of record data with filtering, sorting and field selection

Participants_Db::get_record_id_by_term($term, $value, $single = true) – given the name of the field, the function returns the record ID of the first record that matches it. The third argument, if set to false, causes the function to return an array of IDs for all matching records.

PDb_Template_Email::send($config, $data) – can be used to send a template-based email. See Using the PDb_Template_Email Class for details.

Participants_Db::field_defs() – provides an array of PDb_Form_Field_Def objects for each defined field in the main database.

Public methods for the PDb_List_Query object listed on the List Query reference page.

API Filter Details

pdb-before_validate_field

This action supplies the field values used to validate a submitted field so that a custom validation can be performed. This action will be triggered for each field as the form submission is validated. The value supplied:

• $field – object with properties ‘value’, ‘name’, ‘validation’, ‘form_element’, ‘error_type.’

The two key properties here are “error_type” and “validation.” The validation property indicates the validation method to apply. If it is a custom validation method, this filter callback would perform that method, and mark the field valid or not by setting the error_type property. This callback can also be used to replace a stock validation method.

The ‘error_type’ property is the one the filter callback will in most cases change to indicate the result of the validation. It is initially set to boolean false. If validation fails, the property would be set to an error type string. This string is the key to the user feedback message in the $error_messages array that corresponds to the validation error. You can define your own key or use a stock message key such as ’empty.’

If it passes validation, the $field->error_type property should in most cases be set to the key string ‘valid’. If it is left false, built-in validation methods will be applied according to the form_element and validation properties.

While the value, name and form_element properties can all be altered, it’s probably not a good idea to alter the name property since that identifies the field, while altering the form_element property won’t do anything–it’s just there to use in constructing your validation method.

If you want to change the submitted value, it needs to happen on the pdb-before_submit_signup or pdb-before_submit_update filters in order to have that change continue through the submission process and be visible to the user as a changed value.

pdb-validation_error_messages

Validation error messages can be altered or added to using this filter. Each error message may contain a placeholder “%s” that will be replaced by the name of the field validated. The value supplied:

• $error_messages – array of error messages, to which a new message can be added. The form of this array is $validation_type_key => $validation_error_message Existing messages can also be altered.  The $field->error_type string keys the array and determines the error message to show.

pdb-before_display_form_element

This gives access to the raw field value before it is displayed in a non-form context, such as a single record page, email or CSV.

The return value of the callback is expected to supply the string that will be displayed. Several form elements are stored in formats that wouldn’t make good displays (such as serialized arrays and timestamps) so a formatting of these raw values is often necessary. If the filter return value is empty or null, the standard formatting for the field will be used.

Note the value and the form element can be accessed as properties of the field object, along with all the other properties of the field.

• $return – an empty string to be filled with the display string
• $field – the field object

pdb-form_element_build_{$type}

This action is given the PDb_FormElement object based on the name of the type. It is used to build the form input element.

For instance to set the output of the text-area form element, use ‘pdb-form_element_build_text-area’ as your filter tag, then put your HTML into the output property of the supplied object. This also allows you to define custom form elements. Be sure to set this up using an add_action function.

A practical application of the use of this action is described here Creating Custom Form Elements

pdb-list_query

This filter passes in the list query as a MySQL query string, which can be altered using string manipulation, then returned. There are three ways to implement complex searches and directly control the result set for displaying a list of records: this filter, which gives direct access to the query, you can dynamically alter the shortcode in a template (easier for those with limited PHP skills) or finally, there is the new query object, explained below.

The list query is altered for pagination after this filter is applied. Any changes made here affects the whole set of results, and then pagination uses a limit clause to select a range of records to display on the page. For this reason, you cannot add limit clauses with this filter.

pdb-template_select

This filter only fires if there is no custom template (normally found in /wp-content/YOUR_THEME/templates/) and so provides a way for a plugin to provide the template. Variable passed in to the callback:

• $template – name of the template file

If the filter provides a valid absolute path to a template file, it will be used. If the filter provides only a template file name, the plugin will look for it first in the current theme directory, then in the plugin for the default file.

pdb-captcha_setup

This sends the PDb_CAPTCHA object to a filter so an alternate CAPTCHA implementation can be inserted. Two properties in the object must be set: ‘validation’ and ‘HTML’. The HTML property contains the HTML string to display the CAPTCHA challenge, and is required to implement the CAPTCHA element.

The ‘validation’ string is a complete regex string to test against the user input.

pdb-select_database_table

This gets the name of one of four key data sources: the three database tables and the settings array. A callback on this filter will be able to select a database or settings according to the language setting (for instance) making it possible to use translated field definitions and plugin settings. A valid data source must exist at the name returned.

pdb-before_signup_thanks

This action is used to alter the user feedback after a submission is made. This action takes place after the record has been stored, so it cannot be used to alter the stored values.

The function is provided with 2 arguments: a utility object and the form status (tells whether the submission is a signup or an update).

The utility object has following properties:

• recipient – the user’s email address
• receipt_subject – subject of the receipt email
• receipt_body – body of the receipt email
• notify_recipients – the list of recipients for the notification email
• notify_subject – subject of the notification email
• notify_body – body of the notification email
• thanks_message – the message to be displayed on the screen after a successful submission
• participant_values – an associative array of values from the new record

Altering these properties (which are passed by reference) in a callback changes the feedback provided by the plugin.

Changing the ‘participant_values’ property won’t have any effect on the values stored because the record has been stored at this point, but this data set is used to replace the value tags in the email bodies and feedback messaging. You can also use this to add custom values.

The form status will be one of several string values such as ‘normal’, ‘multipage-signup’, ‘multipage-update’.

pdb-before_update_thanks

(version 1.9.7 and later) This action is used to alter the user feedback after a record is updated on the frontend. This action takes place after the record has been stored, so it cannot be used to alter the stored values. The action is provided a single argument, a utility object.

The utility object has following properties:

• notify_recipients – the list of recipients for the notification email
• notify_subject – subject of the notification email
• notify_body – body of the notification email
• thanks_message – the message to be displayed on the screen after a successful submission
• participant_values – an associative array of values from the updated record

Altering these properties (which are passed by reference) in a callback changes the feedback provided by the plugin.

Changing the ‘participant_values’ property won’t have any effect on the values stored because the record has been stored at this point, but this data set is used to replace the value tags in the email bodies and feedback messaging. You can also use this to add custom values to your messages.

pdb-receipt_email_template

This passes in an array containing the subject and body email templates as the first argument, the second argument is an array of the submitted values. The callback is expected to return the array of templates.

pdb-access_capability

This filter has two values passed into the callback: the capability name and a context string. Before an access-controlled feature is displayed to the user, that user’s capabilities is checked against the required capability for that feature. The required capability is what the callback should return, so if you want to open that feature up to other users, you would return the key capability for that user.

Take a look at this page for the current list of controlled-access actions available: Backend User Access Control

For an example of altering the access capability, with an in-depth explanation of how the filter works, take a look at this article: Allowing Participants Database Editors to Delete Records

pdb-incoming_record_match
pdb-process_form_matched_record

These two filters work together to provide a way to implement an alternative record matching method. Record matching happens when a new record is added or a record is imported via CSV. If “update on match” is selected as the preference, then when a record comes in, it looks for a matching record to update if possible. Normally, this checks a single field for a match. Using these two filters, any kind of matching method can be implemented.

The pdb-incoming_record_match filter passes in a boolean indicating whether a matched record has been found or not. The second parameter is the submittted post array. To implement an alternative matching method, you would look at the post array and return true if your method detects a match.

As of version 17.8.11, there are two more parameters available to this filter: the duplicate record preference ( 1 = updating a matching record; 2 = preventing a duplicate ) and a true/false if the current operation is a CSV import. These will prove useful if there are several different scenarios where record matching takes place in your setup.

The process_form_matched_record filter passes in the ID of the matched record (using the normal method) and the submitted post array. This filter allows you to use the post data to find a match using an alternative method, returning the ID of the found record.

An example of the use of these filters can be found here…

pdb-single_record_link_field

This filter passes in an array of field names, add any fieldnames you want the single record link to go on.

For example:

pdb-single_record_url

Used the change the URL used in links to a record’s single record (or detail) page. First argument is the default URL, second argument is the record ID.

pdb-calculated_field_calc_value

This filter takes 3 arguments: (bool) $result, (array) $replacement_data, and (\PDb_Field_Item) $field. The $result argument should return the calculated value, or bool false if the calculation should proceed normally using the plugin’s code. $replacement_data is the array of values used to perform the calculation. If (for example) you have a value tag in the calculation template, the value for that tag will be in this array. The $field object gives you access to all the calculation field’s properties.

pdb-allowed_html_form
pdb-allowed_html_post

HTML that is printed to the screen is filtered to disallow dangerous content. This filter provides a way to alter the list of allowed HTML tags and attributes. The two filter names refer to the context: pdb-allowed_html_form is for user input displays such as the signup form or the record edit form. pdb-allowed_html_post is applied to read-only content such as list displays and single record displays. Read this article for information about how this works:

How to change the allowed HTML tags for WordPress

This filter gets the array of allowed tags and attributes and expects an array in return.

API Method Details

Participants_Db::get_id_list( Array $config )

This utility function supplies an array of record ids, with the ability to filter and sort. The $config array uses similar parameters as the [pdb_list] shortcode:

• ‘filter’ – a filtering string using the same format as the list shortcode filter
• ‘orderby’ – list of fields to order the list with
• ‘order’ – list of (asc or desc) order directions for the ordering fields

Here is an example of the use of this method, it will produce an array of IDs for records that have a last_name beginning with the letter “a”:

<?php Participants_Db::get_id_list( array( 'filter' => 'last_name=a*' ) ); ?>

Participants_Db::get_participant_list( Array $config )

This function works much the same as the preceeding one, with the addition of the ‘fields’ parameter.

• ‘fields’ – a comma-separated list of field names
• ‘filter’ – a filtering string using the same format as the list shortcode filter
• ‘orderby’ – list of fields to order the list with
• ‘order’ – list of (asc or desc) order directions for the ordering fields

This function returns an array of data objects, indexed by the record id. Each data object will have as its properties the field data specified in the ‘fields’ parameter. If the ‘fields’ parameter is not specified, all fields will be included.

Participants_Db::write_participant( Array $data, Int $id )

This method is used for updating existing records or for creating new records. The $data array must be an associative array with the array keys matching the field names you want to write to. The $id is the numeric id of the record you want to update. For example:

<?php
// update participant record id #1024
Participants_Db::write_participant( array( 'first_name' => 'John', 'last_name' => 'Jack' ), 1024 );

// create a new record, the function returns the new id
$record_id = Participants_Db::write_participant( array( 'first_name' => 'John', 'last_name' => 'Jack' ) );

If you want to create a new record, omit the $id argument.

You cannot use this method to set the id of a new record, that is handled internally. If you need to use your own id value scheme, you can set up a new field for that purpose.

When creating a new record this way, values are not validated, and no checks are made to avoid adding a duplicate record. You should do that in your code if you need to avoid that.