Introduction

AFD Robot Web version makes using address management and bank validation with web sites easy. Both internal use and public website use are supported (although the exact use of your software will be limited by the terms of your license agreement with AFD). Automatic configuration and detection of fields is supported even when you have no control over the website layout or functions.

Setup

Include the AFD Robot script and token on the web pages that you wish to use Robot Web with, it will identify the relevant fields automatically. In most cases it’s as simple as that, depending on your product licence AFD Robot Web will recognise when you enter a postcode or bank details, and present the result to you.

For situations where you do not have access to the source code of the web page you want to use Robot with, we have browser plugin and proxy server solutions which may be suitable. Contact AFD Technical Support on 01624 811712 and ask for a Browser plug-in or Proxy Server integration.

Including the Robot Web Script on your Website

To include the Robot Web Script on your website, carry out the following steps:

  1. Copy the afdrobottoken.js you will have received from AFD to an appropriate location on your website
  2. Locate your end body tag (</body>) for any pages that you wish to use Robot with and immediately prior to that add both the token and robot include script

For example:

<script src="afd.robot.token.js" type="text/javascript"></script>
<script src="//apps.afd.co.uk/robot/afd.robot.2.0.5.js" type="text/javascript"></script>
</body>

If possible you may prefer to host the Robot script on your own website, and in which case the apps.afd.co.uk can be removed or altered as appropriate.

If you are unable to host the afd.robot.token.js file on your own website then instead set these in the afdRobotOptions settings, see the Customising Robot section of this manual

Robot will now work automatically with address entry on that page. You can add additional configuration options to customise how Robot works; see the Customising Robot section of this manual.

Using Robot

Address Entry

To use Robot simply type the postcode, or property name/number followed by a postcode in a website and you will then be prompted to select the address to insert.

Simply select the address you wish to Insert and click the "Select This Address" button to insert it into the page.

Robot will detect your applications fields and insert the address. See Customising Robot if you wish to tweak how Robot inserts the address.

The "Find" box at the top also allows you to enter a different postcode or a fast-find search, for example "Commercial Street, Birmingham" if the address you were looking for was not found (for example you entered the wrong postcode). For more examples of what you can type in the "Find" box see the main product manual.

Bank Account / Card Number Validation

Robot also supports Bank Account Number and Card Number validation (subject to a separate licence fee). This enables client side validation of an account or card number entered. Using this functionality requires custom configuration of Robot to either enable it on pressing a specific "hot key" combination on the keyboard or by adding a button to a specific web-page to trigger it. When triggered, a message will be displayed to indicate if the number entered is valid or otherwise.

For details on how to configure this please see Customising Robot of this manual.

Email Validation

Robot also supports Email validation. This enables client side validation of an email address entered. Using this functionality requires custom configuration of Robot to either enable it on pressing a specific "hot key" combination on the keyboard or by adding a button to a specific web-page to trigger it. When triggered a message will be displayed to indicate if the email address entered is valid or not.

For details on how to configure this please see Customising Robot of this manual.

Hot Key Support for Reverse Address Searching

Robot also supports the use of Hot Keys. Pressing the Hot Key carries out a fast-find from your webpage allowing you to enter a fast-find string where the postcode is not known, e.g. "Commercial Street, Birmingham" press the Hot Key and have Robot look up the address for you.

For details on how to configure hot keys please see Customising Robot section of this manual.

Customising Robot

By default Robot functions with all webpages if used as a plug-in or through a proxy. It also attempts to autodetect fields on a webpage. You can customise the way robot works to restrict it to a single page or site and, even when included on a single page, customise the fields it works with. Options are also provided to allow you to add a lookup field and button to pages you have control over.

To customise Robot you need to add a script block prior to the Robot JavaScript include in your webpage with the structure given below.

