AddressServerin the Cloud

AddressCleanse

AutoComplete JavaScript Client

Can't find what you're looking for?

Overview

The AutoComplete JavaScript Client is a code snippet that you can add to a web page to give it address capture capability. Please see the below Demo for an idea of the imparted functionality.

The capability does not require the installation of any files (as these can be referenced on the hosted service), but if having local service files is your preference, these can be downloaded from here. Subsequent references to cloud.hopewiser.com in the code would then been replaced with a local reference of your choosing.

The AutoComplete JavaScript Client sample code download provides a sample webpage (for HTML or PHP) illustrating the standard functionality. This can be tweaked and adapted to suit the need.

Demo

Quick Start

Need to have generated a service Authorisation Code using the service Authorisation Code Generator (giving a Base64 encoded value based upon the username and password of a Hopewiser AddressServer in the Cloud service user).

Download, unzip, and extract the AutoComplete JavaScript Client sample code to an appropriate directory in a web server (for HTML or PHP).

Add the Authorisation Code from above (in the HPW.FindAddress() auth section) and the MAF ID of a dataset available to the account referenced in the HPW.FindAddress() dataset section.

Start up the servlet container publishing the sample web page giving sight of the standard functionality from any web browser.

Basics

1. How do I install AutoComplete JavaScript Client?

In the <head> of your web page, add these lines (replacing 'https://cloud.hopewiser.com/jsclient' with the relative path of the folder you used above, if you chose to install these files on your own web server):

Before the </body> closing tag of your web page, add these lines (replacing 'https://cloud.hopewiser.com/jsclient' with the relative path of the folder you used above, if you chose to install these files on your own web server):

optionally, parameters to influence other service behaviours referenced in the below Optional Parameter table.

Mandatory Parameter

Description

auth

A valid authorisation code is required to access the required dataset.

dataset

A dataset ID associated with the MAF and AutoComplete database files.

input

The search field to invoke the AutoComplete address lookup.

output.line1 to output.line2

The first two lines of the formatted label for the selected address.

Optional Parameter

Description

server

This is the URL to the AutoComplete Server. It defaults to "https://cloud.hopewiser.com".

minLength

This is the minimum number of characters a user must type before a search is performed. Its default value is 1.

delay

This is a delay in milliseconds between when a keystroke occurs and when a search is performed. No menu will be displayed until the typist pauses for the specified delay period after the last keystroke. Its default value is 300.

outputlines

This parameter is used to specify the maximum number of formatted output lines which should to be mapped accordingly in the "output.line" block. Allowed range is 2 to 9. Its default value is 7.

output.line3 to output.line9

Configure field mappings to include additional address label lines.

output.country

Configure a field mapping to include the country field information.

'detail' matched address output fields

This optional configuration section contains mapping information for some of the common address output fields.

The available detail elements will depend on your dataset. To view the available detail elements, visit:

Calls a callback function at the end of populating the returned address if this parameter is configured.

LabelFormat

Select the position of the town, county and postcode within the formatted address label. Allowed values are Standard (the default), FixedPostcode or FixedTown.

The value FixedPostcode reserves the last line of the formatted address label for the postcode and forces it to be output on a separate line.

The value FixedTown reserves the last three lines of the formatted address label for the town, county and postcode and forces each value to be output on a separate line. Please note that a line is reserved for the county even if none is output.

When a fixed value is requested, the formatted address label will comprise the maximum allowed number of address lines, some of which may be empty.

ReserveOrganisationLine

Select the position of the organisation within the formatted label. Allowed values are Always, Never or AsRequired (the default).

The value AsRequired includes the organisation within the address label following standard formatting rules.

The value Always reserves the first line of the formatted address label for the organisation and forces it to be output on a separate line. If there is no organisation then the first line will be empty.

The value Never removes the organisation from the formatted address label.

IncludeCounty

Select when the county should be included within the formatted address label. Allowed values are Always, Never or AsRequired (the default).

DropCountyToFitLabel

Select if the county may be dropped when it does not fit within the formatted address label. Allowed values are Never (the default), or Always.

TownFormat

Select the required town format. Allowed values are Uppercase (the default) or Lowercase.

(Replace yourAuthCode with your authorisation code and the example HTML IDs with your actual HTML IDs.) If you do not specify an ID for line3..line6, the returned address will be formatted to fit the available lines. The county ID should be used in conjunction with the IncludeCounty parameter, and must be specified when the county is required. If you do not specify an ID for country, then it will be omitted. The input field does not have to be a separate field; it can be one of the output fields, in which case it would most likely be the postcode field.

2. How do I lookup an address?

Key in a search criteria into your input field, an autocomplete menu will be automatically displayed when the minimum length and delay conditions are met and one or more matched items is/are return from the AutoComplete server. You can narrow down the search by either keying in more information or select one of the returned items from the autocomplete menu. The menu will be closed automatically either by pressing the "ESC" key to abort the search or by selecting a fully completed address from the menu.

3. How do I troubleshoot my installation?

NOTE: your web page must be served up via a web server, using the http:// or https:// protocol. The AutoComplete JavaScript Client will not work if you open your web page directly from the file system, using the file:// protocol.

When the autocomplete enabled web page is loaded, the AutoComplete Javascript Solution will check field mapping and configuration information for errors. When an error is detected, a message window will be displayed. The solution might not function correctly until the error is corrected.

1. How do I install AutoComplete JavaScript Client service files locally?

You do not have to download anything to use the AutoComplete JavaScript Client because your web page can reference the necessary files on our servers. However, if you'd like to download the client files and install them on your own web server, you can. Download the AutoComplete JavaScript Client files from here.

Uncompress the downloaded AutoCompleteJavaScriptClient.zip file and then upload the extracted files to a suitable location on your web server.

2. How do I customise an address label?

Variations in the appearance of an output address label are achieved, in the AutoComplete JavaScript Client solution, via five optional parameters in the FindAddress() function call – LabelFormat, IncludeCounty, DropCountyToFitLabel, ReserveOrganisationLine, and TownFormat. For full details on each, please refer to the How do I install AutoComplete JavaScript Client? section.

3. How can I return individual address elements?

This can be useful if, for example, you need delivery point information or if you want premise details separately from the street information. In the JavaScript object that you pass in to the HPWAUTOC.FindAddress() function, you can include an optional detail object containing the names of the address elements that you want, and the HTML IDs of the fields that you want the values returned to. For example:

4. How can I return ‘extra data’ fields?

Depending on your dataset, you may be able to return extra data. In the JavaScript object that you pass in to the HPWAUTOC.FindAddress() function, you can include an optional extra object containing the names of the extra data elements that you want, and the HTML IDs of the fields that you want the values returned to. For example:

5. How can I call a function given a successful address lookup?

This can be useful if, for example, you need to enable a button or if you want to display the address on a map. In the JavaScript object that you pass in to the HPWAUTOC.FindAddress() function, you can include an optional success attribute containing the function that you want to call. For example:

6. How can I style the user interface?

The Select and Cancel buttons have a class of btn. You can define this class in your CSS or you can use jQuery to add your own class:

$(".btn").addClass("myButtonClass");

The Select button has a class of btn-primary and the Cancel button has a class of btn-default. If you want to style the buttons individually, you can define these classes in your CSS or you can use jQuery to add your own classes:

The status bar has a class hpw-info and its ID is hpw-status. The ID of the list of possible matches is hpw-possibles. Both the status bar and the list of possible matches are contained within div elements that have the class form-group.