what3words autosuggest jQuery plugin
Easily capture 3 word addresses on your website with the 3 word address validation JQuery plugin by what3words.
what3words is a global addressing system. It has divided the world into a grid of 3m x 3m squares and assigned each one a unique 3 word address. what3words is more accurate than traditional street addressing, and even allows location information to be captured for places without addresses, such as parks or beaches. The 3 word address validation plugin created by what3words allows you to easily integrate 3 word addresses into your site by applying what3words AutoSuggest on an input field, including default styling.
AutoSuggest jQuery Plugin
The plugin provides a simple way to get started using AutoSuggest on your website. It has been designed to be used when you want a user to input a 3 word address in a form field. Based on a full or partial address, it returns a list of the most relevant 3 word address candidates. Corrections are provided for input errors.
Visualising the results
The autosuggest results are displayed in the same way as the search box on map.what3words.com and in the what3words mobile apps.
The resulting candidate list contains the 3 word address, the nearest place to that address.
While autosuggest uses the clipping parameter to determine the geographical boundary of results, the plugin makes use of a country_filter This allows you to more easily limit results to a specific country. Please note that using the country_filter may impact the number of results returned to the user.
Getting Started
Prerequisites
- jQuery 1.7.2 and above because of .on event handler
Dependencies
The plugin uses these dependencies.
- jquery-Typeahead plugin 2.10.4 https://www.npmjs.com/package/jquery-typeahead
- jquery-validation plugin 1.17.0 https://www.npmjs.com/package/jquery-validation Distribution contains a bundle version including these libraries:
Using the plugin
Make sure to include jQuery in your page, for example:
<script src="https://code.jquery.com/jquery-2.2.4.min.js"></script>Include the what3words plugin files from the ./dist folder into your HTML source:
Include JQuery plugin bundled with jquery-typeahead and jquery-validation plugins
<script src="https://github.com/what3words/jquery-plugin-w3w-autosuggest/raw/master/[path-to-plugin]/js/jquery.w3w-autosuggest-plugin.bundle.min.js"></script>or separately
<script src="https://github.com/what3words/jquery-plugin-w3w-autosuggest/raw/master/path/to/jquery.typeahead"></script>
<script src="https://github.com/what3words/jquery-plugin-w3w-autosuggest/raw/master/path/to/jquery.validation"></script>
<script src="https://github.com/what3words/jquery-plugin-w3w-autosuggest/raw/master/[path-to-plugin]/js/jquery.w3w-autosuggest-plugin.min.js"></script>Add the input element which will become the what3words autosuggest field. This must be within a form element for example:
<div>
<div>
<form>
<input id="twa-input" class="w3w-address-field" type="text" >
</form>
</div>
</div>Add the CSS to the <header>:
<link rel="stylesheet" href="https://github.com/what3words/jquery-plugin-w3w-autosuggest/blob/master/[path-to-plugin]/css/jquery.w3w-autosuggest-plugin.bundle.min.css">or separately
<link rel="stylesheet" href="https://github.com/what3words/jquery-plugin-w3w-autosuggest/blob/master/path/to/jquery.typeahead.css">
<link rel="stylesheet" href="https://github.com/what3words/jquery-plugin-w3w-autosuggest/blob/master/[path-to-plugin]/css/jquery.w3w-autosuggest-plugin.min.css">NB: Do not forget to copy the flags.png file with the css files
You'll need to register for a what3words API key to access AutoSuggest. The key should be passed to a new instance of the plugin which is initialised on an input field. Initialisation should preferably occur after jQuery and before the