Skip to content

Latest commit

 

History

History
206 lines (174 loc) · 7.89 KB

README.md

File metadata and controls

206 lines (174 loc) · 7.89 KB
Raw

vsGoogleAutocomplete

Angularjs autocomplete module using Google Maps JavaScript API v3 and embedded autocomplete validator

Demo

Features

  • Has special embedded validator for autocomplete validation
  • Can easy parse address components through special directives
  • Uses google formatted address as result of autocomplete
  • Uses last version of Google Maps JavaScript API (v3)

Install

Bower

bower install vs-google-autocomplete

Getting started

  1. Add the Google Places library script to your index.html
<script type="text/javascript" src="https://maps.googleapis.com/maps/api/js?libraries=places"></script>

  1. Add vs-google-autocomplete.js to your index.html

  2. Add vsGoogleAutocomplete module dependency:

angular.module('yourApp', ['vsGoogleAutocomplete']);
  1. Add vs-google-autocomplete directive to input field:
<form>
  <input vs-google-autocomplete
         ng-model="address"
         name="address"
         type="text">
</form>

Autocomplete options

You can add an options object as attribute parameter, which will restrict autocomplete results.

Options object can contain the following properties:

  • types {Array.<string>} (In general only a single type is allowed):
    • 'geocode'
    • 'address'
    • 'establishment'
    • '(regions)'
    • '(cities)'
  • bounds {google.maps.LatLngBounds}
  • componentRestrictions {object}

Example:

<form>
  <input vs-google-autocomplete="options"
         ng-model="address"
         name="address"
         type="text">
</form>
$scope.options = {
  types: ['(cities)'],
  componentRestrictions: { country: 'FR' }
}

In example above, autocomplete results will only consist of cities of France.

Parsing address components

You can bind your model with autocomplete address components.

Directives for parsing:

  • vs-place - gets place detail results object
  • vs-place-id - gets unique identifier denoting place
  • vs-street-number - gets street number of place
  • vs-street - gets street name of place
  • vs-city - gets city name of place
  • vs-state - gets state name of place
  • vs-country-short - gets country iso code of place
  • vs-country - gets country name of place
  • vs-latitude - gets latitude of place
  • vs-longitude - gets longitude of place
  • vs-post-code - gets postcode of place
  • vs-district - gets district of place (administrative_area_level_2)

Example:

<form>
  <input vs-google-autocomplete="options"
         ng-model="address.name"
         
         vs-place="address.place" 
         vs-place-id="address.components.placeId"
         vs-street-number="address.components.streetNumber" 
         vs-street="address.components.street"
         vs-city="address.components.city"
         vs-state="address.components.state"
         vs-country-short="address.components.countryCode"
         vs-country="address.components.country"
	     vs-district = "address.components.district"
         
         name="address"
         type="text">
</form>

Embedded validator

Module, as an addition, also provides special validator for autocomplete validation.

Default usage

  1. Add vs-autocomplete-validator.js to your index.html

  2. Add vs-autocomplete-validator directive to input field:

<form>
  <input vs-google-autocomplete
         vs-autocomplete-validator
         ng-model="address"
         name="address"
         type="text">
</form>

By default, validator checks if autocomplete result is a valid google address (selected from drop down list).

Additional validators

You can add additional validator by adding denormalized validator name as attribute parameter. If you need more than one additional validator, you can add validator names using comma(,) separator.

Validator names in html are normalized in javascript code, so validator with name vsStreetAddress should have name vs-street-address in html.

Available validator names

  • vsStreetAddress - normalized name of validator, which checks if autocomplete result is full address (street number, street, ...)

This module is under development and now it has only one additional validator (and one by default). Please, if you need other additional validators, you can write about this in issues, we will be grateful to you :).

Example

<form>
  <input vs-google-autocomplete
         vs-autocomplete-validator="vs-street-address"
         ng-model="address"
         name="address"
         type="text">
</form>

In the example above validator will checks if autocomplete result is a valid google address and if it is a full address (street number, street, ...).

Validation errors

Validator publishes validation errors if validation is failed.

If validation is failed, validator publish error with name vsAutocompleteValidator to NgModelController.$error hash object and name of each embedded validator to NgModelController.vsAutocompleteErorr hash object.

Custom validators

You can also add your own validator for your own needs. Embedded validator should validate PlaceResult object, which returns after autocomplete. For this, you should add factory to your main module, which must return function.

Custom validator template:

angular.module('yourApp')
  .factory('validatorName', function() {
    /**
    * Implementation of custom embedded validator.
    * @param {google.maps.places.PlaceResult} PlaceResult object.
    * @return {boolean} Valid status (true or false)
    */
    function validate(place) {
    	// ...
    }
    	
    return validate;
  });

Rules for custom validator:

  • you should add factory to any module of your app
  • factory must always return function (embedded validator implementation)
  • function for validation always gets PlaceResult object as parameter
  • you should implement function, which returns
  • factory name - it is normalized embedded validator name (eg. 'validatorName' in factory can be 'validator-name' in html)

After adding custom validator, you should add its name as attribute parameter to vs-autocomplete-validator directive. Validator with name someValidatorName in factory should have name some-validator-name in html.

Core developers can inject in validator factory vsGooglePlaceUtilityservice, which contains useful functionality for working with PlaceResult object (parameter of function for validation). You can look at this utility service in vs-autocomplete-validator.js :).

Author

K.Polishchuk (http://github.com/vskosp)

License

MIT © K.Polishchuk

Credits

Google Maps JavaScript API https://developers.google.com/maps/documentation/javascript/places-autocomplete