0845 600 9231 Hopewiser on Facebook Hopewiser on Twitter

Hopewiser Web Services

JavaScript Client

Contents

Introduction

The JavaScript Client is a code snippet that you can add to a web page to give it address capture capability.

To use the JavaScript Client you will require an AddressServer in the Cloud account. If you don't already have an account, then please register on-line or alternatively contact us.

What does the JavaScript Client do?

The JavaScript Client provides address capture capability to a web page. It operates very much like the Find Address button on our Sign Up page. (You need to be logged off to access the Sign Up page.)

How do I install the JavaScript Client?

Download

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 the AddressServer Downloads page. (You will need to log on to access the downloads page).
  AddressServer Downloads

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

Setup

In the <head> of your web page, add this line (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):

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

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

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

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>

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, and
  • 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.

Your authorisation code is the User Name of a service user, followed by a colon, followed by the Password of the service user, all Base64 encoded. You can use our online Authorisation Code Generator to get your authorisation code. For your security, it is important that you use a User Name with only service user permissions so that nobody can decode your credentials and use them to log on to Your Account. The dataset reference you specify must be one that is available to the service user that you used to generate the authorisation code.

Optional Parameter Description
IncludeCounty

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

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.
NOTE: It is strongly recommend to include this parameter as its default is subject to change from Always to AsRequired.
ReserveOrganisationLine

Select the position of the organisation within the formatted label. Allowed values are AsRequired, Always or Never (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.
NOTE: It is strongly recommend to include this parameter as its default is subject to change from Never to AsRequired.
organisation

Deprecated; replaced by ReserveOrganisationLine

Select the position of the organisation within the formatted label. Allowed values are true or false (the default).

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

The value false 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-external", // 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 = "Always")
      ReserveOrganisationLine: "AsRequired",  // optional (default = "Never")
      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-external", // 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 = "Always")
      ReserveOrganisationLine: "AsRequired",  // optional (default = "Never")
      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-external", // 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 = "Always")
      ReserveOrganisationLine: "AsRequired",  // optional (default = "Never")
      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 perform an address search?

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 use the debug version of Hopewiser JavaScript Client to check your integration for errors. This version will display a message box to the user if there are any missing or invalid fields.

In the lines you added before the </body> closing tag of your web page, replace this line:

  <script src="https://cloud.hopewiser.com/jsclient/hpw-jsclient.min.js"></script>

with this one:

  <script src="https://cloud.hopewiser.com/jsclient/hpw-jsclient.debug.js"></script>

(Replace 'https://cloud.hopewiser.com/jsclient' with the relative path of your installation folder, if you chose to install these files on your own web server.) When you have resolved the problem, be sure to switch back to the non-debug version of Hopewiser JavaScript Client.

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

Advanced Topics

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-external", // 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 = "Always")
      ReserveOrganisationLine: "AsRequired",  // optional (default = "Never")
      TownFormat: "Uppercase"                 // optional (default = "Uppercase")
    });
  }

The available detail elements are:

Field Description
Department Department associated with the organisation.
Organisation Organisation name for the delivery point.
Flat Formatted flat.
Floor Formatted floor.
HouseName1 Primary house name for the delivery point.
HouseName2 Secondary house name for the delivery point.
Premise Formatted premise.
StreetName1 First street of the address.
StreetName2 Second street of the address.
DistrictName1 Minor district of the address.
DistrictName2 Major district of the address.
DPID UK: 3-character Delivery Point Suffix.
Australia: 8-character Delivery Point ID.
UDPRN UK: 8-digit Unique Delivery Point Reference Number.
DedupeKey Hopewiser field used for deduplication purposes.

How can I return extra data?

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-external", // 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 = "Always")
      ReserveOrganisationLine: "AsRequired",  // optional (default = "Never")
      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

or

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-external?q=listoutputs or https://cloud.hopewiser.com/atlaslive/xml/uk-nspd-paf-external?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 on 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-external", // 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 = "Always")
      ReserveOrganisationLine: "AsRequired",  // optional (default = "Never")
      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.