Best practices for form design

Introduction

This document specifies best practices for form designers/developers to insure correct interoperability with Fill It by Personal.

The Fill It application is implemented in two parts:

• Bookmarklet that is inserted into a 3rd party page 
• Fill It application hosted by Personal

To ensure correct interoperability, follow these general guidelines:

• Use 'p3name'  - this requires developers have access to the form. This will ensure good Fill It performance. See below for information on how to use 'p3name' attributes.
• Map the form fields using 'Fill It' (can be done by standard users) - See 'Form mapping using Fill It' below.
• Report problem to Personal by "report a problem" link and specifying the form to check. Personal administrator will check the form and map and adjust the mappings if needed.

Fill It Basics

When FIll It is launched, the bookmarklet is loaded into the 3rd party page. The bookmarklet detects all the forms on the page and sends them to Personal.

On the backend, mapping process between form fields and Personal fields is performed for each of the form fields.

Fields are mapped based on the following information:

• 'p3name' property if available. If this is available, Fill It will ignore all other info.  
• Field 'name'
• Field 'label'

The matching process has a few steps:

• Each form field is examined for presence of "p3name" attribute as well as field 'name' and corresponding field label. 
• Explicit Mapping:  If 'p3name' attribute is specified, it will set the mapping.  This mapping will guarantee that your form is matched accurately to the Personal fields. This is the preferred method of mapping.
• Statistical Mapping:  If 'p3name' attribute is NOT specified, the application will recommend mappings based on previous statistics, both global and for this particular form
• Name Mapping: If there are no statistics for this field (form field is visited first time), a name search will be performed and the best result based on name match will be suggested
• Finally, if there is no close name match, this field will be flagged as not-supported.  Future users can update the mapping manually to meet their needs. These fields are not shown in “simple” mode. 

Best Practices for Form HTML structure and elements

These guidelines define how HTML forms and elements should be structured in order to detect correct mapping.

Good Form Development Practices

As a rule of thumb. the simpler the form structure, the better the interoperability. 

Simple form (using 'p3name)

    <label for="firstname">First name</label>

    <input p3name="firstName" id="firstname" type="text" name="firstname"/><br/>

In this case, mapping is explicitly set to 'firstName'. No statistical or name matching will be performed.

SImple form (using labels):

    <label for="firstname">First name</label>

    <input id="firstname" type="text" name="firstname"/><br/>

In this case, statistical mapping will be attempted on field name ("firstname"). If not present, name search will be performed on label ("First name"). 

Poor Form Development Practices

Badly defined form (no labels)

First name

<input id="firstname" type="text" name="firstname"/><br/>

In this case "First name" is just text, not a label. Fill it cannot make a correlation between the input field and corresponding label. Statistical mapping will still work fine, but the first users to visit the form will likely need to change the mappings manually (which will be difficult for non-advanced users). This will also be true for cases when you define labels using some other methods (images, CSS, etc.). 

'fieldset'

It is recommended NOT to use HTML 'fieldset' when designing forms.

Hidden fields

Fill It skips all the hidden fields on the form. If hidden fields are used for data submission, Fill It will not be able to populate them.

Javascript and data mangling

If the form uses javascript for data handling, moving it to hidden fields or some other data manipulation, Fill It may not be able to correctly fill the form.

[Do we want to comment on using Flex here or any other formats not covered?]

Using Fill It with fully validated personal fields

Some of the fields in Personal are marked as 'fully validated'. This applies to finite enumerations such as gender (Male/Female), state (50 state list), countries (country list), etc. When designing forms with fields that map to one of these fully-validated fields, form designers should review the list of available values and appropriate formats. If possible, form designers should use field values provided by Personal. Personal uses standard enumeration types and works hard to keep them up-to-date. If there is a problem with missing values, please send us feedback, and we will try to address the problem.

Field formats

Some personal fields are supported in multiple formats. When searching through the list of fields, format identifiers are shown in {<format id>}. When mapping to form fields, only compatible formats are shown.

For example, 'state' field can be specified in long or short format. When defining forms, both of the form specifications will work.

Long 'state' format.

<label for="state">State (long)</label><br/>

<select name="state" id="state">

    <option value="alabama">Alabama</option>

    <option value="alaska">Alaska</option>

</select>

Short 'state (abb)'

<label for="state1">State Short</label><br/>

<select name="state1" id="state_short">

    <option value="al">AL</option>

    <option value="il">IL</option>

</select>

Form mapping using 'Fill It' application

The Fill It application supports changing field mappings as one of its standard features.

Field mappings can be changed by clicking on the field name to the left of the field and searching and selecting the appropriate Personal field name. It is easy to see which field on the form matches to the field in Fill It because of the green highlight on the form field. Different mapping options also list the compatible field formats (see below in 'formats' section) Once the new mappings are selected and form is submitted, the new mappings are included in mappings statistics and the most popular mapping will be displayed to future visitors to your form.

If there is not a match for your form field in Personal, the field can also be marked as "not supported".

In 'simple' mode (default), all the 'not supported' fields are hidden. This simplifies the user experience for non-advanced users. Clicking on 'advanced' shows all the fields including 'not supported' ones.

Pubished value for 'p3name' attribute and formats

preferred_name.people.person.name