This tutorial is for version 1.x of the API, which is for Form Tools 2. If you're using Form Tools 3, please check out this tutorial instead.
Once you get into the wonderful world of multi-page forms (or even single-page forms with server-side validation), you often need to access and display the values the user has entered up to that point. Here's a couple of cases where this is handy:
- If a user clicks back to a previous page to re-edit a field
- You want to include a "review" page where the user can see the values they're entered in the form up to that point, to ensure they're submitting the correct information.
- Your form contains a CAPTCHA that prevents them from continuing until it's entered correctly. If entered improperly, you'll need to re-enter their values to prevent them having to re-fill them.
The good news is that if you're using the API functions, this isn't terribly hard to do. The bad news is that it *does* require getting your hands a little dirty. This tutorial is less about the API than it is about basic PHP.
The ft_api_init_form_page function
If you've dutifully followed the instructions in the API and the multi-page tutorial, you've added the ft_api_init_form_page() PHP call to each of your pages. In addition to its other functionality, this returns all form values in a single PHP array.
The following explains how to re-fill fields of all different types. A few examples assume that short tags are enabled on your system (). If they're not, you can use instead. The two are synonymous.
The @ symbol isn't strictly necessary; it's included in case you have error reporting turned up high. If the array keys don't exist, it will throw a minor notice. The @ character suppresses those notifications.
Form field types
To re-fill a text field, you just need to load the value attribute from the $fields array, like so:
The second line is similar to the first except that it encodes the content. This is necesary if the field is likely to contain double quotes. If it DOES, the HTML will be invalidated and it won't display properly. In most other cases, you don't need to encode it.
HTML-encoding the content for textareas is not necessary, since the content is not loaded within a double-quote encapsulated attribute.
Note the  characters on group of checkboxes section. To pass along multiple values for a group of form fields with the same name, those characters are necessary.
Note the  characters in the name attribute of the select tag. They are required to pass along multiple values for a single form field like this.