Deprecated JQuery Library v1.8.1
Last updated
Last updated
The UI client uses jQuery and jQuery UI to create 'auto-complete' fields that invoke the Harmony API service methods.
We recommend +, a lightweight vanilla address auto-complete implementation is already included without the dependency on jQuery and jQuery UI.
Before you can use the Harmony API client, you must make sure you have:
An active Harmony API account
A Harmony API username and password for your domain
The versions of the JavaScript UI client can be downloaded using the following links:
For any earlier versions of client please contact us.
The UI client is dependent on the following JavaScript libraries:
3.5.1+
1.12.1+
1.8.1+
These dependencies should be included on the web page before the UI client. In the following example, the three JavaScript files have been downloaded to the 'scripts' folder in the root of the website.
Before making service requests, the client must be initialised. This is done by invoking the init
method on the global Harmony
object.
This method must be called before any other methods are invoked on the Harmony
object.
Once the Harmony API client has been initialised, lookup fields can be created using the global Harmony.UI
object.
The following example creates a international single-line address lookup on a text input with the id 'address' and 'country'.
As well as performing address lookups, the UI client can output additional fields from the lookups performed. This is done by adding fields using the global Harmony.UI
object.
The following example configures a single-line address lookup which then outputs the component parts of the resulting address to separate fields on the page.
The following example configures two single-line address lookups which then outputs the component parts of the resulting address to separate fields on the page.
When an address is selected from the lookup, the postcode, locality and street fields will automatically be populated with the corresponding values from the selected address.
Harmony.UI.LOADING
CSS class
The CSS class added to the input
element during the service method invocation.
Harmony.UI.OUTPUT
Field
The field used to output any errors that occur during the service method invocation.
Adds a new field specifying the field name (e.g. Harmony.POSTCODE
, Harmony.LOCALITY
, etc) and the input element.
Single-line address lookup version 2 for international address lookup on the supplied input
element.
Parses the value retrieved from the Harmony.ADDRESS
field and populates any other specified fields with the results.
Sets the element to use to display the Harmony UI output.
Adds a new field specifying the field name (e.g. Harmony.POSTCODE
, Harmony.LOCALITY
, etc) and the input element.
Type: StringThe name of the field to be added (e.g. Harmony.POSTCODE
).
Type: ObjectThe input
element to be assigned to the field (e.g. document.getElementById("postcodeField"))
.
Type: IntegerThe optional index if there are multiple sets of lookups on the same page (e.g. one for residential addresses and the other one for postal addresses). Currently only available for addressLookupV2
.
The following example assigns the Harmony.LOCALITY
field to the input element with the ID localityField
:
Type: ObjectThe input
address element to create the lookup for (e.g. document.getElementById("address")
).
Type: ObjectThe input
country element to create the lookup for (e.g. document.getElementById("country")
).
Type: StringThe Source of Truth to override the default Australia and New Zealand SOTs. It is optional.(e.g. Harmony.AUPAF
for Australia).
Type: StringOptional index to indicate which set of fields to populate if there are multiple lookups.
The following example creates a single-line address lookup (use AUPAF for Australian addresses) on the input element with ID singleLineAddress
and country
and customized opts
:
Parses the value entered in the Harmony.ADDRESS
field and populates any other specified fields with the parse results.
The following example uses jQuery to assign a click
event to a button with the ID parseButton
, which then parses the value in the address
input and outputs the generated address components into the postcode
, locality
and street
inputs:
Sets the element to use to display the Harmony UI output.
Type: ObjectThe element (can be any type) in which to post the Harmony UI output (e.g. document.getElementById("output")
).
The following example sets the output element to the element with the ID outputDiv
:
See the documentation for details on configuring the other lookup components.
The UI client library acts as a further abstraction wrapper for the . As with the Harmony API JavaScript client, the objects used by the library are JavaScript representations of those found in the .
It is recommended to use the current Javascript UI Client Address lookup methods. However are still available.
Creates international single-line address lookup with v2 APIs on the supplied input
and country
elements. It returns the response from service and the callback is available via onSelect
option.
For service, the response is available via ui.onRetrieveItem
and the callback is available via onRetrieve
option. For service, if getIntlGeocode
options is enabled, the response is available via ui.onIntlGeocodeItem
and the callback is available via onIntlGeocode
option.
Type: ObjectOptional parameter to be passed into the component (e.g. getIntlGeocode
true/false to enable international geocode call for the selected address, default is false. And callback functions e.g. onRetrieve
and onIntlGeocode
in below sample).