ft_api_process_form

API

Overview

The simplest way to store form submission data is by submitting your form to process.php; the information is stored, the user is redirect to some sort of "thank you"page and everyone gets on with their life. This method, though the simplest, doesn't allow for more complicated scenarios, such as:

You want to add server-side validation to ensure the information is valid before adding to the database.
You have a multi-page form and need to submit the data only on the very last step.
You have a multi-page form and need to store the data page-by-page as the user progresses through the form.
You want to submit the information, but don't want it to appear in the Form Tools UI until a later date.

Enter the API. The API comes with a number of functions designed to let you submit the information via PHP code, rather than through the more restrictive process.php POST script. The most important of these functions is the ft_api_process_form() function. For those of you familiar with earlier version of Form Tools, this function replaces the older process_form() function used for "code" submission types, and was found in the (now deprecated) process_code.php file.

Fundamentally, Form Tools doesn't care HOW the information gets into the database. What's important is that it gets there.

Finalizing submissions

Every form submissions in the Form Tools database has a finalized flag: "yes" or "no". By default, submissions sent via process.php are set to finalized. Submissions sent via ft_api_process_form() are NOT finalized. Only finalized submissions appear in Form Tools.

Parameter keys

For completion, here's all the values that may be passed via the single parameter (a hash). But we strongly suggest giving one of the above tutorials a read first, otherwise this won't make all that much sense.

1. Required keys

submit_button

The name attribute of your submit button. This is needed to let the function know when to try to process the form. If the name attribute isn't in the POST request, the function does nothing.

form_data

Generally this is the $_POST or $_GET. It contains the contents of the form just submitted.

file_data

If your form contains one or more file upload fields, you'll need to include this key, passing along the $_FILES value ("file_data" => $_FILES).

2. Optional keys

next_page

The URL (relative or absolute) of which page to redirect to (e.g. the next page in the form or the "thankyou" page). If this isn't defined, it doesn't redirect anywhere.

finalize

This tells the function to finalize the submission. This makes the submission appear in the Form Tools UI, so generally you'll only want to pass this value on the final step of your form - otherwise, for multi-page forms, incomplete submissions will appear in the Form Tools interface.

no_sessions_url

For multi-page forms it's a good idea to pass along this value. It should be the URL of a page (usually the FIRST page in the form sequence) where the user will be redirected to if they didn't start the form from the first page. It ensures the form submission gets created & submitted properly.

may_update_finalized_submissions

This is pretty descriptive! It lets you control whether or not a finalized submission may be updated or not. It's set to true by default, as of 1.0.0.

namespace

If you specified a custom namespace for ft_api_init_form_page, for where the form values will be stored temporarily in sessions, you need to pass that same value to this function - otherwise it won't be able to retrieve the form and submission ID.

send_emails

Added in 1.0.1. (boolean). By default, Form Tools will trigger any emails that have been attached to the "on submission" event ONLY when the submission is finalized (finalize=true). This setting provides you with direct control over when the emails get sent. If not specified, will use the default behaviour.

API

Overview

Finalizing submissions

Related Links

Parameter keys