WordPress Contact Forms API

Heads up! This page is available only in Italian

WordPress Contact Forms Plugin by Cimatti is developed as part of our Accua Marketing Platform. It includes Accua Form API and Accua Forms. Accua Form API allows the integration of the PHP Form Builder Class with WordPress. Accua Forms implements a visual interface for the creation and management of forms. For this reason actions and filters have the prefix “accua_form_” or “accua_forms_”.

Accua Forms filters and actions

To validate and do actions with the forms defined in the “WordPress Contact Form Plugin” you can use filters “accua_forms_validation” and “accua_forms_submission”

Filter accua_forms_validation

add_filter('accua_forms_validation', 'my_function_name', 10, 4);
function my_function_name($valid, $fid, $submittedData, $form){
  // Do your checks and set $my_validation_result as true or false
  return $valid && $my_validation_result;
}

$valid: the current result of validation, true if all tests are passed, false if an error occured
$fid: form id
$submittedData: array containing data submitted by the user
$form: the AccuaForm object. You should use $form->setFormError($errors, $element) to output an error message

Please note that this is a filter, so you have to return $valid even if your function does nothing, or you will break the validation process.

Filter accua_forms_submission

add_filter('accua_forms_submission', 'my_function_name', 10, 6);
function my_function_name($replace_map, $fid, $submittedData, $form, $_field_data, $_istance_data){
  // Execute your custom php code. Modify or add custom tokens in array $replace_map
  return $replace_map;
}

$replace_map: associative arrays of the tokens. You can modify or add values. You must return this array at the end. To avoid name collision, if you define custom tokens you should prefix with “__your_plugin_name_”.
$fid: the form id
$submittedData: data submitted by the user
$form: the form object
$_field_data: array that contains the data that defines the fields
$_istance_data: array that contains the settings of the istance of the fields

Action accua_forms_print_tokens

If you are a plugin developer, the main way to add functionalities to the “WordPress Contact Forms Plugin” is defining custom tokens and letting the user add them to messages. If you want to show a brief description of your tokens in the message settings pages, you can use the action “accua_form_print_tokens”.

add_action('accua_forms_print_tokens', 'my_function_name');
function my_function_name() {
  echo "List of my custom tokens";
}

Accua Form API and PHP Form Builder Class integration

The plugin defines the class “AccuaForm” that extends the “Form” class from PFBC. To create a new form you can use

$form = AccuaForm::create($formID);
$form->render(); //output html

This class works a little differently from PFBC. When an AccuaForm object is created, “accua_form_alter” action is called so the form can be defined adding fields, styles and validation functions.

The generated form is serialized and saved in an encrypted hidden field. When the form is submitted, the form object is unserialized from the submitted form, and integrity checks are done so the submitter can’t taint the serialized encrypted form. Serialized form is not saved on the server, so it will not waste server resource even if it will not be submitted.

When the form is submitted, validation functions are called. If the validation passes, submission functions are called.

Action accua_form_alter

add_action('accua_form_alter', 'my_function_name', 10, 2);
function my_function_name($formID, $form) {
  // do something on $form object
}

$formID: the form ID
$form: the AccuaForm object

Forms created with the interface have the prefix ‘__accua-form__’, so if you use one of these hooks you should check that IDs starts with ‘__accua-form__’

Filter accua_form_validate

add_filter('accua_form_validate', 'my_function_name', 10, 4);
function my_function_name($valid, $formID, $submittedData, $form){
  // Do your checks and set $my_validation_result as true or false
  return $valid && $my_validation_result;
}

$valid: the current result of validation, true if all tests are passed, false if an error occured
$formID: form id
$submittedData: data submitted by the user
$form: the AccuaForm object. You should use $form->setFormError($errors, $element) to output an error message

Please note that this is a filter, so you have to return $valid even if your function does nothing, or you will break the validation process.

Filter accua_form_submit

add_action('accua_form_submit', 'my_function_name', 10, 3);
function my_function_name($formID, $submittedData, $form){
  // Do your custom code
}

$fid: the form id
$submittedData: data submitted by the user
$form: the form object