AddressFinder - Guides - Adding AddressFinder to a bespoke website

Installation Instructions

This page shows how to add the AddressFinder auto-complete plugin to a custom address form.

You can watch the 4 minute video, or refer to the notes and screenshots below.

Step by step

We will attach the AddressFinder widget to the first street field in this form.

The expected behaviour is:
1. A user starts typing this address into the street field
2. The autocomplete service displays matching addresses
3. The desired address is selected
4. The individual address elements are then automatically populated into the street, suburb, city and postcode fields.

Listed below is the HTML source code of this form. We are going to attach the AddressFinder Javascript widget to the customer_street_details_1 element on line 9.

[…]
<div class="field">
  <label for="customer_name">Name</label><br>
  <input type="text" name="customer[name]" id="customer_name">
</div>
<div class="field">
  <label for="customer_street_details_1">Street</label><br>
  <!-- We'll be attaching the AddressFinder widget to the field below... -->
  <input type="text" name="customer[street_details_1]" id="customer_street_details_1"><br>
  <input type="text" name="customer[street_details_2]" id="customer_street_details_2">
</div>
<div class="field">
  <label for="customer_suburb">Suburb</label><br>
  <input type="text" name="customer[suburb]" id="customer_suburb">
</div>
<div class="field">
  <label for="customer_city">City</label><br>
  <input type="text" name="customer[city]" id="customer_city">
</div>
<div class="field">
  <label for="customer_postcode">Postcode</label><br>
  <input type="number" name="customer[postcode]" id="customer_postcode">
</div>
<div class="field">
  <label for="customer_phone_number">Phone number</label><br>
  <input type="text" name="customer[phone_number]" id="customer_phone_number">
</div>
<div class="actions">
  <input type="submit" name="commit" value="Create Customer">
</div>
[…]
 

The first step is to confirm you're got a license key. If you don't have one, just complete the Get a licence key form and then come back here and resume.
Visit the code generator page, and click the Advanced code generator tab.
The code generator requires your licence key. Paste that into the first field.

Next, drop in the ID value of the first street address field. In our example (above) this is customer_street_details_1.
As this form has multiple fields for each address element, we will select the multiple address inputs option.
We will leave the rest of the options unchanged, but do have a read through so that you understand what sorts of changes you can make.
Next, copy the generated Javascript and paste it into your page. You should paste it close to the bottom, just above the closing </body> tag.

Here is the code that was generated:

<script>
(function(){
var widget, initAF = function(){
  widget = new AddressFinder.Widget(
    document.getElementById('customer_street_details_1'),
    'ADDRESSFINDER_NZ_DEMO_KEY',
    'NZ',
    {
    }
  );
  widget.on('result:select', function(fullAddress, metaData) {
    var selected = new AddressFinder.NZSelectedAddress(fullAddress, metaData);
    document.getElementById('customer_street_details_1').value = selected.address_line_1()
    document.getElementById('address_line_2').value = selected.address_line_2()

    // If you only have one address line
    // document.getElementById('address_line').value = selected.address_line_1_and_2()

    document.getElementById('suburb').value = selected.suburb()
    document.getElementById('city').value = selected.city()
    document.getElementById('postcode').value = selected.postcode()
  });
};

function downloadAF(f){
  var script = document.createElement('script');
  script.src = 'https://api.addressfinder.io/assets/v3/widget.js';
  script.async = true;
  script.onload = f;
  document.body.appendChild(script);
};

document.addEventListener('DOMContentLoaded', function () {
  downloadAF(initAF);
});
})();
</script>
 

Take a look at the function on line 11. This is the result:select handler, and it will be called when a user clicks on an address.

We need to adjust the ID field values to match our form. If you scroll up the page a little, you'll see that our fields are named customer_street_details_1, customer_street_details_2, customer_suburb, customer_city and customer_postcode.

Here's the updated source code, now with the field IDs updated:

[…]
<div class="field">
  <label for="customer_name">Name</label><br>
  <input type="text" name="customer[name]" id="customer_name">
</div>
<div class="field">
  <label for="customer_street_details_1">Street</label><br>
  <input type="text" name="customer[street_details_1]" id="customer_street_details_1"><br>
  <input type="text" name="customer[street_details_2]" id="customer_street_details_2">
</div>
<div class="field">
  <label for="customer_suburb">Suburb</label><br>
  <input type="text" name="customer[suburb]" id="customer_suburb">
</div>
<div class="field">
  <label for="customer_city">City</label><br>
  <input type="text" name="customer[city]" id="customer_city">
</div>
<div class="field">
  <label for="customer_postcode">Postcode</label><br>
  <input type="number" name="customer[postcode]" id="customer_postcode">
</div>
<div class="field">
  <label for="customer_phone_number">Phone number</label><br>
  <input type="text" name="customer[phone_number]" id="customer_phone_number">
</div>
<div class="actions">
  <input type="submit" name="commit" value="Create Customer">
</div>
[…]
<script>
(function(){
var widget, initAF = function(){
  widget = new AddressFinder.Widget(
    document.getElementById('customer_street_details_1'),
    'ADDRESSFINDER_AU_DEMO_KEY',
    'NZ'
  );
  widget.on('result:select', function(fullAddress, metaData) {
    var selected = new AddressFinder.NZSelectedAddress(fullAddress, metaData);
    document.getElementById('customer_street_details_1').value = selected.address_line_1();
    document.getElementById('customer_street_details_2').value = selected.address_line_2();

    // If you only have one address line
    // document.getElementById('address_line_1').value = selected.address_line_1_and_2();

    document.getElementById('customer_suburb').value = selected.suburb();
    document.getElementById('customer_city').value = selected.city();
    document.getElementById('customer_postcode').value = selected.postcode();
  });
};

function downloadAF(f){
  var script = document.createElement('script');
  script.src = 'https://api.addressfinder.io/assets/v3/widget.js';
  script.async = true;
  script.onload = f;
  document.body.appendChild(script);
};

document.addEventListener('DOMContentLoaded', function () {
  downloadAF(initAF);
});
})();
</script>
[…]
 

That's all the changes you need to make. Let's reload our page and see it working:

You can see the autocomplete working nicely, with the matching addresses being displayed.
If we then click on the address, our result:select handler should go and fill in the individual form fiels below:
SUCCESS! It works! You can see all of the fields now have the right address values populated.

Get a free licence key now

Existing user? Get your Licence key from the AddressFinder Portal.

Use the Widget code generator

Fill in the widget code generator, and then add the code to your form.

Installation Instructions

Step by step

Get a free licence key now

Use the Widget code generator

Next steps