Sometimes it’s necessary to create a custom form element to handle a specific need for a UI element in a Participants Database form. The means for doing that have been set up in the plugin, you’ll definitely need some coding skills to get this done, so this post will only briefly cover the basic steps to setting up a custom form element. You are expected to know how to make this into your own custom form element.
There are 3 steps to take to set up a custom form element:
- Register the element with Participants Database
- Define the HTML for showing the form element in a form
- Define how the element’s value is displayed when not in a form
Register Your Custom Element
pdb-set_form_element_types 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. Your custom form element type will show up in the Form Element dropdown on the Manage Database Fields page.
Showing a Custom Form Element in a Form
For this, we use the
This action is triggered when a form element is instantiated. When the element is instantiated, the PDb_FormElement object will be passed to the action handler. The handler is expected to fill the ‘output’ property with the HTML string. The handler argument is passed by reference so other changes to the element object are possible in addition to defining the output HTML.
This action can also be used to override an existing element build function. If the FormElement object already has it’s output property filled with HTML, the standard build method will be skipped. For instance, if you wanted to modify how the “link” element was displayed, you could use the “pdb-form_element_build_link” hook to define your new HTML for that element. The normal way of building that element would then be skipped.
Showing the Value of a Custom Form Element
Each form element has a way to show it’s value in a non-form context, and that can be customized as well. For that, we use the
pdb-before_display_form_element filter which is supplied the raw value of the field and the PDb_Field_Item object for the element. Typically, you’d test the field object to see if it was your custom form element, then return the appropriate display HTML. Be sure your filter returns a boolean false for form elements you don’t want to alter!
Let’s say you want to create a custom form element that stores an array of 3 values. You’re giving the element a handle of ‘array’ and a title of ‘List.’ The “pdb-set_form_element_types” filter is used to add those terms to the list of elements available in the field definition page.
The filters and actions need to define the custom element would be added like this:
add_filter( 'pdb-set_form_element_types', 'my_array_register_element' ); add_action( 'pdb-form_element_build_array','my_array_element_building_function' ); add_filter( 'pdb-before_display_form_element','my_array_element_value_display_function', 10, 2 );
The my_array_register_element() function adds the field name to the list of elements. The my_array_element_building_function() sets the PDb_FormElement object ‘output’ property with the HTML needed to display the element in a form. The my_array_element_value_display_function() returns the display value of the form element.
Here is the full code for our example. This one is way too simple to be used as-is, it’s only to show you how the parts go together, you can take it from here.