The submission form included with BNE Testimonials has been, fore the most part, basic. Over the releases, you have been able to adjust the labels and of course remove certain fields from showing. However, you have not been able to add, edit, or remove the fields themselves at the developer level.
Now with version 2.4.2, an API has been exposed to control how the fields are presented. With this new API, you can now do the following:
- Add new fields (frontend & admin)
- Edit existing fields (frontend)
- Remove fields (frontend)
- Store new field data in the database
New hooks and filters in v2.4.2
- bne_testimonials_form_fields – filter – returns an array of fields used in the submission form.
- bne_testimoinals_form_submit_after – hook – An open hook allowing handing new submission data or custom actions when a form is submitted.
- bne_testimonials_email_data – filter – returns an array of data that is looped in the email notification of submitted fields.
Example #1 – Star Rating Field Replacement
Let’s take a simple example – changing the rating select field to a star rating field. For this, we’re going to use an alternate rating select field that is now included with v2.4.2. The default behavior is to select the rating from a select box, however; using the alternate rating field we can now use a star rating radio field.
The above filter would go in your child theme’s functions.php or a utility plugin. The ‘rating_star’ is an actual field type in the plugin that was created specifically for this purpose. Any existing field can theoretically be altered or added. One note, validation for custom fields are not handled by the plugin and should be added via the bne_testimoinals_form_submit_after() action hook where you can validate, sanitize, and save to the database.
Example #2 – Adding a new, sanitizing, and Saving a field
Now, let’s take a more complex one – well one with many parts. Let’s say we need to collect a phone number. To do that we’ll need to use:
- cmb2_init_before_hookup() to add the field to the admin metabox,
- bne_testimonials_form_fields() to add the field to the submit form,
- bne_testimoinals_form_submit_after() to update our testimonial post meta, and finally
- bne_testimonials_email_data() to include the value in the email notification.
What makes this “complex” even though it’s a single field, is that there are a lot of places for the data to go depending on how you want to interact with it.
For example, if you only want to collect the phone number and include it in the email, then you could skip using cmb2_init_before_hookup and bne_testimoinals_form_submit_after as these would be used to interact with the data in WordPress. By contrast, if you didn’t want to include the phone number in the email notification, you could skip bne_testimonials_email_data.
This allows you to decide, as a developer, how you want to handle the data. With that said, if you will be storing the data, retrieving the data and interacting with the data elsewhere, you should sanitize and escape it where possible.