JavaScript Client

Overview

Provides address capture capability to a web page.
Does not require the installation of any files (as these can be referenced on the hosted service).
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

To use this functionality you will need to buy an Address Lookup click bundle from the Shop located in our Portal. Register for the Portal here.
A generated service Authorisation Code is required using the service Authorisation Code Generator and a token username and password you created in registering.
Download, unzip, and extract the 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).
Add 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

How do I install JavaScript Client?

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

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

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

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

Replace ‘https://cloud.hopewiser.com/jsclient2’ 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 JavaScript components required can be located in the Customisation section “How do I install AutoComplete JavaScript Client service files locally?”.

If your web site is already using jQuery, Bootstrap or json2, 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>

In the <head> of your web page, add a script to handle the button’s onclick event. In the button’s onclick handler, call the HPW.FindAddress() function:

  <script>
  function btnFindAddress_onclick() {
    HPW.FindAddress({...});
  }
  </script>

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

Your authorisation code
The dataset to look up against
The HTML ID of your input field
An object containing the HTML IDs of your output fields
Optionally, parameters to indicate if you want to include the County or any Organisation Name within the matched address, and whether you want the town in upper or lower case.

Optional Parameter	Description
IncludeCounty	Select when the county should be included within the formatted address label. Allowed values are *Always, Never* or *AsRequired* (the default). The value *AsRequired* will only include the county when appropriate, for example when it meets PTT guidelines or when it is required to disambiguate UK town names.
ReserveOrganisationLine	Select the position of the organisation within the formatted label. Allowed values are *AsRequired* (the default), *Always* or *Never. 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.
TownFormat	Select the required town format. Allowed values are *Uppercase* (the default) or *Lowercase*.

Optional Parameter

Description

IncludeCounty

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

The value AsRequired will only include the county when appropriate, for example when it meets PTT guidelines or when it is required to disambiguate UK town names.

ReserveOrganisationLine

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

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.

TownFormat

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

If your web page has separate address fields

Specify their HTML IDs in the output object, e.g.

  function btnFindAddress_onclick() {
    HPW.FindAddress({
      auth: "yourAuthCode",          // required
      dataset: "uk-rm-paf-mr", // required
      input: "txtInput",             // required
      output: {
        line1:    "txtLine1",        // required
        line2:    "txtLine2",        // required
        line3:    "txtLine3",        // optional
        line4:    "",                // optional
        town:     "txtTown",         // required
        county:   "txtCounty",       // optional
        postcode: "txtPostcode",     // required
        country:  "txtCountry"       // optional
      },
      IncludeCounty: "AsRequired",            // optional (default = "AsRequired")
      ReserveOrganisationLine: "AsRequired",  // optional (default = "AsRequired")
      TownFormat: "Uppercase"                 // optional (default = "Uppercase")
    });
  }

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 btnFindAddress_onclick() {
    HPW.FindAddress({
      auth: "yourAuthCode",          // required
      dataset: "uk-rm-paf-mr", // required
      input: "txtInput",             // required
      output: {
        line1:    "txtAddress",      // required
        line2:    "txtAddress",      // required
        line3:    "txtAddress",      // optional
        line4:    "",                // optional
        town:     "txtAddress",      // required
        county:   "txtAddress",      // optional
        postcode: "txtAddress",      // required
        country:  "txtAddress"       // optional
      },
      IncludeCounty: "AsRequired",            // optional (default = "AsRequired")
      ReserveOrganisationLine: "AsRequired",  // optional (default = "AsRequired")
      TownFormat: "Uppercase"                 // optional (default = "Uppercase")
    });
  }

If your web page has a mixture of multi-line and individual address fields

For each address line you want, specify the HTML ID of the field you want it returned to, e.g.

  function btnFindAddress_onclick() {
    HPW.FindAddress({
      auth: "yourAuthCode",          // required
      dataset: "uk-rm-paf-mr", // required
      input: "txtInput",             // required
      output: {
        line1:    "txtStreet",       // required
        line2:    "txtStreet",       // required
        line3:    "txtStreet",       // optional
        line4:    "",                // optional
        town:     "txtTown",         // required
        county:   "txtCounty",       // optional
        postcode: "txtPostcode",     // required
        country:  "txtCountry"       // optional
      },
      IncludeCounty: "AsRequired",            // optional (default = "AsRequired")
      ReserveOrganisationLine: "AsRequired",  // optional (default = "AsRequired")
      TownFormat: "Uppercase"                 // optional (default = "Uppercase")
    });
  }

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 or line4, 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.

