Harmony RightAddress JavaScript client

The Harmony RightAddress JavaScript client is a JavaScript library that can be included on a web page, allowing website users to connect directly to the Harmony RightAddress services without any server-side processing requirements.

As of version 1.3.0, the Harmony RightAddress JavaScript client can be configured to use either Cross Origin Resource Sharing (CORS) or JSON with Padding (JSONP):

  • If your clients have older IE browsers (i.e. 7, 8 or 9), the JSONP configuration offers the best backwards compatibility.
  • If your clients will all be using modern browsers (or IE10+), CORS is a more correct solution.

Code snippet

Copy and paste the following code snippet into your web page.

Pre-requisites

Before you can use the Harmony RightAddress client, you must make sure you have:

  • An active Harmony RightAddress account
  • A Harmony RightAddress username and password for your domain
  • A proficiency in JavaScript

Getting the client

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

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>

Setting the environment and protocol

During initialisation, the client environment is set to Production and the protocol is set to CORS. To use the Production environment or the JSONP protocol, the useEnv and useProtocol methods can be used.


    <script type="text/javascript">

        // Use the Production environment
        Harmony.useEnv(Harmony.ENV_PRODUCTION);

        // Use the JSONP protocol
        Harmony.useProtocol(Harmony.JSONP);

    </script>

Invoking service requests

Once the Harmony RightAddress client has been initialised, any methods available to the supplied user can be invoked. These methods are invoked using the global Harmony object.

The following example invokes the address method with the single-line address '1 abc street' and the 'AUPAF' Source of Truth. The callback method then output the addresses in a textarea with the id 'output':


    <script type="text/javascript">

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

        Harmony.address({ fullAddress:"1 abc street" }, Harmony.AUPAF,
                function(response) {
                    var outputText = "";

                    // Check if the request was successful.
                    if (response == Harmony.SUCCESS) {

                        // Fill the output text with the single-line address results.
                        for (var i = 0; i < response.payload.length; i++) {
                            outputText += response.payload[i].fullAddress + "\n";
                        }

                    } else {

                        // Fill the output text with the error message(s).
                        for (var i = 0; i < response.messages.length; i++) {
                            outputText += response.messages[i] + "\n";
                        }

                    }

                    // Put the output text in the textarea (with id 'output')
                    document.getElementById("output").value = outputText;
                }
        );

    </script>

See the Harmony RightAddress JavaScript client API documentation for details on invoking the other Harmony RightAddress service methods.