Forms API Hooks

Please note that in the code, custom fields are always referred to by their slug. All custom fields created with Types have a wpcf- prefix in their slug. This is why most of the examples on this page use fields with this prefix, for example, wpcf-my_field. When writing custom code for fields created with Types, always use this prefix. For custom fields created in other ways, simply use their respective slug values.

Please keep in mind that $post_id is the User ID when using Toolset Forms API with Toolset User Forms.

cred_before_save_data

Description
This hook allows doing a custom action right before saving or processing any data but after validation.
Arguments
  • form_data. An associative array of of data about current form:
    • form_id. The form ID.
    • post_type. The post type that the form operates on.
    • form_type. The type of the form (create or edit form.
    • container_id. Refers to the post_id of the post, page or custom post type that contains the CRED form.
Output

More Usage examples

Example
add_action('cred_before_save_data', 'my_before_save_data_action',10,1);
function my_before_save_data_action($form_data)
{
    // if a specific form
    if ($form_data['id']==12)
    {
        if (isset($_POST['my_custom_field']))
        {
            // remove this field data
            unset($_POST['my_custom_field']);
        }
    }
}
//Custom before save action can be performed for specific form, using the form ID:
add_action('cred_before_save_data_12', 'before_save_data_for_form_with_id_12',10,1);
function before_save_data_for_form_with_id_12($form_data)
{
    //some code here
}

cred_custom_notification_event_type_condition

Description
This hook is used during evaluation of a custom notification condition, when the event type is custom. It should be used in combination with the cred_notification_event_type hook.
Arguments
  • boolean . Defaults to false. Returns whether the current custom event is the targeted notification event.
  • notification . An array with details of the notification. The key field is name, the notification name, used to target specific notifications.
  • form_id . The ID of the CRED form.
  • post_id . The ID of the post published or edited.
Output
boolean. Return true or false - whether the current custom event is the targeted notification event.

More Usage examples

Example
// Create a function that checks whether a specific condition is met, when a custom event type is used.
add_filter( 'cred_custom_notification_event_type_condition', 'my_custom_event', 99, 4)
function my_custom_event( $bool, $notification, $form_id, $post_id ){
  if( $form_id == '123' ){
    $date_field = get_post_meta( $post_id, 'wpcf-my-date-field', true );
    $current_date = date('Y-m-d');
    if( strtotime( $current_date ) == $date_field )
      return true;
  }
}

cred_file_upload_disable_progress_bar

Description
Disable the file upload progress bar and perform file uploading on form submission.
Arguments
  • is_disabled. Boolean. Whether to disable or not the progress bar.
Output
boolean. Return true or false - whether the progress bar should be disabled.

More Usage examples

Example
add_filter("cred_file_upload_disable_progress_bar", "disable_progress_bar");
function disable_progress_bar($val) {
    return true;
}

cred_filter_field_before_add_to_form

Description
This filter enters into action before each field is added to a Form on the front-end of the site, and gives users the ability to modify several field attributes. Attributes vary by custom field type, so the examples here are generalized.
Arguments
  • field. An associative array of properties that define this field. Properties vary by field type and may include but are not limited to:
    • slug. The string slug of this field.
    • data. An associative array containing repetition and validation configurations, which vary by field type and may include but are not limited to:
      • repetitive. Boolean, whether or not this field repeats.
      • validate. An associative array of field validation properties including require properties which vary by field type and may include but are not limited to:
        • required. An associative array of properties for a required field:
          • active. Boolean, whether or not the field is required.
          • message. String error message to display when a required field is left blank.
    • form_html_id. An array containing the string ID that will be applied to this field on the frontend.
Output
array. An associative array of properties that define this field. This array structure must match the original structure provided in the callback parameter $field.

More Usage examples

Example
// make the first_name and last_name fields in a User form required
add_filter('cred_filter_field_before_add_to_form', 'required_fields_func', 10, 1);
function required_fields_func($field){
    if(in_array($field['id'], array('first_name', 'last_name'))){
        $field['data']['validate']['required'] = array (
            'active' => 1,
            'message' => 'This field is required'
        ) ;
    }
    return $field;
}

cred_form_action_uri_querystring_array

Description
Filter used in order to manipulate action form uri querystring.
Arguments
  • querystring. Array of querystring parameters
  • post_id. int. The post ID of the referring form.
  • form_id. int. The form ID of the referring CRED form.
Output
array. Array of querystring parameters.

More Usage examples

Example
add_filter( 'cred_form_action_uri_querystring_array', 'handle_cred_form_uri_querystring_array', 10, 3 );
function handle_cred_form_uri_querystring_array( $querystring_array, $post_id, $form_id )
{
    //adding new querystring if does not exists
    if ( ! isset($querystring_array[ 'new_parameter' ] ) ) {
        $querystring_array[ 'new_parameter' ] = 'new_value';
    }
    //replacing parameter that already exists
    if (isset($querystring_array['parameter_to_replace'])) {
        $querystring_array['parameter_to_replace'] = 'new_value';
    }
    //removing a parameter that exist
    if (isset($querystring_array['parameter_to_delete'])) {
        unset($querystring_array['parameter_to_delete']);
    }
    return $querystring_array;
}

cred_form_ajax_upload_validate

Description
This hook provides custom validation for files that are uploaded using AJAX
Arguments
  • error_fields. An array containing an errors array and a fields array:
    • errors. An associative array of field names to error messages.
    • fields. An associative array of field names to this structure:
      • value. The field value.
      • name. The field name.
      • type. The field field type (i.e. email, file, image, text).
      • repetitive. Whether this field is repetitive or not.
  • form_data. An associative array of of data about current form:
    • form_id. The form ID.
    • post_type. The post type that the form operates on.
    • form_type. The type of the form (create or edit form.
    • container_id. Refers to the post_id of the post, page or custom post type that contains the CRED form.
Output
array. An array containing an errors array and a fields array.

More Usage examples

Example
add_filter('cred_form_ajax_upload_validate','my_validation',10,2);
function my_validation($error_fields, $form_data)
{
    //field data are field values and errors
    list($fields,$errors)=$error_fields;
    //validate if specific form
    if ($form_data['id']==62)
    {
        //check if featured image exists o
        if ($fields['_featured_image']['field_data']['size'] > 1000000)
        {
            //set error message for featured image
            $errors['_featured_image'] = 'Wrong size image';
        }
    }
    //return result
    return array($fields,$errors);
}

cred_form_validate

Description
This hook provides custom validation for form fields. The default validation will still be performed, so even if custom validation returns TRUE this will not override default validation. However if data are valid by default validation, custom validation can override that and provide errors if this is desired.
Arguments
  • error_fields. An array containing an errors array and a fields array:
    • errors. An associative array of field names to error messages.
    • fields. An associative array of field names to this structure:
      • value. The field value.
      • name. The field name.
      • type. The field field type (i.e. email, file, image, text).
      • repetitive. Whether this field is repetitive or not.
  • form_data. An associative array of of data about current form:
    • form_id. The form ID.
    • post_type. The post type that the form operates on.
    • form_type. The type of the form (create or edit form.
    • container_id. Refers to the post_id of the post, page or custom post type that contains the CRED form.
Output
array. An array containing an errors array and a fields array.

More Usage examples

Example
add_filter('cred_form_validate','my_validation',10,2);
function my_validation($error_fields, $form_data)
{
    //field data are field values and errors
    list($fields,$errors)=$error_fields;
    //uncomment this if you want to print the field values
    //print_r($fields);
    //validate if specific form
    if ($form_data['id']==12)
    {
        //check my_field value
        if ($fields['wpcf-my_field']['value']!='correct_value')
        {
            //set error message for my_field
            $errors['wpcf-my_field']='Wrong Value';
        }
        //check if featured image exists
        if (empty($fields['_featured_image']['value']))
        {
            //set error message for featured image
            $errors['_featured_image'] = 'Missing featured image';
        }
    }
    //return result
    return array($fields,$errors);
}
//For repetitive fields, $fields is an array of values.
//For example, in order to set error message for the second instance of a repetitive field, you can use the following code:
$errors['my_repetitive_field'][1]='Error for second field';
//For File and Image fields, $fields array also contain the upload data.
//For example, you can use the following code:
$fields['wpcf-my_file']['file_data'] = array(
    'size' => uploaded file size,
    'name' => name of uploaded file,
    'type' => type of uploaded file,
    'error' => what error occurred during upload,
    'tmp_name' => location of temporary uploaded file
);
//For skype fields, values are stored as an array:
$fields['wpcf-my_skype']['value']=array(
    'skypename'=> skype name of user,
    'style'=> name of default skype button used
)
//For select and checkboxes fields, values are stored as arrays:
$fields['wpcf-my_checkboxes']['value']=array(
    'value1',
    'value2',
    'value3'
);
//Text-like fields (textarea, WYSIWYG) have only one value, which is the actual input text.
add_filter('cred_form_validate', 'validate_form_wyswyg');
function validate_form_wyswyg( $data ) {
    list($fields,$errors)=$data;
    if (empty($fields['wpcf-wyswyg']['value'])) {
        $errors['wpcf-wyswyg'] = 'Missing wyswyg';
    }
    return array($fields,$errors);
}

cred_mail_header

Description
This hook allows you to change the header information of emails sent using CRED automatic notifications feature. Its parameters allow you to target an exact notification of an exact form and post.
Arguments
  • headers. An array with our header information. We can add new information to this array by adding a custom array ($myheaders in our example) with additional header information to it. Then we simply merge our custom array with the $headers one. Please note that there are a lot of headers you can set (see the comprehensive message headers list here) but the most important are the following: Content-Type: text/HTML; charset=UTF-8, From, CC, BCC, and Reply-To.
  • formid. An ID of the form we want to target.
  • postid. The id of the post that is being created or edited by the form.
  • notification_name. The name of the notification.
  • num_notification. An ID of a notification of the form we are targeting. As you add notifications to a CRED form, each notification has a $num_notification associated with it, starting from zero (0). This means that first notification in a form has a $num_notification value of 0, second one has a value of 1, and so on.
Output
array. An array with our header information.

More Usage examples

Example
//Customise CRED notifications
function customise_cred_notifications( $headers, $formid, $postid, $notification_name, $notification_number ) {
    if ($formid==5 && $notification_number==0) {
        $myheaders = array( 'Reply-To: noreply@test.it' );
        return array_merge($headers, $myheaders);
    }
    return $headers;
}
add_filter('cred_mail_header', 'customise_cred_notifications', 10, 5);
//The following example shows how you can use any value submitted by the form for updating the $headers.
//In the following snippet, we first get the user by ID and then add this user's email address to a custom variable ($myheaders).
//Finally, we merge our custom variable with the $headers.
//The result is that the email notification sent when the form is submitted will have a user's email address set as the Reply-To address.
function customise_cred_notifications( $headers, $formid, $postid, $notification_name, $notification_number ) {
    $myheaders = array();
    $myuser = get_user_by('ID', $postid);
    $myheaders = array( 'Reply-To: '.$myuser->user_email );
    return array_merge($headers, $myheaders);
}
add_filter('cred_mail_header', 'customise_cred_notifications', 10, 5);

cred_notification_event_type

Description
This hook is used to create a custom event type for notifications. It should be used in combination with the cred_custom_notification_event_type_condition hook.
Arguments
  • notification_type . Any custom name for a new event type.
  • notification . An array with details of the notification. The key field is name, the notification name, used to target specific notifications.
  • form_id . The ID of the CRED form.
  • post_id . The ID of the post published or edited.
Output
string . Any custom name for a new event type.

More Usage examples

Example
// Add a new notification event type and then check whether a specific condition is met. If it is, return the slug that will be used for your custom notification event type.
add_filter( 'cred_notification_event_type', 'my_custom_event_type', 99, 4);
function my_custom_event_type($notification_type, $form_id){
  if( $form_id == '123' )
  // Return a slug for your custom notification event type. This can be anything, but must be unique.
    return 'custom_notification_event_type';
}

cred_notification_recipients

Description
This filter allows you to add or modify email recipients of CRED notifications, optionally updating to, cc, and bcc recipients. It can apply to all notifications, or target individual notifications.
Arguments
  • recipients. An array of notification recipients. Each recipient is stored as an array with a to field (with possible values of 'to', 'cc', or 'bcc'), an address field (the email address), an optional name and lastname fields. This argument must be returned by the filter.
  • notification. An array with details of the notification. The key field is name, the notification name, used to target specific notifications.
  • form_id. The ID of the CRED form.
  • post_id. The ID of the post published or edited.
Output
array. An array of notification recipients.

More Usage examples

Example
/**
 * Customise CRED notification recipients by adding a BCC
 * to the the notification "Content submitted"
 */
add_filter('cred_notification_recipients', 'modify_recipients', 10, 4);
function modify_recipients($recipients, $notification, $form_id, $post_id) {
    // Check notification name matches target notification
    if ( isset($notification['name']) && 'Content submitted' == $notification['name'] ) {
        // Add a BCC to log@emailaddress.com
        $recipients[] = array(
            'to'        =>  'bcc',
            'address'   => 'log@emailaddress.com',
            'name'      =>  '',
            'lastname'  =>  ''
            );
    }
    return $recipients;
}

cred_save_data

Description
This hook allows doing a custom action when post data is saved to database.
Arguments
  • post_id. The id of the current created or edited post.
  • form_data. An associative array of data about current form:
    • id. The form ID.
    • post_type. The post type that the form operates on.
    • form_type. The type of the form - 'new' or 'edit'.
    • container_id. Refers to the post_id of the post, page or custom post type that contains the CRED form.
Output

More Usage examples

Example
add_action('cred_save_data', 'my_save_data_action',10,2);
function my_save_data_action($post_id, $form_data)
{
    // if a specific form
    if ($form_data['id']==12)
    {
        if (isset($_POST['my_custom_field']))
        {
            // add it to saved post meta
            add_post_meta($post_id, '__my_custom_field', $_POST['my_custom_field'], true);
        }
    }
}
//A custom save action can also be made for a specific form by using the form ID:
add_action('cred_save_data_12', 'save_data_for_form_with_id_12',10,2);
function save_data_for_form_with_id_12($post_id, $form_data)
{
    //some code here
}
//Calculate the difference from a start date and end date sent after the CRED form submission.
add_action('cred_save_data', 'calculate_days_func',10,2);
function calculate_days_func($post_id, $form_data) {
    if ($form_data["id"]==1160 || $form_data["id"]==1184)
    {
        if(isset($_POST['wpcf-start-date']['datepicker'])){
            $start_date = new DateTime(date('Y-m-d', $_POST['wpcf-start-date']['datepicker']));
        }
        if(isset($_POST['wpcf-end-date']['datepicker'])){
            $end_date = new DateTime(date('Y-m-d', $_POST['wpcf-end-date']['datepicker']));
        }
        $datediff = $start_date->diff($end_date);
        update_post_meta($post_id, 'wpcf-duration', $datediff->days + 1);
    }
}
//Create a dynamic post title by the CRED form.
add_action('cred_save_data','func_custom_post_title',10,2);
function func_custom_post_title($post_id,$form_data) {
    if ($form_data['id']==9999) {
        $name = get_post_meta($post_id, 'wpcf-name', true);
        $email = get_post_meta($post_id, 'wpcf-email', true);
        $title= $name. '-' . $email;
        $args = array('ID' => $post_id, 'post_title' => $title);
        wp_update_post($args);
    }
}

cred_submit_complete

Description
Hook that allows doing a custom action after post data is saved to database and before doing any other action, like redirection.
Arguments
  • post_id. The id of the current created or edited post.
  • form_data. An associative array of data about current form:
    • id. The form ID.
    • post_type. The post type that the form operates on.
    • form_type. The type of the form - 'new' or 'edit'.
    • form_html_id. The HTML ID of the form on the front-end of your site.
Output

More Usage examples

Example
add_action('cred_submit_complete', 'my_success_action',10,2);
function my_success_action($post_id, $form_data)
{
    // if a specific form
    if ($form_data['id']==12)
    {
        // user can overwrite everything here, eg redirection, messages displayed etc..
        // eg redirect regardless of form settings
        header('location:success.php');
    }
}
//Custom success action can also be performed for a specific form by using the form ID:
add_action('cred_submit_complete_12', 'success_for_form_with_id_12',10,2);
function success_for_form_with_id_12($post_id, $form_data)
{
    //some code here
}

cred_success_redirect

Description
Filter redirection URL (if it has been set in form settings).

Please note that for the redirection hooks to work, the form must be set to redirect to a specific page or a post after the submission. If for example, the form options are set to “Keep displaying this form” or “Display a message instead of the form” after submission, the redirection hooks will not work.

Arguments
  • URL. The URL to redirect to.
  • post_id. The id of the current post.
  • form_data. An associative array of data about current form:
    • form_id. The form ID.
    • post_type. The post type that the form operates on.
    • form_type. The type of the form (create or edit form.
Output
string. The URL to redirect to.

More Usage examples

Example
add_filter('cred_success_redirect', 'custom_redirect',10,3);
function custom_redirect($url, $post_id, $form_data)
{
    if ($form_data['id']==12)
        return 'http://newlocation';
    return $url;
}
//This filter can also be applied for a specific form, using the form ID:
add_filter('cred_success_redirect_12', 'custom_redirect_for_form_with_id_12', 10, 3);
function custom_redirect_for_form_with_id_12( $url, $post_id, $form_data )
{
    $newurl = 'http://newlocation';
    return $newurl;
}