Re-filling form fields using the API

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.

$fields = ft_api_init_form_page();

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

Text fields

To re-fill a text field, you just need to load the value attribute from the $fields array, like so:

<input type="text" name="my_textfield1" value="<?=@$fields["my_textfield1"]?>" />
<input type="text" name="my_textfield2" value="<?=htmlspecialchars(@$fields["my_textfield2"])?>" />

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.

Textareas

HTML-encoding the content for textareas is not necessary, since the content is not loaded within a double-quote encapsulated attribute.

<textarea name="my_textarea"><?=@$fields["my_textarea"]?></textarea>

Radio Buttons

<input type="radio" name="my_radio" value="one" <?php if (@$fields["my_radio"] == "one") echo "checked"; ?> /> Radio Button 1<br />
<input type="radio" name="my_radio" value="two" <?php if (@$fields["my_radio"] == "two") echo "checked"; ?> /> Radio Button 2<br />
<input type="radio" name="my_radio" value="three" <?php if (@$fields["my_radio"] == "three") echo "checked"; ?> /> Radio Button 3

Checkboxes

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.

<!-- a single checkbox -->
<input type="radio" name="my_single_checkbox" value="one" <?php if (@$fields["my_single_checkbox"] == "one") echo "checked"; ?> /> Checkbox 1

<!-- a group of checkboxes -->
<input type="checkbox" name="foods[]" value="pizza" <?php if (@in_array("pizza", $fields["foods"])) echo "checked"; ?> />Pizza<br />
<input type="checkbox" name="foods[]" value="pasta" <?php if (@in_array("pasta", $fields["foods"])) echo "checked"; ?> />Pasta<br />
<input type="checkbox" name="foods[]" value="seafood" <?php if (@in_array("seafood", $fields["foods"])) echo "checked"; ?> />Seafood<br />
<input type="checkbox" name="foods[]" value="chinese" <?php if (@in_array("chinese", $fields["foods"])) echo "checked"; ?> />Chinese<br />

Dropdown

<select name="marital_status">
	<option value="">Please select</option>
	<option value="married" <?php if (@$fields["marital_status"] == "married") echo "selected"; ?>>Married</option>
	<option value="single" <?php if (@$fields["marital_status"] == "single") echo "selected"; ?>>Single</option>
	<option value="common-law" <?php if (@$fields["marital_status"] == "common-law") echo "selected"; ?>>Common-law</option>
	<option value="divorced" <?php if (@$fields["marital_status"] == "divorced") echo "selected"; ?>>Divorced</option>
</select>

Multi-select Dropdown

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.

<select name="authors[]" size="4" multiple>
	<option value="bunin" <?php if (@in_array("bunin", $fields["authors"])) echo "selected"; ?>>Bunin</option>
	<option value="chekhov" <?php if (@in_array("chekhov", $fields["authors"])) echo "selected"; ?>>Chekhov</option>
	<option value="dostoevsky" <?php if (@in_array("dostoevsky", $fields["authors"])) echo "selected"; ?>>Dostoevsky</option>
	<option value="gogol" <?php if (@in_array("gogol", $fields["authors"])) echo "selected"; ?>>Gogol</option>
	<option value="karamzin" <?php if (@in_array("karamzin", $fields["authors"])) echo "selected"; ?>>Karamzin</option>
	<option value="olesha" <?php if (@in_array("olesha", $fields["authors"])) echo "selected"; ?>>Olesha</option>
	<option value="pushkin" <?php if (@in_array("pushkin", $fields["authors"])) echo "selected"; ?>>Pushkin</option>
	<option value="tolstoy" <?php if (@in_array("tolstoy", $fields["authors"])) echo "selected"; ?>>Tolstoy</option>
	<option value="turgenev" <?php if (@in_array("turgenev", $fields["authors"])) echo "selected"; ?>>Turgenev</option>
</select>

DOCUMENTATION