Configuring your form page

Make sure your form has been given a .php extension (the API requires your files to be PHP files - not HTML), then add the following PHP to the very top of your page with a few minor modifications listed underneath:

• The path to the api.php file has to be updated, depending on where it's located in relation to your form.
• Change "submit_button_name_attribute" to whatever the name attribute of your form submit button may be. If it doesn't have one, add it!
• Change "thanks.php" to whatever page you want to redirect to, after the form has been submitted.
• You can omit the "file_data" line if your form doesn't contain any file upload fields.

Next, make sure your form tag looks like this:

Because no action attribute is included, the form will submit the information to itself. The processFormSubmission() method will take care of redirecting to the next page for you. One of the nice things about posting the submission to itself is that if later on, you choose to add server-side validation (see this tutorial), it's very easy to handle and display the errors on the same page.

If you are uploading files through your form, also include the enctype attribute, like so:

With regard to the form's post attribute, if you want to use method="GET", that's fine - just change the value in the form method attribute to "GET" and change the PHP line in the top of the from:

That lets the API know where to look for the form submission data. Finally, put through a form submission. You should be redirected to your "thank you" page. So far so good! Nothing is being stored in Form Tools yet, but we're getting there.

Explanation of code

If you're not interested in the details, ignore this section and go to the next step. It's just for those of you who are curious.

The code does a number of things. First, the initFormPage() function initializes the page environment; precisely what it does depends on the "mode", i.e. whether the form is in "test" mode (like now), "initialize" mode (when you put through the test submission to Form Tools later) or "live", when everything's been configured. But one thing it ALWAYS does is start PHP sessions to provide storage for the form values and "meta" info (like submission and form ID) as the user progresses through the form.

Note that the initFormPage() method returns a $fields variable. This variable contains all the form field values entered up to that point. So, imagine you added some server-side validation that threw an error after the user submitted the form. You could use the $fields variable to reload all the values entered. (For more information on that, see the Adding Server-Side (PHP) Validation to your Forms and Re-filling form fields with the API tutorials.

The processFormSubmission() function is the main workhorse function: it does the job of adding the information to the database and redirecting, based on whatever values you pass to it.

"Direct" form types that submit their content directly to the process.php script and have the submission added in on go AFTER the user had submitted the form. The API works the other way round. Once your form is live, the initFormPage() actually creates a blank submission BEFORE the user has even filled in a field. Then, each form submit will update those fields included in the form submission. Only when they are actually finalized (i.e. the "finalize" => true parameter is passed to processFormSubmission()) is the submission made visible within Form Tools. This has a number of benefits, including the fact that it allows you to separate your form into multiple pages, updating separate fields bit by bit. Also, it's compatible with adding an external mechanism to allow people to return later on to complete setting up their form.