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.
This hook allows doing a custom action right before saving or processing any data but after validation.
form_data. An associative array of 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 (create or edit form.container_id. Refers to the post_id of the post, page or custom post type that contains the CRED form.More Usage examples
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
}
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.
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.
boolean. Return true or false - whether the current custom event is the targeted notification event.
More Usage examples
// 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;
}
}
Disable the file upload progress bar and perform file uploading on form submission.
is_disabled. Boolean. Whether to disable or not the progress bar.
boolean. Return true or false - whether the progress bar should be disabled.
More Usage examples
add_filter("cred_file_upload_disable_progress_bar", "disable_progress_bar");
function disable_progress_bar($val) {
return true;
}
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.
field. An associative array of properties that define this field. This argument is optional and if used, you first need to set the right array format. 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. A string ID that will be applied to this field on the front-end.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
// 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){
//error_log(print_r($field, true));
if(in_array($field['id'], array('first_name', 'last_name'))){
// in some cases $fields['data'] is an empty string, so you'll need to first set it's expected format for PHP 7.1 compatibility
if (!is_array($field['data'])) {
$field['data'] = array();
}
$field['data']['validate']['required'] = array (
'active' => 1,
'message' => 'This field is required'
) ;
}
return $field;
}
Filter used in order to manipulate action form uri querystring.
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.
array. Array of querystring parameters.
More Usage examples
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;
}
This hook provides custom validation for files that are uploaded using AJAX
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.array. An array containing an errors array and a fields array.
More Usage examples
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);
}
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.
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.array. An array containing an errors array and a fields array.
More Usage examples
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['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['wyswyg'] = 'Missing wyswyg';
}
return array($fields,$errors);
}
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.
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.
array. An array with our header information.
More Usage examples
//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', 8, 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', 8, 5);
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.
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.
string . Any custom name for a new event type.
More Usage examples
// 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';
}
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.
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.
array. An array of notification recipients.
More Usage examples
/**
* 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;
}
By default, WordPress provides three time intervals for running scheduled events: run every hour, twice a day, and daily. Toolset Forms uses one of those scheduled intervals to check for expired posts and expire them if it is needed. Use this filter to register your schedule.
$schedules. Array of existing scheduled periods. Each element must have a proper unique key. It must have the following structure:
array( 'interval' => {seconds between each scheduled event}, display=> {Public name of the schedule] )
$schedules. Array of schedule items.
More Usage examples
//Define your custom schedule
add_filter ('cred_post_expiration_cron_schedules', 'my_function', 10,1);
function my_function ($schedules) {
$schedules['fifteenmin'] = array( 'interval' => 15 * MINUTE_IN_SECONDS, 'display' => __( 'Every 15 minutes' ) );
return $schedules;
}
$custom_actions. Array of actions where custom actions can be added. Each action is an associative array with two elements (meta_key and meta_value).
$post_id. The ID of the current created or edited post.
$form_data. Associative array of data about the current form (form_id, post_type and form_type).
$custom_actions. Array of actions containing data for the meta_key and meta_value to apply.
More Usage examples
//Updating a custom field when a post expires
add_filter('cred_post_expiration_custom_actions', 'my_custom_actions', 10, 3);
function my_custom_actions($custom_actions, $post_id, $form_data) {
$custom_actions[] = array( 'meta_key' => 'advert_active', 'meta_value' =>'false' );
return $custom_actions;
}
If the redirection is done after a post is deleted this filter can modify the redirection target.
url. The original URL to redirect to.
post_id. The ID of the post being deleted.
string. The new URL to redirect to. It can also be self to change the action and reload the current page, It can also be left empty to do nothing.
More Usage examples
add_filter( "cred_redirect_after_delete_action", "prefix_custom_redirect", 10, 2 );
function prefix_custom_redirect( $url, $post_id ) {
if ( 123 == $post_id ) {
// When deleting the post with ID 123, redirect to the post with ID 789.
return get_permalink( 789 );
}
return $url;
}
This hook allows doing a custom action when post data is saved to database.
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.More Usage examples
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);
}
}
Hook that allows doing a custom action after post data is saved to database and before doing any other action, like redirection.
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.More Usage examples
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
}
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.
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.string. The URL to redirect to.
More Usage examples
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;
}