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.
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.

Basics

How do I install International JavaScript Client?

In the <head > of your web page, add this line…

  <link rel="stylesheet" href="https://cloud.hopewiser.com.au/jsclient/hpw-intl-jsclient.css" />

Before the </body> closing tag of your web page, add these lines…

  <script src="https://cloud.hopewiser.com.au/jsclient/jquery.min.js"></script>
  <script src="https://cloud.hopewiser.com.au/jsclient/bootstrap.min.js"></script>
  <script src="https://cloud.hopewiser.com.au/jsclient/json2.min.js"></script>
  <script src="https://cloud.hopewiser.com.au/jsclient/easyXDM.min.js"></script>
  <script src="https://cloud.hopewiser.com.au/jsclient/hpw-intl-jsclient.min.js"></script>

Replace ‘https://cloud.hopewiser.com.au/jsclient’ with the relative path of the folder if you chose to install these files on your own web server in place of using the Hopewiser hosted resources. Details of how to obtain local International JavaScript components required can by located in the Customisation section “How do I install International JavaScript Client service files locally?”.

If your web site is already using jQuery, Bootstrap, json2 or easyXDM, you may be able to omit the applicable lines or reference your existing installation as necessary.

Add a button with the following attributes to your web page:

  <button type="button" data-toggle="modal" data-target="#hpwModal" data-backdrop="static" onclick="btnFindAddress_onclick()">Find Address</button>

The HPWINTL_JavaScript and btnFindAddress_onclick functions need to be declared in the <head> of the web page. The first function contains a configurable HPWINTL object, whilst the second function handles the FindAddress’s onclick event. The onclick event is where the HPWINTL_JavaScript(HPWINTL.ADDRESS_SEARCH() function will be triggered:

  <script>
   HPWINTL_JavaScript(mode) {
    HPWINTL.FindAddress({ ...});  
  }

  function btnFindAddress_onclick() {
    HPWINTL_JavaScript(HPWINTL.ADDRESS_SEARCH);
  }
  </script>

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)…

  
    HPWINTL_JavaScript(HPWINTL.USE_OWN_CODES);
    HPWINTL_JavaScript(HPWINTL.USE_ALPHA2_CODES);
    HPWINTL_JavaScript(HPWINTL.USE_ALPHA3_CODES);

The HPWINTL.FindAddress() function takes a JavaScript object containing:

Your authorisation code
The HTML ID of your input field
The HTML ID of your country drop-down field
An optional CSV string containing a list of ISO 3166 alpha-3 codes to list your preferred countries (if using HPWINTL.USE_OWN_CODES)
An object containing the HTML IDs of your output fields
A system Mode parameter

If your web page has separate address fields
Specify their HTML IDs in the output object, e.g.

  
 function HPWINTL_JavaScript(mode) {
    HPWINTL.FindAddress({
      auth: "yourAuthCode",          // required
      input: "txtInput",             // required
      output: {
        line1:    "txtLine1",        // required
        line2:    "txtLine2",        // optional
        line3:    "txtLine3",        // optional
        line4:     "txtTown",        // optional
        line5:     "txtCounty",     // optional
        line6:     "txtPostcode"   // optional
      },
      Mode: mode
    });
  }

If your web page has a single multi-line address field
Specify its HTML ID against each address line you want to be returned, e.g.

  
function HPWINTL_JavaScript(mode) {
    HPWINTL.FindAddress({
      auth: "yourAuthCode",          // required
      input: "txtInput",             // required
      output: {
        line1:    "txtAddress",      // required
        line2:    "txtAddress",      // optional
        line3:    "txtAddress",      // optional
        line4:    "txtAddress",      // optional
        line5:    "txtAddress",      // optional
        line6:    "txtAddress",      // optional
        line7:    "txtAddress"       // optional
      },
      Mode: mode
    });
  }
  </script>

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.

How do I lookup an address?

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.

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 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

How do I install International JavaScript Client service files locally?

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.

How do I populate the list of countries?

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:

  <script>
   HPWINTL.FindAddress({
      ...
      aliasCounryCodes: {"UK":"GBR"},
      ...
    });
  </script>

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…

https://cloud.hopewiser.com.au/atlaslive/countries/json

or

https://cloud.hopewiser.com.au/atlaslive/countries/xml

Enter your Hopewiser Address Lookup username and password when prompted.

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 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:

  
function HPWINTL_JavaScript(mode) {
    HPWINTL.FindAddress({
      auth: "yourAuthCode",          // required
      input: "txtInput",             // required
      output: {
        line1:    "txtAddress",      // required
        line2:    "txtAddress",      // optional
        line3:    "txtAddress",      // optional
        line4:    "txtAddress",      // optional
        line5:    "txtAddress",      // optional
        line6:    "txtAddress",      // optional
        line7:    "txtAddress"       // optional
      },
      detail: {                      // optional
        Premise: "txtPremise",
        Organisation:   "txtOrganisation"
      },
      Mode: mode
    });
  }

How can I return ‘extra data’ fields?

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:

  
function HPWINTL_JavaScript(mode) {
    HPWINTL.FindAddress({
      auth: "yourAuthCode",            // required
      input: "txtInput",               // required
      output: {
        line1:    "txtLine1",          // required
        line2:    "txtLine2",          // optional
        line3:    "txtLine3",          // optional
        line4:    "txtLine4",          // optional
        line5:    "txtLine5",          // optional
        line6:    "txtLine6",          // optional
        line7:    "txtLine7"          // optional
      },
      Mode: mode,
      extra: {                         // optional
        Extra_LATTITUDE:  "txtLatitude",
        Extra_LONGITUDE: "txtLongitude"
      }
    });
  }

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 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:

  
 function HPWINTL_JavaScript(mode) {
    HPWINTL.FindAddress({
      auth: "yourAuthCode",          // required
      input: "txtInput",             // required
      output: {
        line1:    "txtAddress",      // required
        line2:    "txtAddress",      // optional
        line3:    "txtAddress",      // optional
        line4:    "txtAddress",      // optional
        line5:    "txtAddress",      // optional
        line6:    "txtAddress",      // optional
        line7:    "txtAddress"       // optional
      },
      Mode: mode,
      success: EnableButton,         // optional
    });
  }

  function EnableButton() {
    document.getElementById("btnNext").disabled = false;
  }

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:

  $(".btn-primary").addClass("myPrimaryButtonClass");
  $(".btn-default").addClass("myDefaultButtonClass");

You can also reference the Select button using its ID hpw-btnOK.

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.
Department	Department associated within an organisation
Organisation	Organisation name for a delivery point
Flat	Flat – formatted as if in a label
Floor	Floor – formatted as if in a label
Premise	Premise number – formatted as if in a label
POBox	PO Box – formatted as if in a label
HouseName1	Primary house name for a delivery point
HouseName2	Secondary house name for a delivery point
StreetName1	First street of an address
StreetName2	Second street of an address
DistrictName1	Minor district of an address
DistrictName2	Major district of an address
Town	Town
County	County
Postcode	Postcode
Country	Country
State	State or province