<script>
    afdRobotOptions={
        // If you are unable to host afd.robot.token.js, uncomment the following two
        // lines and update them with your details.
        // id: "ID_NEEDS_TO_GO_HERE",
        // token: "TOKEN_NEEDS_TO_GO_HERE",
        showFastFind:true,
        autoInsert:false,
        msgPostcodeFirst:" This form has postcode lookup enabled. Type the postcode to automatically fill out the rest of the address.",
        /* hotKey:{
            keyCode: 91, // [
            ctrl: true,
            alt: true,
            shift: false
        },
        accountHotKey:{
            keyCode: 66, // B
            ctrl: true,
            alt: true,
            shift: false
        },
        cardHotKey:{
            keyCode: 67, // C
            ctrl: true,
            alt: true,
            shift: false
        },
        emailHotKey:{
            keyCode: 93, // ]
            ctrl: true,
            alt: true,
            shift: false
        },
        */
        globalEnable:true,
        // exceptions:new Array("www.afd.co.uk"),
        autoFields: true,
        /* robotFields: new Array(
            new Array("#GridE", "GridEast"),
            new Array("#GridN", "GridNorth")
        ),
        */
        // lookupField: "#lookupField",
        // sortcodeField: "#sortcode",
        // accountField: "#account_number",
        // cardField: "#card_number",
        // emailField: "#email_address",
        // lookupButton: "#lookupButton",
        // cardButton: "#cardButton",
        // accountButton: "#accountButton",
        // emailButton: "#emailButton",
        upperCaseTown: true
        // pceURL:"//apps.afd.co.uk/json/pce/lookup",
        // jQuery: "//ajax.googleapis.com/ajax/libs/jquery/1.10.2/jquery.min.js",
        // jQueryUI: "//ajax.googleapis.com/ajax/libs/jqueryui/1.10.2/jqueryui.min.js",
        //jQueryUICSS:"//ajax.googleapis.com/ajax/libs/jqueryui/1.10.2/themes/redmond/jquery-ui.css"
        // jQuery18UI: "//ajax.googleapis.com/ajax/libs/jqueryui/1.8.24/jqueryui.min.js",
        // jQuery18UICSS:
        "//ajax.googleapis.com/ajax/libs/jqueryui/1.8.24/themes/redmond/jquery-ui.css"
    }
</script>

The options above are set to the defaults Robot uses and those that aren’t used by default are commented out to provide examples so this can be used as a starting point for your own configuration. Any settings you don’t wish to change from the default can be removed if you wish. The settings are described in the following sections:

Customising how the Robot Dialog Appears

The following settings alter how the Robot Dialog Appears:

  • showFastFind: When true (default) the Fast-Find box is shown on the Robot dialog allowing reverse searches to be carried out. If you do not wish this to be shown, for example on public websites where postcode lookup only functionality might be required, simply set this to false. Note this does not apply when a dialog is displayed from the hotkey as in this case the find box is required to enter the lookup.
  • autoInsert: When true the Robot dialog will not appear if there is only one matching address for a lookup, the address will instead be automatically inserted into the webform. By default this is set to false.
  • msgPostcodeFirst: If a user attempts to enter an address into an address field without using the postcode first a message is displayed (only once) to recommend lookup from the postcode. This specifies the message to display. If set to a blank string ("") then this functionality is disabled.

Hot Key Options

Hot Keys can be enabled to allow reverse address searching from a key combination and/or bank, card and email validation.

  • The hotkey section applies to a hot-key used to bring up the Robot window for reverse searching using the Find Box.
  • The accountHotKey section applies to a hot-key used to validate an account number entered on the form. Robot will attempt to auto-detect the sort code and account number fields and display if the number entered is valid or not. You can also use the sortField and accountField properties to specify the id of the form fields to use to override auto-dectection of these fields.
  • The cardHotKey section applies to a hot-key used to validate a card number entered on the form. Robot will attempt to auto-detect the card number field and display the card type if it is a valid number or inform the user if it is invalid. You can also use the cardField property to specify the id of the form field to use to override auto-dectection of this field.
  • The emailHotKey section applies to a hot-key used to validate an email address entered on the form. Robot will attempt to auto-detect the email address field and display a message as to if the email address is valid or not. You can also use the emailField property to specify the id of the form field to use to override auto-dectection of this field.

