Form Tester API (advanced customization)

From wiki.usabilitytools.com
Jump to: navigation, search

This is the description for Application Programming Interface of UsabilityTools Form Tester tool.

It is aimed at programmers - your IT department after reading this page will know how to customize the Form Tester behavior to your website's needs.

Contents

Getting access to API

Form Tester has static API, what means that global variable is used. You should paste configuration code above the original tracking script line:

 <script type="text/javascript">
   window['UT-FT-API-STATIC'] = {
   // settings go here
   }
 </script>
 <script type="text/javascript">
   (function(s,o,g,a,m){a=s.createElement(o),m=s.getElementsByTagName(o)[0];a.async=1;a.defer=1;a.src=g;m.parentNode.insertBefore(a,m)})
   (document,'script','https://usabilitytools.com/form-tester/rest/script/XXXXX');
 </script>
 

How to handle forms that occur in variants

When the Form Tester tracking script finds out that somebody is using a form on your website, the first thing it does is it checks whether this particular form has been used before. If so - the collected data is aggregated to the previously collected results of this particular form.

The standard form identification mechanism used to differentiate forms takes into account *parameters of the fields* within the form, including:

  • number of fields,
  • position of fields within the form,
  • fields attributes: id, class or name.

This sophisticated mechanism works well in most cases. Although, sometimes this algorithm is too restrictive in telling which form is which, especially when the form depends on the particular user. Such cases include:

  • dynamic e-commerce carts, where the structure of the form differs depending on the number of items in it,
  • dynamic, multi-step forms, where the structure of the form differs depending on the previous user answers.

In such cases it is advised to use less-restrictive identification method, taking into account *form parameters only*. You can use API to switch identification mechanism to one that suites your needs best.

Custom form identification

You can choose form element attributes which should be used to identification. If you don't specify all of them for all your forms, it's OK, our marvelous algorithm can handle that.

 window['UT-FT-API-STATIC'] = {
   // other API stuff
   /* WATCH OUT! default value is true for all options
    * if you ommit some property, it will be set to true
    */
   formId: {
       id: true, // set to false to exclude id attribute from identification
       name: true, // set to false to exclude name attribute from identification
       class: true, // set to false to exclude class attribute from identification
       action: true, // set to false to exclude actione attribute from identification
       data: true // set to false to exclude data-ftid attribute from identification
   }
 };

In some cases choosing right attributes for different forms on the same page can be hard or even impossible. If you can edit forms on your page, add attribute "data-ftid" with unique ID as value, then exclude all other attributes from identification.

 <form data-ftid="MY_UNIQUE_ID_FOR_REGISTRATION_FORM" action="/register" id="F21sad1230" name="123sada21321" class="main-form registration-form"></form>
 window['UT-FT-API-STATIC'] = {
   // other API stuff
   formId: {
       id: false,
       name: false,
       class: false,
       action: false,
       data: true
   }
 };

How to handle fields with variable attributes' value

Custom field identification

Some fields in your form can have attributes containing data like product ID in shopping carts. Form Tester looks on those attributes and recognize every single field as different than others, which in fact have the same role in your form. Such situation is not desired - in this case you can use Form Tester API to make it omit particular attributes in the process of field identification.

 window['UT-FT-API-STATIC'] = {
   // other API stuff
   /* WATCH OUT! default value is true for all options
    * if you ommit some property, it will be set to true
    */
   fieldId: {
       id: true, // set to false to exclude id attribute from identification
       name: true, // set to false to exclude name attribute from identification
       class: true, // set to false to exclude class attribute from identification
       type: true, // set to false to exclude type attribute from identification
       tag: true, // set to false to exclude HTML tag name from identification
       data: true // set to false to exclude data-ftid attribute from identification
   }
 };

For example, if you disable identification by id, two checkboxes like that:

 <input type="checkbox" class="myCheckbox" id="myCheckbox1234" />
 <input type="checkbox" class="myCheckbox" id="myCheckbox5678" />

will get the same field ID, because of they have the same class attribute.

Checkboxes like below will get another IDs, until they have different class names.

 <input type="checkbox" class="myCheckbox" id="myCheckbox1234" />
 <input type="checkbox" class="yourCheckbox" id="myCheckbox5678" />

All attributes you choose will be used during identification process. If you enable, ex. class, tag and type attributes, two inputs like below will have the same ID - "INPUT_checkbox_myCheckbox"

 <input type="checkbox" class="myCheckbox" id="myCheckbox1234" />
 <input type="checkbox" class="myCheckbox" id="myCheckbox5678" />

but another one with additional class "green" will have different ID - "INPUT_checkbox_myCheckbox_green".

 <input type="checkbox" class="myCheckbox green" id="myCheckbox5609" />

Things can be much easier if you decide to make your form with Form Tester in mind. You can specify unique ID for every field (or group of fields) by "data-ftid" attribute. Thanks to this you can group completely different fields in the way what you like. But be careful, if you use wrong IDs, you can break the data!

Two fields below look the same, but will get different IDs because of data-ftid attribute.

 <input data-ftid="REGISTRATION_INPUT_NAME" type="text" class="user_input" /> 
 <input data-ftid="REGISTRATION_INPUT_SURNAME" type="text" class="user_input" />

If you accidentaly use the same ID for some completely different fields, data could be broken.

 <input data-ftid="REGISTRATION_INPUT_SURNAME" type="text" class="user_input" />
 <input data-ftid="REGISTRATION_INPUT_SURNAME" type="checkbox" class="myCheckbox green" id="accept-tos" />

Using API for Submit buttons

In case of problems with correct identification of your form's Submit button - please consult Form Tester Submit Button API

It lets you choose which element of your webpage is the submit button of your form.