Many websites must do more than simply display information. They must interact with visitors, take action based on visitor responses, and display different information for different people. We will teach you how to build these types of sites using Toolset plugins and offer some custom PHP coding.

  • Your site retains everything it “knows” in the database.
  • Visitors send their responses using forms.
  • The logic you implement for processing forms and taking action is called the Business Logic.

The Forms plugin already does much of the “business logic” for you. Forms creates posts in the database, edits posts, and controls the status ((i.e., whether they are drafted or published) of those posts.

However, sometimes you may require that more complex operations occur when visitors submit forms. In these cases, you should use Forms’s hooks to implement your own logic during the post-submission process.

Here are the events that you can identify and customize:

 

Form step What you can do with it Hook name and documentation
When the form displays Disable the file-upload progress bar and force uploaded files to be submitted with the form. cred_file_upload_disable_progress_bar
Before the form is submitted Add your own checks on the form data and prevent the form from being submitted. cred_form_validate
Validate files that were uploaded using AJAX (normal file upload). cred_form_ajax_upload_validate
Modify the form submission arguments. cred_form_action_uri_querystring_array
Take action immediately before the form is saved (when all validations have passed already). cred_before_save_data
While saving the post to the database Take action when saving a post to the database. cred_save_data
After the form is successfully submitted Take action after saving the post to the database. cred_submit_complete
Customize the header of the notification email that Forms sends after the form is fully processed. cred_mail_header
Modify the recipients of the email notifications. cred_notification_recipients
Modify the destination URL to which to redirect the user after processing the form. cred_success_redirect

 

Example – Toolset Contractors System

Toolset’s Contractors system uses Toolset forms to submit applications and implements a complex business logic. Forms takes care of the “heavy lifting” by displaying the forms, validating submission data, and creating posts in the database.

On some form submissions, in addition to publishing posts, we must take additional actions.

Toolset clients apply to become “contractors” using the following Toolset form:

When submitting this form, Forms creates a new Contractor post, which it sets as a draft. We must set a usermeta field to indicate that this user (client) is available. Forms cannot do this because we set the usermeta fields on a separate element and with a special condition.

Therefore, we use the cred_save_data hook, which allows us to run additional logic immediately after Forms creates the post in the database.

Implementing custom logic 
/**
* Action for 'cred_save_data' to set the contractors state associated with the usermeta field.
*
* @param int $post_id
* @param array $form_data
*
* @uses get_post()
*
* @return void
*/
public function action_cred_save_data( $post_id, $form_data ) {
  $form_post = get_post( $form_data['id'] );
  if ( ! empty( $form_post ) ) {
     switch ( $form_post->post_name ) {
        case 'add-contractor':
           $contractor = $this->module->get_contractor( $post_id );
           $contractor->set_contractor_availability( Contractor::CONTRACTOR_AVAILABILITY_AVAILABLE );
           $constructor_user = $this->module->get_contractor_current_user();
           if ( $constructor_user->is_eligible_contractor() ) {
              $constructor_user->set_eligible_notice_dismissed_state( true );
           }
           break;
        case 'edit-contractor':
           $contractor = $this->module->get_contractor( $post_id );
           $contractor->sync_contractor_state();
           break;
     }
  }
}

 

You can see that we use one function to implement the custom logic for two cases: when adding contractors and when editing them.

Using similar hooks, we could implement a complex workflow that allows clients to submit applications, enables our team to review them, and finally raises concerns and asks clients to respond to them. The entire business logic that we implement with Toolset forms and hooks appear as follows:

Implementing this entire logic using only PHP would be a project that lasted many months. Building a flexible GUI that allows all these transitions would cause Forms UI to become bloated. Combining standard elements with tiny glue logic gives us an elegant implementation that only requires several simple PHP functions.