International JavaScript Client

Overview

Provides International address capture capability to a web page.

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 have been replaced with a local reference of your choosing.

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.

Quick Start

An Address Lookup service account with a ‘live’ International click bundle is required.

A generated service Authorisation Code is required using the service Authorisation Code Generator (giving a Base64 encoded value based upon the token username and password you created during registering with Address Lookup).

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

Add the Authorisation Code from above to the HPWINTL.FindAddress()auth section).

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

The HPWINTL_JavaScript and btnFindAddress_onclick functions need to be declared. The first function contains a configurable HPWINTL object and the latter function is a handle to the FindAddress’s onclick event. The onclick event is where the HPWINTL_JavaScript(HPWINTL.ADDRESS_SEARCH() function will be triggered:

In the <head> of your web page, add a script to handle the functions. The first function contains a configurable HPWINTL object and the latter function is a handle to the FindAddress’s onclick event. The onclick event is where the HPWINTL_JavaScript(HPWINTL.ADDRESS_SEARCH) function will be triggered:

One of the following three methods must be called to specify the country code values that are defined in the country drop-down box (please refer to the Customisations section called How do I populate the list of countries for details and distinctions of each)…

Replace yourAuthCode with your authorisation code and the example HTML IDs with your actual HTML IDs.) The address label is not formatted. For a matched address, this will contain one or more address lines which will be written to line1-7 in that order for each of the output field mappings that are provided. The input field does not have to be a separate field; it can be one of the output fields.

Enter a string into the input box referenced by the input field. This will be used as an initial search criteria associated with the Find Address button click event. Select an address from the list of possible matches then click the Select button. Repeat if necessary until you have the address you want.

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

You can set the Debug flag found in the international-javascript-client sample page to true. This will display a message box to the user if there are any missing or invalid fields.

IE Compatibility Modes

The International JavaScript Client uses Bootstrap, which is not supported in the old Internet Explorer compatibility modes. To be sure you’re using the latest rendering mode for IE, consider including the appropriate <meta> tag in your page:

<meta http-equiv="X-UA-Compatible" content="IE=edge">

Confirm the document mode by opening the debugging tools: press F12 and check the Document Mode.

Customisations

You do not have to download anything to use the International 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 International JavaScript Client files from here.

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

The HPWINTL_JavaScript method must be called with one of the HPWINTL.USE…CODES parameter to setup the country list box. This function should be added near the end of the Javascript block and the action is normally applied when the page load is complete.

Add “HPWINTL_JavaScript(HPWINTL.USE_OWN_CODES);” o your Javascript block if you do not wish the International JavaScript client to auto-populate the country list box. Please ensure that your country list definition contains valid alpha-2 or alpha-3 codes. If your country list definition contains un-recognised alpha-2 or alpha-3 codes but still want to use them, you can link this code to a valid alpha-3 code with the aliasCountryCodes setting. The aliasCountryCodes defines a key-value pair object which contains a list of alias country codes and alpha-3 codes. For example, UK is not a valid alpha-2 code, but it can be defined as an alias to “United Kingdom” by creating a key-value pair to link the UK code to the GBR alpha-3 code. The HPWINTL.FindAddress will be setup as follows:

The topCountries setting is not applicable when the HPWINTL_JavaScript method is called with the HPWINTL.USE_OWN_CODES parameter.

By adding “HPWINTL_JavaScript(HPWINTL.USE_ALPHA2_CODES);” or “HPWINTL_JavaScript(HPWINTL.USE_ALPHA3_CODES);” to your Javascript block, the International JavaScript Client will auto-populate the country list box with the corresponding alpha2 or alpha3 country codes. The country list drop-down boxed referenced by the countryListBox will be populated and updated accordingly. The topCountries setting will be applied when the HPWINTL_JavaScript method is called with the HPWINTL.USE_ALPHA2_CODES or HPWINTL.USE_ALPHA3_CODES parameter. Country or countries that are specified in the topCountries setting will be listed at the top of the populated country list when presented to the user.

To view an exhaustive listing of the Alpha2 and Alpha3 codes referenced in the above and the data coverage level of that country (SubPremise, HouseNumber, HouseNumberRange, Street, City, or None), use one of the below URLs in a browser…

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 HPWINTL object that you pass in to the HPWINTL.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:

In the International JavaScript object that you pass in to the HPWINTL.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. This is currently limited to Latitude and Longitude. For example:

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 International JavaScript object that you pass in to the HPWINTL.FindAddress() function, you can include an optional success attribute containing the function that you want to call. For example:

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.

Common Output Fields

The following table lists the output fields that can be retrieved from all Master Address Files (MAFs) including Hopewiser’s International offering.

Data Item

Description

Label1-Label7

Formatted address label comprising up to the specified number of lines.