Widget advanced usage

Event Listeners

You can subscribe to event notifications from the widget using the on() listener function. This method simply takes the event name, and a callback function.

    
    (function(){
      var widget,
        initAF = function() {
          widget = new AddressFinder.Widget(
            document.getElementById('address_field'),
            'YOUR_KEY',
            'NZ'
          );

          widget.on('result:select', function(value, item) {
            alert('You’ve selected: '+ value);
          });
        };

      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);
  });

    })();
    
  

View this on jsFiddle

Take a look at our Widget Documentation to see what kind of events you can set listeners for.

Custom Styling

Typically our JavaScript library embeds a stylesheet with some simple styling. However if you wish to apply your own css, that can be done with a few simple tweaks.

First when initialising the widget, you’ll need to pass an option specifying not to embed it’s own stylesheet:

    
    (function(){
      var widget,
        initAF = function() {
          widget = new AddressFinder.Widget(
            document.getElementById('address_field'),
            'YOUR_KEY',
            'NZ',
            {manual_style:true}
          );
        };

      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);
  });

    })();
    
  

Then include some CSS in a stylesheet like so:

    
    ul.af_list {
      list-style: none;
      padding: 0;
      margin: 0;
      border: solid 1px #666;
      background: white;
    }
    li.af_item {
      cursor: pointer;
    }
    li.af_hover {
      background-color: steelblue;
      color: white;
    }
      li.af_footer {
      font-size: 0.8em;
      color: #666;
      text-align: right;
    }
    
  

View this on jsFiddle

Adding third-party search services.

It’s possible to include additional search results in the autocomplete results, by providing a function to carry out the searching. The search function will be passed two arguments, the query and a callback function. The callback function requires you to pass back the original query and an array of formatted results.

    
    (function(){
      var widget,
        store_service,
        stores = ['Queen Street, Auckland', 'Cuba Street, Wellington', 'Bridge Street, Nelson', 'The Octagon, Dunedin'],
        initAF = function() {
          widget = new AddressFinder.Widget(
            document.getElementById('address_field'),
            'YOUR_KEY',
            'NZ'
          );

          store_service = widget.addService('store-search', function(query, response_fn){
            var regex = new RegExp('^' + query, 'gi');
            var matches = stores.filter(function(store){
              return regex.test(store);
            });
            var results = matches.map(function(match){
              return {value:match}
            });
            response_fn(query, results);
          });

          store_service.setOption('renderer', function(value){
            return '
' + value + '
';
          });
        };

      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);
  });

    })();
    
  

View this on jsFiddle

Support for Asynchronous Module Definition (AMD)

By default the widget.js package includes dependencies which can cause problems with AMD libraries such as Require.js, especially when the AddressFinder is loaded after the AMD library. As the core library needs to be loaded from our remote server, we’re providing a special core.js library, which allows you to include the dependencies (reqwest and neat-complete) in your own project.

The best point reference is our example project on github.

The core.js is compatible with all modern browsers. Internet Explorer is supported for versions 10+