| CARVIEW |
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.
Reference
- cred_before_save_data
- cred_custom_notification_event_type_condition
- cred_file_upload_disable_progress_bar
- cred_filter_field_before_add_to_form
- cred_form_action_uri_querystring_array
- cred_form_ajax_upload_validate
- cred_form_validate
- cred_mail_header
- cred_notification_event_type
- cred_notification_recipients
- cred_post_expiration_cron_schedules
- cred_post_expiration_custom_actions
- cred_redirect_after_delete_action
- cred_save_data
- cred_submit_complete
- cred_success_redirect
- 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: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 }
- 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; } }
- 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; }
- 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. 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.
- 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){ //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; }
- Description
Filter used in order to manipulate action form uri querystring.
- Arguments
-
querystring. Array of querystring parameterspost_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; }
- 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); }
- Description
This hook provides custom validation for form fields. The default validation will still be performed, so even if custom validation returns
TRUEthis 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['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); }
- 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', 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);
- 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'; }
- 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; }
- Description
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.
- Arguments
-
$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] )
- Output
$schedules. Array of schedule items.
More Usage examples
- Example
-
//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; }
- Description
- Arguments
-
$custom_actions. Array of actions where custom actions can be added. Each action is an associative array with two elements (meta_keyandmeta_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).
- Output
$custom_actions. Array of actions containing data for themeta_keyandmeta_valueto apply.
More Usage examples
- Example
-
//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; }
- Description
If the redirection is done after a post is deleted this filter can modify the redirection target.
- Arguments
-
url. The original URL to redirect to.post_id. The ID of the post being deleted.
- Output
string. The new URL to redirect to. It can also beselfto change the action and reload the current page, It can also be left empty to do nothing.
More Usage examples
- Example
-
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; }
- 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); } }
- 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 }
- 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 'https://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 = 'https://newlocation'; return $newurl; }