Re-filling form fields using the API

This tutorial is for version 2.x of the API, which is for Form Tools 3. If you're using Form Tools 2, please check out this tutorial instead.

Once you get into the wonderful world of creating 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
If you want to include a "review" page where the user can see the values they're entered, 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 incorrectly, you'll need to re-enter the form fields to prevent them having to type them in again.

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 initFormPage() method

If you've dutifully followed the instructions in the API and the multi-page tutorial, you've added the initFormPage() PHP call to each of your pages. In addition to the other stuff it does, this method also returns all form values in a single PHP array.

$fields = $api->initFormPage();

The following explains how to re-fill fields of all different types. Several of the examples assume that PHP short tags are enabled on your system. If not, you can use the full PHP tags.

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