The Form widget provided by Elementor Pro is a handy tool to easily add forms to your WordPress site. After defining the form fields, you can add “Actions After Submit” to select what you want to happen after the form is submitted. Elementor provides several options out of the box including, storing the submitted form data to your database, notifying the site admin, sending a confirmation email to the submitter, sending the form data to a third-party CRM, or even a generic webhook, which you can configure to run more actions.
We’ve found these built-in options to be sufficient in the majority of cases, but sometimes we’ve needed to handle the form submissions in a unique way, such as when a webhook URL requires the data to be formatted in a specific manner. Thankfully, Elementor provides the Form Action API which allows developers to create custom form actions. The development process is similar to creating custom Elementor Widgets or Dynamic Tags. In the custom action, you define controls to display in the Elementor editor, and then you define a function that receives those control settings and does the custom work you need the action to do. Finally, you register your custom action with Elementor so that the action’s label appears in the action list, as shown in the screenshot above. We recommend adding the custom action code via a plugin so that the action can be reused on other sites too.
The Form Action API linked above outlines in detail the exact code you will need to create your custom action. The documentation is clear, but you might have some questions after implementing it, such as how to handle errors or display post-submission messages to the user. We’ll dive deep in this post and explore the questions you might have after implementing custom form actions using Elementor Form Action API.
Success Image
Let’s create an action that displays an image after the form is submitted successfully. First, we need to add a control to select the image in Elementor. We do this with the register_settings_section method like so:
public function register_settings_section( $widget ) {
$widget->start_controls_section(
'section_custom',
[
'label' => __( 'Custom', 'elmformaction' ),
'condition' => [
'submit_actions' => $this->get_name(),
],
]
);
$widget->add_control(
'success_image',
[
'label' => __( 'Success Image', 'elmformaction' ),
'type' => \Elementor\Controls_Manager::MEDIA,
'label_block' => true,
'separator' => 'before',
'description' => __( 'Select the image to be displayed after the form is submitted successfully.', 'elmformaction' ),
]
);
$widget->end_controls_section();
}
Notice the “condition” limits our control section to display only when our action has been selected. To select an image we need to add a MEDIA control. If you need a different control type for another feature, check the Elementor docs or class Controls_Manager in the Elementor plugin for all the control types available, including TEXT, SELECT, SWITCHER, ICON, WYSIWYG, URL, CODE, and many more.
Then in our action’s run function, we need to add the image to the data sent back in the form response. To do this we will use the $ajax_handler provided by Elementor Pro, which is a helper class that allows us to easily modify the ajax response with errors, messages, or any arbitrary data. The source can be reviewed at
elementor-pro/modules/forms/classes/ajax-handler.php.
public function run( $record, $ajax_handler ) {
$settings = $record->get( 'form_settings' );
if ( empty( $settings['success_image'] ) ) {
return;
}
$ajax_handler->add_response_data( 'success_image', $settings['success_image']['url'] );
}
The important bit here is the add_response_data call where we add the image URL to the ajax response data.
Here’s our full class for reference:
class CustomFormAction extends \ElementorPro\Modules\Forms\Classes\Action_Base {
public function get_name() {
return 'custom';
}
public function get_label() {
return __( 'Custom', 'elmformaction' );
}
/**
* @param \Elementor\Widget_Base $widget
*/
public function register_settings_section( $widget ) {
$widget->start_controls_section(
'section_custom',
[
'label' => __( 'Custom', 'elmformaction' ),
'condition' => [
'submit_actions' => $this->get_name(),
],
]
);
$widget->add_control(
'success_image',
[
'label' => __( 'Success Image', 'elmformaction' ),
'type' => \Elementor\Controls_Manager::MEDIA,
'label_block' => true,
'separator' => 'before',
'description' => __( 'Select the image to be displayed after the form is submitted successfully.', 'elmformaction' ),
]
);
$widget->end_controls_section();
}
/**
* @param \ElementorPro\Modules\Forms\Classes\Form_Record $record
* @param \ElementorPro\Modules\Forms\Classes\Ajax_Handler $ajax_handler
*/
public function run( $record, $ajax_handler ) {
$settings = $record->get( 'form_settings' );
if ( empty( $settings['success_image'] ) ) {
return;
}
$ajax_handler->add_response_data( 'success_image', $settings['success_image']['url'] );
}
public function on_export($element) {}
}
Finally, be sure to register this class as an action according to the example in the Form Action docs linked above. With that, we should have the action available, and when added we should be able to select an image.
Then we need to add some javascript to grab this image from the response data and add it to the page. Elementor emits the event submit_success when a form is submitted successfully, so we will listen for that event.
jQuery(function($) {
$( document ).on('submit_success', function(e, data) {
if (data.data.success_image) {
var img = $('<img />', {
src: data.data.success_image
});
$(e.target).append(img);
}
});
});
With that, you can see the image added to the form after submission.
Error handling
If your action involves some other process that might fail, you should let the user know if something goes wrong. The $ajax_handler also provides a method for adding errors to the form submission called add_error_message. So then if something goes wrong in your action’s run function, you can call the method:
$ajax_handler->add_error_message( 'Custom process failed. Please try again' );
Then Elementor will display the message on the form.
The above should help you create your own form actions to use with the Elementor form builder. This will allow you greater flexibility in handling user interactions.
If you’d like a challenge, use the examples above as a guide to creating these features:
Change the success message to a thank you message that includes the name the user submitted in the form, e.g. “Thanks, John!”
Add a control to enter a shortcode to be displayed as the success message. Remember, Elementor templates can be rendered with shortcodes.