How do I lookup an address?

Type a postcode into your input field then click the Find Address button. 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 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 autocomplete-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 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 JavaScript Client service files locally?

You do not have to download anything to use the 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 JavaScript Client files from here, uncompress the downloaded JavaScriptClient.zip file and then upload the extracted files to a suitable location on your web server.

How do I customise an address label?

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

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 HPW.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 btnFindAddress_onclick() {
    HPW.FindAddress({
      auth: "yourAuthCode",          // required
      dataset: "uk-rm-paf-mr", // required
      input: "txtInput",             // required
      output: {
        line1:    "txtLine1",        // required
        line2:    "txtLine2",        // required
        line3:    "txtLine3",        // optional
        line4:    "",                // optional
        town:     "txtTown",         // required
        county:   "txtCounty",       // optional
        postcode: "txtPostcode",     // required
        country:  "txtCountry"       // optional
      },
      detail: {                      // optional
        Premise: "txtPremise",
        UDPRN:   "txtUdprn"
               },
      IncludeCounty: "AsRequired",            // optional (default = "AsRequired")
      ReserveOrganisationLine: "AsRequired",  // optional (default = "NAsRequired")
      TownFormat: "Uppercase"                 // optional (default = "Uppercase")
    });
  }

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

  function btnFindAddress_onclick() {
    HPW.FindAddress({
      auth: "yourAuthCode",            // required
      dataset: "uk-nspd-paf", // required
      input: "txtInput",               // required
      output: {
        line1:    "txtLine1",          // required
        line2:    "txtLine2",          // required
        line3:    "txtLine3",          // optional
        line4:    "",                  // optional
        town:     "txtTown",           // required
        county:   "txtCounty",         // optional
        postcode: "txtPostcode",       // required
        country:  "txtCountry"         // optional
      },
      extra: {                         // optional
        Extra_Grid_Latitude:  "txtLatitude",
        Extra_Grid_Longitude: "txtLongitude"
      },
      IncludeCounty: "AsRequired",            // optional (default = "AsRequired")
      ReserveOrganisationLine: "AsRequired",  // optional (default = "AsRequired")
      TownFormat: "Uppercase"                 // optional (default = "Uppercase")
    });
  }

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

https://cloud.hopewiser.com/atlaslive/json/dataset?q=listoutputs

https://cloud.hopewiser.com/atlaslive/xml/dataset?q=listoutputs

Replace dataset with the dataset you want to use, e.g. https://cloud.hopewiser.com/atlaslive/json/uk-nspd-paf?q=listoutputs or https://cloud.hopewiser.com/atlaslive/xml/uk-nspd-paf?q=listoutputs. Enter your User name and Password when prompted. The available extra data elements are those Outputs that have a TableName of Extra Data.

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

  function btnFindAddress_onclick() {
    HPW.FindAddress({
      auth: "yourAuthCode",          // required
      dataset: "uk-rm-paf-mr", // required
      input: "txtInput",             // required
      output: {
        line1:    "txtLine1",        // required
        line2:    "txtLine2",        // required
        line3:    "txtLine3",        // optional
        line4:    "",                // optional
        town:     "txtTown",         // required
        county:   "txtCounty",       // optional
        postcode: "txtPostcode",     // required
        country:  "txtCountry"       // optional
      },
      success: EnableButton,         // optional
      IncludeCounty: "AsRequired",            // optional (default = "AsRequired")
      ReserveOrganisationLine: "AsRequired",  // optional (default = "AsRequired")
      TownFormat: "Uppercase"                 // optional (default = "Uppercase")
    });
  }

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

Data Item	Description
Label1-Label9	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
DPID	The delivery point suffix
UDPRN	(UK Only) Eight digit numeric code to uniquely identify a UK delivery point
UAID	Unique address identifier
DedupeKey	Key for deduplication purposes
ExtendedDedupeKey	Key for deduplication purposes