# Deprecated JQuery Library v1.8.1

The UI client uses jQuery and jQuery UI to create 'auto-complete' fields that invoke the Harmony API service methods.

{% hint style="warning" %}
**We recommend** [Harmony API JavaScript client version 2.0.0](/loqate-harmony-api/integrations/client-libraries/javascript-library-v2.1.0.md)+, a lightweight vanilla address auto-complete implementation is already included without the dependency on jQuery and jQuery UI. 
{% endhint %}

### Pre-requisites

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

### Getting the client

The versions of the JavaScript UI client can be downloaded using the following links:

* [harmony-ui-1.8.1.min.js](http://common.mastersoftgroup.com/scripts/harmony-ui-1.8.1.min.js)
* For any earlier versions of client please contact us.

### Configuring the client dependencies

The UI client is dependent on the following JavaScript libraries:

* [jQuery](http://jquery.com/) 3.5.1+
* [jQuery UI](http://jqueryui.com/) 1.12.1+
* [Harmony RightAddress JavaScript Client](https://developer.mastersoftgroup.com/harmony/client/js) 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.

```
 <!-- Include the JavaScript dependencies -->
    <script src="https://ajax.googleapis.com/ajax/libs/jquery/3.5.1/jquery.min.js" type="text/javascript"></script>
    <script src="https://ajax.googleapis.com/ajax/libs/jqueryui/1.12.1/jquery-ui.min.js" type="text/javascript"></script>    
    <script src="/scripts/harmony-2.0.1.min.js" type="text/javascript"></script>

    <!-- Include the Harmony RightAddress JavaScript UI client -->
    <script src="/scripts/harmony-ui-1.8.1.min.js" type="text/javascript"></script>
```

### Initialising the client

Before making service requests, the client must be initialised. This is done by invoking the `init` method on the global `Harmony` object.

```
Harmony.init({String} username, {String} password, {String} locale);
```

This method must be called before any other methods are invoked on the `Harmony` object.

```
    <script type="text/javascript">

        Harmony.init("webUser", "password", Harmony.AUSTRALIA);

    </script>
```

### Creating a single-line international address lookup with v2 APIs

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

```
<script type="text/javascript">

    Harmony.init("webUser", "password", Harmony.AUSTRALIA);
    //pass in custom feature options if applicable. 
    Harmony.useFeatureOptions({"exposeAttributes":0, "groupAddresses":1});
    //pass in Optional parameter for jquery autocomplete.
    var opt = {
        // min 3 chars to trigger the lookup
        minLength:3, 
        // enable Harmony.International.getGeocode for non-AU/NZ countries when address selected.
        getIntlGeocode:true,
        //Override onSelect function if applicable. It is Optional
        onSelect: function(event, ui) {
           console.log('address selected: ' + JSON.stringify(ui.item));
        },
        //Override onIntlGeocode function if applicable. It is Optional
        //e.g. get ui.onIntlGeocodeItem object for address payload after onIntlGeocode call.
        onIntlGeocode: function(event, ui) {
           console.log('geocode address selected: ' + JSON.stringify(ui.onIntlGeocodeItem));
        },
        //Override onRetrieve function if applicable. It is Optional
        //e.g. get ui.onRetrieveItem object for address payload after onRetrieve call.
        onRetrieve: function(event, ui) {
           console.log('onRetrieve address selected: ' + JSON.stringify(ui.onRetrieveItem));
        }
      };

      //specify the sot for AU/NZ address search if applicable, otherwise just pass in null.
      var sot = "GNAF";

      Harmony.UI.addressLookupV2($("#address"), $("#country"), sot, opt);

    </script>
```

### Specifying output fields

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.

```
    <script type="text/javascript">

        Harmony.init("webUser", "password", Harmony.AUSTRALIA);

        // Configure the address lookup.
        Harmony.UI.addressLookup($("#address"), Harmony.AUPAF);

        // Configure the output fields.
        Harmony.UI.addField(Harmony.POSTCODE, $("#postcode"));
        Harmony.UI.addField(Harmony.LOCALITY, $("#locality"));
        Harmony.UI.addField(Harmony.STREET, $("#street"));
        //add attributes field e.g. latitude and longitude
        Harmony.UI.addField("attributes.Latitude", $("#Latitude"));
    	Harmony.UI.addField("attributes.Longitude", $("#Longitude"));

    </script>
```

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.

```
    <script type="text/javascript">

        Harmony.init("webUser", "password", Harmony.AUSTRALIA);

        // Configure the address lookup.
        Harmony.UI.addressLookup($("#address"), Harmony.AUPAF);
        Harmony.UI.addressLookup($("#address1"), Harmony.AUPAF, undefined, null, 1);

        // Configure the output fields.
        Harmony.UI.addField(Harmony.POSTCODE, $("#postcode"));
        Harmony.UI.addField(Harmony.LOCALITY, $("#locality"));
        Harmony.UI.addField(Harmony.STREET, $("#street"));

        Harmony.UI.addField(Harmony.POSTCODE, $("#postcode1"), 1);
        Harmony.UI.addField(Harmony.LOCALITY, $("#locality1"), 1);
        Harmony.UI.addField(Harmony.STREET, $("#street1"), 1);

    </script>
```

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.

### Additional information

See the [Harmony RightAddress JavaScript UI client API](https://developer.mastersoftgroup.com/harmony/client/jsui/api.html) documentation for details on configuring the other lookup components.

## Extending Library for JQuery

The UI client library acts as a further abstraction wrapper for the [Harmony RightAddress JavaScript client](https://developer.mastersoftgroup.com/harmony/client/js). As with the Harmony API JavaScript client, the objects used by the library are JavaScript representations of those found in the [Harmony RightAddress service API](https://developer.mastersoftgroup.com/harmony/api/).

**It is recommended to use the current Javascript UI Client Address lookup methods.** However [the previous version of JavaScript UI Client Address lookup methods](https://developer.mastersoftgroup.com/harmony/client/jsui/v1/api.html) are still available.

### Constants

| Name               | Type      | Description                                                                          |
| ------------------ | --------- | ------------------------------------------------------------------------------------ |
| 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. |

### Methods

| Name                                                                                                               | Description                                                                                                            |
| ------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------- |
| [Harmony.UI.addField](https://developer.mastersoftgroup.com/harmony/client/jsui/api.html#addField)                 | Adds a new field specifying the field name (e.g. `Harmony.POSTCODE`, `Harmony.LOCALITY`, etc) and the input element.   |
| [Harmony.UI.addressLookupV2](https://developer.mastersoftgroup.com/harmony/client/jsui/api.html#addressLookupV2)   | Single-line address lookup version 2 for international address lookup on the supplied `input` element.                 |
| [Harmony.UI.parseAddress](https://developer.mastersoftgroup.com/harmony/client/jsui/api.html#parseAddress)         | Parses the value retrieved from the `Harmony.ADDRESS` field and populates any other specified fields with the results. |
| [Harmony.UI.setOutputElement](https://developer.mastersoftgroup.com/harmony/client/jsui/api.html#setOutputElement) | Sets the element to use to display the Harmony UI output.                                                              |

### Harmony.UI.addField(field, element, index)

Adds a new field specifying the field name (e.g. `Harmony.POSTCODE`, `Harmony.LOCALITY`, etc) and the input element.

#### field

Type: StringThe name of the field to be added (e.g. `Harmony.POSTCODE`).

#### element

Type: ObjectThe `input` element to be assigned to the field (e.g. `document.getElementById("postcodeField"))`.

#### index

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

```
    // Perform the assignment using standard JavaScript.
    Harmony.UI.addField(Harmony.LOCALITY, document.getElementById("localityField"));
  
    // Perform the assignment using a jQuery selector.
    Harmony.UI.addField(Harmony.LOCALITY, $("#localityField"));
    
    /* Perform the assignment using a jQuery selector with index 
       for the second set address lookup. */
    Harmony.UI.addField(Harmony.LOCALITY, $("#localityField"), 1); 
```

### Harmony.UI.addressLookupV2(element, countryElement, sourceOfTruth, opts, index)

Creates international single-line address lookup with v2 APIs on the supplied `input` and `country` elements. It returns the response from [find](https://developer.mastersoftgroup.com/harmony/api/method/address.html#hraFind) service and the callback is available via `onSelect` option.

For [retrieve](https://developer.mastersoftgroup.com/harmony/api/method/address.html#hraRetrieve) service, the response is available via `ui.onRetrieveItem` and the callback is available via `onRetrieve` option. For [internationalGeocode](https://developer.mastersoftgroup.com/harmony/api/method/address.html#internationalGeocode) service, if `getIntlGeocode` options is enabled, the response is available via `ui.onIntlGeocodeItem` and the callback is available via `onIntlGeocode` option.

#### element

Type: ObjectThe `input` address element to create the lookup for (e.g. `document.getElementById("address")`).

#### countryElement

Type: ObjectThe `input` country element to create the lookup for (e.g. `document.getElementById("country")`).

#### sourceOfTruth

Type: StringThe Source of Truth to override the default Australia and New Zealand SOTs. It is optional.(e.g. `Harmony.AUPAF` for Australia).

#### opts

Type: ObjectOptional parameter to be passed into the [jQuery UI Autocomplete](http://jqueryui.com/autocomplete/) 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).

#### index

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

```
    var opt = {
        // min 3 chars to trigger the lookup
        minLength:3, 
        // enable Harmony.International.getGeocode for non-AU/NZ countries when address selected.
        getIntlGeocode:true,
        //Override onSelect function if applicable. It is Optional
        onSelect: function(event, ui) {
            console.log('address selected: ' + JSON.stringify(ui.item));
        },
        //Override onIntlGeocode function if applicable. It is Optional
        //e.g. get ui.onIntlGeocodeItem object for address payload after onIntlGeocode call.
        onIntlGeocode: function(event, ui) {
            console.log('geocode address selected: ' + JSON.stringify(ui.onIntlGeocodeItem));
        },
        //Override onRetrieve function if applicable. It is Optional
        //e.g. get ui.onRetrieveItem object for address payload after onRetrieve call.
        onRetrieve: function(event, ui) {
            console.log('onRetrieve address selected: ' + JSON.stringify(ui.onRetrieveItem));
        }
    };
    
    // Perform the assignment using a jQuery selector.
    Harmony.UI.addressLookupV2($("#singleLineAddress"), $("#country"), Harmony.AUPAF, opt);
```

### Harmony.UI.parseAddress()

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:

```
    // Add the address field using jQuery selectors.
    Harmony.addField($("#address"), Harmony.ADDRESS);
    
    // Add the output fields using jQuery selectors.
    Harmony.addField($("#postcode"), Harmony.POSTCODE);
    Harmony.addField($("#locality"), Harmony.LOCALITY);
    Harmony.addField($("#street"), Harmony.STREET);
    
    // Use jQuery to generate the click event for the button.
    $("#parseButton").click(function(event) {
        // Perform the parse.
        Harmony.UI.parseAddress();
    });
     
```

### Harmony.UI.setOutputElement(element)

Sets the element to use to display the Harmony UI output.

#### element

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

```
    // Perform the assignment using standard JavaScript.
    Harmony.UI.setOutputElement(document.getElementById("outputDiv"));
  
    // Perform the assignment using a jQuery selector.
    Harmony.UI.setOutputElement($("#outputDiv"));
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.mastersoftgroup.com/loqate-harmony-api/integrations/deprecated-integrations/deprecated-jquery-library-v1.8.1.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.