To specify each Hot Key the following options are used:

  • keyCode: This specifies the JavaScript key code of the key to use. Most commonly used is 65 thru 90 which specify the keys A – Z on the keyboard.
  • ctrl: This specifies that the CTRL (or Control) key should be held down along with the key specified by keyCode
  • alt: This specifies that the ALT key should be held down along with the key specified by keyCode
  • shift: This specifies that the Shift key should be held down along with the key specified by keyCode

It is vital that you specify at least one of the CTRL / ALT keys with a normal keyboard character otherwise the site will be unusable as the hot key will be triggered on normal keyboard input. It is also important to avoid keys used for normal web browser functions so please try the combination in all browsers you support prior to selection.

Field Insertion

By default Robot auto-detects address fields on a form to insert. Postcodes will be picked up from any field; however others may need to be configured. If you need to tweak these settings, or wish to map back a nonaddress field then you can do so with these options. If using these you will wish to include the script on each web form in most cases as you may require different settings for different pages.

  • autoFields: When true (default) Robot auto-detects address fields to set into. If configuring all fields manually you can set this to false.
  • robotFields: This is a two dimensional array of field mappings. Each item has a string with the identifier of the field on your form to place the resulting field value into along with the field to map too. These fields are any of those returned by the Postcode Evolution service when using Standard fields. The identifier can either be the hash symbol followed by your field name, e.g. "#fieldid", or its name selected using "[name=’fieldname’]".
  • upperCaseTown: When true (default) the Town is returned in uppercase as recommended by Royal Mail for correct addressing of mail. However if you are using the Town for other purposes or wish to store it mixed case you can set this option to false.

Buttons and search fields

If you wish to add (or already have) a button on your form that you would like to trigger a fast-find address lookup or an account, card or email validation you can configure mappings from those buttons to Robot here. You can also specify the field on your form that will contain the value to lookup or validate.

  • lookupField: Specifies the identifier of the field where the user will enter a fast-find address string to search for
  • sortcodeField: Specifies the identifier of the sort code field to validate
  • accountField: Specifies the identifier of the account number field to validate
  • cardField: Specifies the identifier of the card number field to validate
  • emailField: Specifies the identifier of the email address field to validate
  • lookupButton: Specifies the identifier of the button to trigger a fast-find lookup using the lookupField
  • accountButton: Specifies the identifier of the button to trigger an account validation using the fields specified by the sortcodeField and accountField options.
  • cardButton: Specifies the identifier of the button to trigger a card validation using the field specified by the cardField option.

In each of these settings the identifier can either be the hash symbol followed by your field name, e.g. "#fieldid", or its name selected using "[name=’fieldname’]". This is standard jQuery selector syntax.

Local Installation of Robot

Hosting Robot with no Internet access is described in the section: Local Installation of this manual. These settings are useful when using that mode:

  • pceURL: Sets the path to the Evolution server with JSONP support for providing the address management/validation functionality.
  • jQuery: Provides an alternative location to download the jQuery library from
  • jQueryUI: Provides an alternative location to download the jQuery UI library from
  • jQueryUICSS: Provides an alternative location to download the jQuery UI Style Sheet from
  • jQueryUI18: Provides an alternative location to download the jQuery UI 1.8.24 library from (only necessary if used with pages using jQuery lower than version 1.6)
  • jQueryUICSS18: Provides an alternative location to download the jQuery UI 1.8.24 Style Sheet from (only necessary if used with pages using jQuery lower than version 1.6)

Robot Dialog Look and Feel

The Robot Dialog uses the JQuery UI library to govern its look and feel. Robot will only load JQuery, JQuery UI and a JQueryUI style sheet if you are not already using one on your website. Therefore if you are using Robot with a specific webpage and are already using JQuery UI in your webpage the Robot dialog will already take on your desired look and feel.

If you are not using JQuery UI you can still change the one used by Robot by including one for this purpose (even if you use a differing JavaScript library these can co-exist for this purpose).

Add to the header of your webpage for the style sheet Robot uses by default:

<link rel="stylesheet" type="text/css" href="http://ajax.googleapis.com/ajax/libs/jqueryui/1.10.2/themes/redmond/jqueryui.css">

However, you can also add any other theme as desired, refer to the JQuery UI docs regarding those available and how to produce custom versions if you so wish.

Add the following to the body of your webpage, at any point prior to the robot JavaScript:

<script src="//ajax.googleapis.com/ajax/libs/jquery/1.10.2/jquery.min.js"></script>
<script>$.noConflict();</script>
<script src="//ajax.googleapis.com/ajax/libs/jqueryui/1.10.2/jqueryui.min.js"></script>

The first two entries load JQuery itself and place it in noConflict mode so that it cannot conflict with any other JavaScript libraries you may be using (omit if you already use JQuery on your page). The second line loads JQuery UI.

If you are using a version of JQuery lower than 1.6 use version 1.8.24 of JQuery UI instead, i.e:

<script src="//ajax.googleapis.com/ajax/libs/jqueryui/1.8.24/jqueryui.min.js"></script>

Robot uses these scripts from the widely used googleapis.com by default as these are the most likely to already be cached by the user. However you can use any other hosted versions or host them yourself if you prefer. If you load them, Robot won’t so you gain full control of those scripts. If you are using Robot through a proxy or for a number of sites and would to change the default style used you can set the jQueryUICSS property as given in the section: Local Installation of Robot (under Customising Robot).

Local Installation

In general Robot will be running on websites where web access is by its nature not a problem. However there are scenarios where you may wish to have Robot completely running on your own local server, for example if you have a highly restricted firewall in place, or are using a non-Internet connected network.

The steps to have this running locally are as follows:

Host the required JavaScript on your own system or server

You will need to download the robot script and its jQuery dependencies onto your own internally hosted system.

The required files are:

  • Afd.robot.2.0.5.js
  • jquery.min.js
  • jquery-ui.min.js
  • jquery-ui.css (and any associated images etc.)

If you are already using jQuery and jQueryUI on your page there is no need to download those files, otherwise we recommend you download them from the following locations:

If you are already using jQuery and only require jQueryUI, if your version of jQuery is less than 1.6 please use

  • jqueryui/1.8.24 instead of the above version.

Set Path to Evolution Host

You will need your own Evolution Host setup with the addition of JSONP support – see separate Evolution Installation Guide.

You then need to inform Robot to use this URL rather than the default (which is AFD’s servers). You do this by setting the pceURL to the relevant path in the Robot Configuration as described in the section: Customising Robot. If you need to do this but don’t wish to change any other options the minimum to add is, prior to inclusion of the Robot JavaScript:

<script>
 afdRobotOptions={
pceURL:"//myhost/jsonp/lookup",
 }
</script>

Reference the local jQuery files

You will also need to reference these jQuery files in your page or ask Robot to do so. To inform Robot of the location of these files you can do this by setting the jQuery, jQueryUI and jQueryUICSS options to the ppropriate locations, i.e. as above but with these set for the root of myHost:

<script>
    afdRobotOptions={
        pceURL:"//myhost/jsonp/lookup",
        jQuery="//myHost/jquery.min.js",
        jQueryUI="//myHost/jquery-ui.min.js",
        jQueryUICSS="//myHost/jquery-ui-css",
        jQueryUI18="//myHost/jquery-ui.min.js",
        jQueryUICSS18="//myHost/jquery-ui-css"
    }
</script>

Note that the jQueryUI18 and jQueryUICSS18 variables are only necessary if you are using Robot which have, or may have, a version of jQuery lower than 1.6 in use.

Alternatively on your webpage when including the robot JavaScript you can also need to include the jQuery scripts and style sheet yourself if you have not already got those that are in-use on your page. Instructions for how to do this are in the section: Local Installation of Robot (under Customising Robot) of this manual (simply path to your server rather than Google’s).