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 1.7.2

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
    provides access to the raw post array before it is processed and submitted to the database from a signup form
  • 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 (version 1.7.1.9)
  • 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-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 (1.7.2)
  • 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.

Plugin Emails

  • pdb-before_signup_thanks
    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
    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 cearch control.
  • 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.

Form Elements

  • pdb-form_element_build_{$type} (action)
    this action allows the construction of custom element types, or modification of built-in types.
  • 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
  • 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 (1.7.2)

CSV Import/Export

  • pdb-csv_export_value
    passes each value as the CSV file is assembled, allows for custom formatting. The field 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-before_csv_store_record
    provides access to the assembled data array before storing it to the database.

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.

Miscellaneous

  • pdb-parse_date
    passes in the raw date string to be parsed into a valid UNIX timestamp.
  • pdb-before_field_added_to_iterator
    passes through 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-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 (version 1.7.2)
  • 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.

Hooks

Hooks provide data to a 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
    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, provides the record values as stored in the database
  • pdb-after_submit_add
    triggered after a new record is added from the frontend or the backend, provides the record values as stored in the database
  • pdb-shortcode_active
    triggered the first time a plugin shortcode is instantiated
  • pdb-record_update_notification
    fired when a record is updated, passes in an array of the submitted record values.
  • 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_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.

Public Functions

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_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.

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

API Call 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 or added to the CSV file. 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_Form_Element object based on the name of the type. 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.

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 callback is used to alter the user feedback after a submission is made. This filter 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.

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 site 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.

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

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.

There are dozens of such checks, so to change the access to a particular feature, you need to learn the context string that is used by the feature. Inspecting the stream of context strings (such as to an error log) should give you the string you need to look for when changing the access level for a particular feature.

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.

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 fond a match using an alternative method, returning the ID of the found record.