I have created a very simple API (a series of filters, hooks and public methods) mainly so I can extend the plugin’s functionality for clients, but these may be of use to programmers who also want to extend the functionality of the plugin. These are offered without support and are intended for experienced WP developers only. If you want me to develop custom functionality for you, please contact me.
As of version 22.214.171.124 the following API functions are available:
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 some form for the plugin to continue functioning.
- 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
- 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. The pagination limits are added to the query, so your syntax must allow that clause to be added at the end of the query string. It will be of the form “LIMIT $offset, $count”
- pdb-before_validate_field – supplies the field values used to validate a submitted field so that a custom validation can be performed.
- pdb-validation_error_messages – supplies the array of validation error messages to be added to or altered
- pdb-form_element_build_$type – allows the construction of custom element types
- pdb-set_form_element_types – allows for alteration of the list of form elements types
- pdb-before_display_field – allows a callback to prepare a raw field value for display
- pdb-before_signup_thanks – gives access to the record and feedback messaging for alteration before it’s presented or emailed to the user
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
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::get_column($name) – gets the attributes of a column, given it’s name. Returns an object with all the field’s properties.
API Call Details
This filter supplies the field values used to validate a submitted field so that a custom validation can be performed. This filter will be executed for each field as the form submission is validated. The value supplied:
- $field – object with properties ’value’, ‘name’, ‘validation’, ‘form_element’, ‘error_type.’
The ‘error_type property 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. It can be a message you define or a stock message such as ‘empty.’
If it passes validation, the $field->validation property should in most cases be set to boolean false so other validation methods won’t be applied. The error_type property will key a feedback message (if one is defined for the state) whether the field passes validation or not.
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. It could be useful to alter the value field if you wanted to correct an entry or clear it so the field comes back blank.
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. Existing messages can also be altered. The $field->error_type string keys the array and determines the error message to show.
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 will be what is 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.
- $return – an empty string to be filled with the display string
- $value – the raw value of the field
- $form_element – the form element handle of the field
This one is not particularly easy to work with, you will need to do string manipulation on the query, which can be fussy and prone to error. I plan to move to an object-oriented query (like WP uses) but for now, this is the only way to implement complex searches and directly control the result set for displaying a list of records. It may be easier to simply rebuild the query rather than alter the string.
Creating Custom Form Elements
Several filters are used to create a new form element type:
This filter is used to add the new form element identifier. The full definition array of form element types is passed through, a new element should be added to the array in the form:
type_handle => title.
This filter is called when a form element is instantiated. When the element is instantiated, the FormElement object will be passed to this filter with the type handle appended to the name. The callback is expected to fill the ‘output’ property with the HTML string.
Validation of the submitted value and display of the value (out of the form context, such as in a list of records) are handled by the previously defined filters. To add a custom element, these filter callbacks should be set up in the theme functions or as a plugin.
For instance, if the new element had a handle of ‘array’ and a title of ‘List,’ the new element is added to the form element types array as
'array' => 'List' Then, the filter callback to build the element HTML would be attached like this:
This callback should return the FormElement object with the ‘output’ property filled with the HTML needed to display the element in a form.
This filter cal also be used to override an existing element build function. If the FormElement object is returned with it’s output property filled with HTML, the standard build method will be skipped.