Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More
Socket
Sign inDemoInstall
Socket

jquery-plugin-w3w-autosuggest

Package Overview
Dependencies
Maintainers
2
Versions
3
Alerts
File Explorer

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

jquery-plugin-w3w-autosuggest

Easily capture 3 word addresses on your website with the 3 word address JQuery plugin by what3words

  • 1.5.0
  • latest
  • Source
  • npm
  • Socket score

Version published
Maintainers
2
Created
Source

what3words what3words autosuggest jQuery plugin

Build Status

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.

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.

OptionTypeOptional?DefaultDescription
keyStringmandatoryYour API key, mandatory unless you bring your proxy page as api_end_point to hide your key
debugBooleanoptionalfalseEnables debug info in console
hintBooleanoptionaltrueDisplays hint result (default is false for Arabic)
logoBooleanoptionaltruedisplays what3words logo on the input as a svg image
multilingualBooleanoptionaltrueEnables the multilingual variant of autosuggest
langStringoptionalenA supported 3 word address language as an ISO 639-1 2 letter code.
resultsNumberoptional3Number of items to show in the result list
country_filterStringoptionalnullSet country code as an [ISO 3166-1 alpha-2]https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 2 letter code
countNumberoptional50Number of items to retrieve from API
directionStringoptionalltrdefault is ltr, can be set to rtl e.g. for Arabic
placeholderStringoptionalSets the placeholder text of the input field (default is `placeholder: 'e.g. lock.spout.radar').
validationBooleanoptionaltrueAdds UI validation result using jquery-validation
typeaheadDelayNumberoptional100delay in ms before sending new API request
api_end_pointStringoptionalfor advanced integration, allow you to proxy request to our API and then hide your key

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:

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:

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

VersionDateDescription
v1.5.001/05/18update 3 word address validation for Japanese with interpunct
v1.4.006/02/18bump jquery version to prevent security issues
v1.3.127/09/17change w3w svg logo url
v1.3.024/04/17fixes conflict with standard jquery-typeahead css, adds searched, selection and cancel events
v1.2.129/03/17prevent warning message on ajax request and test closest form for validation
v1.2.010/03/17refactoring plugin : tidying up dependencies, building single and bundle distribution files. Parameters : multilingual replace auto_detect_lang, country_filter replaces country_selector using only an ISO_3166-1_alpha-2 code
v1.1.013/02/17uses API method autosuggest-ml with number of background results increased to 50
v1.0.007/02/17Initial release

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

FAQs

Package last updated on 01 May 2018

Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

Packages

npm

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc