UI for Postcode Anywhere address look-up

• » Overview
• » Usage & params
• » Example
• » Notes

Overview

This UI for the Postcode Anywhere look-up service takes the hassle out of integration. Just set a few vars in the JS file, call it into your site, and the script does the rest. It DOM-scripts all the relevant elements that support it, such as the look-up <link>/<button> and the neat scrolling <div> that then appears beneath your field that displays returned addresses as links. Clicking one populates your form - it's that simple.

Usage & params

Set the config vars

To use the UI, first set two config variables in the main js.js file:

pathToPHPScript - the path to the PHP file curl_to_API.php which acts as a middle man between the script and the PA service. Update this relevant to your server

fieldsToDataMap - a map of form field names to data field names returned by the PA web service. Update this with the names of your fields (left) and the data fields you need the PA web service to return (right). Note: the PA service can return more than just basic address info - see notes.

...and two vars in the curl_to_API.php file:

pa_user - your Postcode Anywhere username

pa_apikey - your Postcode Anywhere API key (ensure it has some balance on it)

Calling the script

Next to your postcode field, put an inline script which calls new palookup(params);, where params is an object of property/value pairings from the following:

postcodeField (string) - a string representing the ID or jQuery selector text of your form's postcode field

button (bool) - if true, the script will DOM-script a <button> as the invoker, not a link

cssObj (object) - an object of CSS property/value pairings to further style the invoker link/button

cssClass (string) - a CSS class to be applied to the invoker link/button

absolute (bool) - by default, the invoker link/button will be appended to the DOM after your postcode field. If you don't want the script to affect the fluidity of your layout, passing this parameter will position the invoker absolutely instead

callback (function) - a callback function to be called once an address is selected. The script will pass the returned JSON data object to it as the only argument.

Example

Here's the code behind that example, in an inline script after the postcode input field.

Note the callback in this example, which reads the returned country value for the selected address and updates our countries !.

Notes

Global config

You can set global config options for all instances of the look-up in the script file itself, in the config section near the top. If nothing else, make sure you update the pathToPHPScript and fieldsToDataMap vars - see Usage & params above.

More than just street and town

As well as basic address info the PA web service can return a lot of other data, too, such as building name or, for company addresses, department. Click here for a full list of available returnable data. To change or add to the data returned, simply update the fieldsToDataMap fields-to-data map.

JSON

This script uses Postcode Anywhere's JSON API, meaning the returned addresses data is in JSON format, so note this when dealing with it in any callback function you specify.

Multiple instantiation

This script is object-oriented so you can have multiple instances of it on your page, should you wish. Remember to prefix each instantiation with new.

cURL

The utility PHP file included, which acts as a middle-man between the AJAX request and the Postcode Anywhere API, requires the cURL library to be installed. Usually it is by default, but you can confirm this by running phpinfo().

Loading jQuery

By default, this script assumes you're loading jQuery via Google (why might you do this?). If, instead, you're loading jQuery from a local copy in your site folder, update the document ready handler (DRH) in the script file: