Skip to content

Latest commit

 

History

History
180 lines (131 loc) · 6.53 KB

README.md

File metadata and controls

180 lines (131 loc) · 6.53 KB
Raw

Typeahead Address Picker Build Status

It's not an extension of typeahead plugin itself, but a new data source for twitter typeahead (version > 0.10.0)

The AddressPicker is a subclass of a Bloodhound class. It connects suggestions to Google Map AutocompleteService.

But it's much more than a simple suggestion engine because it can be linked to a google map to display/edit location.

How to use

Without a Google Map

The simplest usage is to use it as suggestion engine, without displaying results on google map.

  1. Include typeahead and google map with places activated

Using this repository

<script src="https://maps.googleapis.com/maps/api/js?v=3.exp&sensor=false&libraries=places"></script>
<script src="https://ajax.googleapis.com/ajax/libs/jquery/2.0.2/jquery.min.js"></script>
<script src="../dist/typeahead.js"></script>
<script src="../dist/typeahead-addresspicker.js"></script>

Or if you want to quickly get started

<script src="https://maps.googleapis.com/maps/api/js?v=3.exp&sensor=false&libraries=places"></script>
<script src="https://ajax.googleapis.com/ajax/libs/jquery/2.0.2/jquery.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/typeahead.js/0.10.4/dist/typeahead.bundle.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/typeahead-addresspicker/0.1.4/typeahead-addresspicker.min.js"></script>
  1. Add an input text
<input id="address" type="text" placeholder="Enter an address">
  1. Instanciate an AddressPicker and a typeahead
var addressPicker = new AddressPicker();

$('#address').typeahead(null, {
  displayKey: 'description',
  source: addressPicker.ttAdapter()
});

With a Google Map

For a better user experience, you can connect it to a google map to display results. You just need to add a div as for a google map place holder and connect it to the AddressPicker

  1. As before

  2. Add a div

<input id="address" type="text" placeholder="Enter an address">
<div id="map"></div>
  1. Instantiate an AddressPicker with the google map div element or ID and connect typeahead events.
// instantiate the addressPicker suggestion engine (based on bloodhound)
var addressPicker = new AddressPicker({
 map: {
  id: '#map'
 }
});

// instantiate the typeahead UI
$('#address').typeahead(null, {
  displayKey: 'description',
  source: addressPicker.ttAdapter()
});

// Bind some event to update map on autocomplete selection
$('#address').bind('typeahead:selected', addressPicker.updateMap);
$('#address').bind('typeahead:cursorchanged', addressPicker.updateMap);

Options

When you instantiate a new AddressPicker you can pass a list of options new AddressPicker(options)

Available Options:

  • map (Hash): Map id and options to link typeahead to a goggle map (default: none).

    • id (String/Element) DOM map element or CSS selector
    • all google.maps.Map constructor options. Default values are:
    {
  zoom: 3,
  center: new google.maps.LatLng(0, 0),
  mapTypeId: google.maps.MapTypeId.ROADMAP
}

  • marker (Hash): Marker options display on the map.

    {
  draggable: true,
  visible: false,
  position: MAP_CENTER
}

  • autocompleteService (Hash) : options passed to google.maps.places.AutocompleteService#getPlacePredictions (default: {types: ['geocode']}) For more details read Google documentation. You can add a lot of options, like get only address for a country, or get only cities.

    Example To get only cities in United States:

    {
  autocompleteService: {
    types: ['(cities)'], 
    componentRestrictions: { country: 'US' }
  }
}

  • zoomForLocation (Number): Zoom value when an accurate address is selected (default: 16).

  • reverseGeocoding (Boolean): Reverse geocoding when marker is dragged on map (default: false).

  • placeDetails (Boolean): If not using with a map, you can skip the getDetails portion to speed up the query (default: false).

Events

Only one event is trigger by AddressPicker object: addresspicker:selected. The event is fired when an address is selected or when the marker is dragged. If reverseGeocoding is activated, a full response is trigger, otherwise only lat/lng.

To simplify google response parsing, we fire an object of type AddressPickerResult with some accessors:

  • lat()
  • lng()
  • addressTypes()
  • addressComponents()
  • nameForType: (type, shortName = false)

Listen that event to get values you need and store them in your form. Here is an example:

// Proxy inputs typeahead events to addressPicker
addressPicker.bindDefaultTypeaheadEvent($('#address'))

// Listen for selected places result
$(addressPicker).on('addresspicker:selected', function (event, result) {
  $('#your_lat_input').val(result.lat());
  $('#your_lng_input').val(result.lng());
  $('#your_city_input').val(result.nameForType('locality'));
});

Tests

The code is tested as much as possible. If you want to add features, please add spec in your pull request.

Demo

A demo is included in the github repository, and is available here: http://sgruhier.github.io/typeahead-addresspicker

Quick example to show how to use twitter typeahead autocomplete and google map API to make an address picker.

This example is just a first try and could be enhanced to fully replace my previous address picker: http://xilinus.com/jquery-addresspicker/demos/

Any suggestions (using issues) or pull requests are welcome.

Todo

  • Connect HTML5 geolocalisation API to display user position
  • Anything else that could make sense to be added :). You can open an issue with a label "feature" to open a discussion on a feature/API you'd like to add.

Credits

@copyright Sébastien Gruhier / Xilinus (http://xilinus.com - http://v3.maptimize.com - http://buy.maptmize.com)