There are many ways to create Caldera Forms processors. The basics are covered in this post. You should probably read that post and the processing overview post before reading this post. Note that this post assumes intermediate OOP PHP knowledge. If you’re not comfortable with OOP PHP, keep in mind that the other examples use functional PHP. Also Caldera Forms lead developer Josh Pollock wrote a free eBook to help you learn OOP PHP.
When creating a Caldera Forms processor Caldera_Forms_Processor_Processor or a class that implements the Caldera_Forms_Processor_Interface_Process interface. This is not required, but is recommended. In addition, all processor UI should be generated using the Caldera_Forms_Processor_UI class. Caldera_Forms_Processor_Processor is an abstract class, there is an abstract class for payment and mailing list processors that extends it, which should be extended by your concrete class. Each of those has an interface as well.
Overview Of Processors Classes
Caldera Forms is free software and all code is available on Github. Each of the classes listed here is provided as a link to its source. A brief description of the class is provided here.
Abstracts
- Caldera_Forms_Processor_Processor – This is the main parent class for processors. Registers processor with caldera_forms_get_form_processors and provides pre_process and process callbacks.
- Caldera_Forms_Processor_Payment – Extends Caldera_Forms_Processor_Processor. Has no methods, but forces subclasses to implement Caldera_Forms_Processor_Interface_Payment.
- Caldera_Forms_Processor_Newsletter – Adds a specific method for setting API client and forces subclasses to implement Caldera_Forms_Processor_Interface_Newsletter.
Interfaces
- Caldera_Forms_Processor_Interface_Process – Requires a pre_process, process and fields method.
- Caldera_Forms_Processor_Interface_Payment – Requires a do_payment method.
- Caldera_Forms_Processor_Interface_Newsletter – Requires a subscribe method.
Autoloader
Processor UI
All Caldera Forms processors should use the Caldera_Forms_Processor_UI class to create their UI. This drastically reduces copypasta code , and provides for forward-compatibility. Also, you will notice shortly that Caldera_Forms_Processor_UI and Caldera_Forms_Processor_Processor use exactly the same array for defining fields.
Processor Data
Inside of a Caldera Forms processor callback, the processor configuration is provided and can be translated to the correct data based on the current form submission. The best way to do it is using the Caldera_Forms_Processor_Get_Data class. This class takes the processor and form config, as well as the same fields array that is used for Caldera_Forms_Processor_UI. It provides validation and sanitization of all processor fields. It also has getter methods for field data and errors.
Processor Fields
At this point, it should be pretty clear that the processor config fields must be created before setting up the processor or its UI. Because this array will be used in two or more places, you should create a function for it. This example function shows all of the options the UI fields array accepts. Please read the inline docs for explanations:
Here is an example using a variety of field types and options:
See the section on creating your processor UI for how to use this array to generate the processor UI.
Using The Caldera_Forms_Processor_Processor Class
This class does the actual processing.
Understanding The Class Dependencies
Your processor’s processing should happen in a subclass of the Caldera_Forms_Processor_Processor class or a subclass of one of the subclasses provided. This class’s constructor has three arguments:
$processor_config– Configuration of the processor. (array)$fields$slug– The unique slug for the processor (string) This is used to form filter names and as the index of the processor configuration array added on the caldera_forms_get_form_processors filter.
Here is an example processor config:
Note that the “pre_processor,” “processor” and “post_processor” arguments are not specified. The pre_prcoessor and processor are automatically registered. No post_processor is registered, by default. If your config contains a string as the value for “post_processor”, a post processor callback is registered using the method of the processor class with that name.
When you created an instance of this class, the processor is automatically registered using the “caldera_forms_get_form_processors” filter.
Instantiating This Class
You should instantiate your instance of this class at the caldera_forms_pre_load_processors action.
Filters Created By This Class
There are several filters that are named dynamically using the $slug argument passed into the class. Here are the dynamic filters:
- The “caldera_forms_$slug_fields” filter modifies the processor fields.
- This filter is useful for changing the field configuration during processing.
- JK, There are no other filters right now.
Working With The Data Object
The Caldera_Forms_Processor_Get_Data provides a complete system for converting form submission and processor configuration data to useable data or errors. In your processor class’ pre_processor method, you should “$this->set_data_object_initial( $config, $form );” to set the object in the $data_object property of the class.
Here is an example processor class that illustrates how to work with the data object:
Creating Caldera Forms Payment Processors
All Caldera Forms payment processors should use a subclass of the Caldera_Forms_Processor_Payment class if possible. If that class’ structure doesn’t work, please use the Caldera_Forms_Processor_Interface_Payment interface, which Caldera_Forms_Processor_Payment implements.
Because Caldera_Forms_Processor_Payment implements Caldera_Forms_Processor_Payment and Caldera_Forms_Processor_Interface_Process, you must have a pre_process, process and do_payment method. It is recommended that you use “pre_process” to validate input and call “do_payment”, and return any validation or payment errors there. If validation passes, you can use the “process” method to record payment details.
Creating Newsletter Processors
Processors for subscribing users to mailing list services should extend the Caldera_Forms_Processor_Newsletter class. If the structure of that class isn’t conducive for your needs, please implement the Caldera_Forms_Processor_Interface_Newsletter interface.
Because Caldera_Forms_Processor_Newsletter implements Caldera_Forms_Processor_Interface_Newsletter andCaldera_Forms_Processor_Interface_Process you must have a pre_process, process and subscribe methods. It is recommended that you use “pre_process” to validate input and call “subscribe”, and return any validation or API errors there. If validation passes, you can use the “process” method to record payment details.
Creating The Processor UI
Earlier the processor field configuration array was described. This same array is used to generate the UI for the processor. Creating the processor UI is very simple. All you need to do is pass that array to the config_fields method of the Caldera_Forms_Proccesor_UI class.
Notes About Proccesor UI Templates
- The path to this file is defined in the processor configuration, described earlier in this document.
- The processor template, must be a separate file.
- Using a closure or function that returns a string isn’t supported. Sorry.
- If you need to add inline JavaScript, you can do it in this file.
- We do it all the time.
- Processor templates use Handlebars.js (for now). {{_id}} is the unique ID of the processor.
Make Something Awesome!
Please use this example code to make something special for your website or a cool add-on for public distribution. If you have created a Caldera Forms add-on for public release get in touch. We’d be happy to add it to our 3rd-party integrations page, or list it on our site.