jquery-plugin-w3w-autosuggest v1.5.0

 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.8.0 https://www.npmjs.com/package/jquery-typeahead
• jquery-validation plugin 1.16.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="[path-to-plugin]/js/jquery.w3w-autosuggest-plugin.bundle.min.js"></script>

or separately

<script src="path/to/jquery.typeahead"></script>
<script src="path/to/jquery.validation"></script>
<script src="[path-to-plugin]/js/jquery.w3w-autosuggest-plugin.min.js"></script>

Add the CSS to the <header>:

<link rel="stylesheet" href="[path-to-plugin]/css/jquery.w3w-autosuggest-plugin.bundle.min.css">

or separately

<link rel="stylesheet" href="path/to/jquery.typeahead.css">
<link rel="stylesheet" href="[path-to-plugin]/css/jquery.w3w-autosuggest-plugin.min.css">

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

<script>
 $('#w3w-address').w3wAddress({
  key: 'YOUR-API-KEY-HERE'
 });
</script>

AutoSuggest

The plugin authenticates and interacts with the what3words RESTful API autosuggest method. It returns a list of 3 word addresses based on user input and other parameters. This method provides corrections for the following types of input error:

• typing errors
• spelling errors
• misremembered words (e.g. singular vs. plural) words in the wrong order

The autosuggest method determines possible corrections to the supplied 3 word address string based on the probability of the input errors listed above and returns a ranked list of suggestions.

See also the what3words API AutoSuggest documentation for more detailed information.

Input 3 word address

You will only receive results back if the partial 3 word address string you submit contains the first two words and at least the first character of the third word; otherwise an error message will be returned.

Language

The lang parameter is mandatory for autosuggest; we recommend that you set this according to the language of your user interface, or the browser/device language of your user. If your software displays 3 word addresses to users (in addition to accepting 3 words as a search/input) then we recommend you set the lang parameter for this method to the same language that 3 word addresses are displayed to your users.

You can use the what3words API Get Languages method for a list of all currently loaded and available 3 word address languages.

Results

By default, 3 results are displayed with a 50 background suggestions available to filter by country.

Options

Parameters to be passed to the AutoSuggest plugin.

NOTES

aria-invalid

The attribute aria-invalid is used even if validation is set to false. Without validation, selecting a 3 word address from the result list ensure the address is valid. For references see:

• 1 : https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-invalid_attribute
• 2 : https://www.w3.org/TR/wai-aria/states_and_properties#aria-invalid

api_end_point

this new feature (since version 1.5) allow you to proxy requests to your own server and then hide your what3words API key from your endusers.

The trailing / is needed as the plugin append autosuggest-ml or autosuggest regarding your constructor options.

This API endpoint must then provide a rest endpoint with the desired operations autosuggest-ml and/or autosuggest according your needs.

Building

Prerequisites

• node, gulp

Set up

$ npm install

Recommended : install gulp as global

$ npm install --global gulp-cli

Build

$ gulp build

Clean Dist folder

$ gulp clean

Watch for Development

$ gulp

The build process is automatic using gulp watch. Gulp is watching for Javascript & CSS changes and processing final files to the ./dist folder automatically.

To add or customise styling, set up the development environment, and simply edit / add SCSS files in ./src folder.

sprite

What was done:

• upload images from ./src/images/flags into http://responsive-css.us/ ,
• save sprite and css in src/images/sprite
• use https://tinypng.com/ to shrink image weight

Use sample

The sample page uses the browser localStorage to store your API key. You can find it here where multiple configurations can be found.

Try it live : sample.html

Revision History

Nb Using European Date Format :smile: sorry :us: