View on GitHub

gmUserInput

A jQuery plugin for user input with Google Maps

Download this project as a .zip file Download this project as a tar.gz file

Dependencies

        	
<script type="text/javascript" src="javascripts/jquery-1.8.3.js"></script>
<script type="text/javascript" src="javascripts/jquery-ui-1.9.2.custom.min.js"></script>
<script type="text/javascript" src="http://maps.google.com/maps/api/js?sensor=true&libraries=places"></script>
<script type="text/javascript" src="javascripts/jquery.formalize.min.js"></script>
<script type="text/javascript" src="javascripts/jquery.gmuserinput.js"></script>

Plugin setup

The principle of the plugin is very simple, it will display the user a google maps with a default marker. The user will then be able to drop the marker in the desired location. 

        	
…        	
<div id="myMap" style="height: 400px; width: 800px;"></div>
…
<script>
    $( '#myMap' ).gmUserInput();
<script>

If you run this code as is you will get a pretty dumb result, in fact you will not be able to see the result of user interaction with the map, so let's develop further.

Gathering user input

Upon user inteaction with the map, mainly dropping the draggable marker into the map to add new locations, the plugin triggers following events:

The callback registering to these events, will receive the corresponding marker as input, in field data.marker. Additionally the 'makerlocated' callback will receive the location details in field data.details in Google's Geocoder result format.

Mobility through the map

You can initialize the map to be centered on a given point in the map ( see center option in Options section below ). The map will display usual map controls for the user to freely move around the map.

To simplify this mobility, you may want to provide a way for the user to directly type in the name of a country, city, street, etc... the same way Google maps web page provides.

In the plugin, this can be achieved with the option search ( false by default ). If set to boolean value true, the plugin will add an autocomplete search box for the user to freely navigate the map through keyboard input.

Basic example

So with this basic knowledge of the plugin behavior, we can already build up a basic map input plugin: 

        	
…        	
<div id="myMap" style="height: 400px; width: 830px;"></div>
<div id="userInput" style="font-weight: bold;"></div>
…
<script>
    $( '#myMap' ).gmUserInput( { search: true } );
    $( '#userInput' ).bind( 'markerlocated', function( evt, data ) {
        if( typeof data !== 'undefined' &&
            typeof data.marker !== 'undefined' &&
            typeof data.marker.item !== 'undefined' ) {
				$( '#Example1Input' ).css( 'color', '#00ff00' )
                   .text( "LOCATED: " + data.details.formatted_address );
        }
    } );
    $( '#userInput' ).bind( 'markerselected', function( evt, data ) {
        if( typeof data !== 'undefined' &&
            typeof data.marker !== 'undefined' &&
            typeof data.marker.item !== 'undefined' ) {
        	$( '#Example1Input' ).css( 'color', '#4096EE' )
                   .text( "SELECTED: " + data.marker.item.details.formatted_address );
        }
    } );
<script>

So now you can drag & drop the marker in map, use the search box to find places, and select already dropped markers to see the plugin output. Note that if you relocate an already dropped marker, the plugin will trigger a new markerlocated event.

Example 1 output

Note that Google's Map strange display, it is due to this page's layout template ( image borders, shadow, etc... ). It should not be the case when applying this plugin into your own layouts.

Customizing the plugin

This example shows you how to personalize the plugin to use your own custom markers. 

        	
…
/** css **/
.myCustomMarkerBackground {
    width: 60px;
    height: 60px;
    background-color: rgba( 255, 255, 255, 0.7 );
    border-radius: 7px;
    -moz-border-radius: 7px;
    border: 1px solid #fff;
}
…
<img id="myMarker" src="images/bus_stop.png"></img>
<div id="myMap" style="height: 400px; width: 830px;"></div>
…
<script>
    $( '#myMap' ).gmUserInput( { search: true, 
                                 dropper: '#myMarker',
                                 dropperTitle: 'Place the bus stops',
                                 center: [ 43.699899, 7.277663 ],
                                 dropperWrapClass: 'myCustomMarkerBackground',
                                 addMarkerShadow: true,
                                 zoom: 14 } );
<script>
Example 2 output

Note that again, as the marker is an img element and therefore impacted by this page's global styling to images. If you see the marker out of its background, just reload the page and it should be put in the correct place.

Add shadow to your icon marker

With the option addMarkerShadow set to true, when the user drops the marker in the map, the plugin will replace the icon image with the shadowed version. For that, the plugin will replace the URL of your icon 'myicon.png' with 'myicon_shadow.png', so ensure that the corresponding resource is available.

The same way, the plugin will replace the shadowed icon by the original one when replacing the marker in the map.

Customizing the marker container

As seen in previous example, you can provide a custom class for your marker's background. In such case, the wrapper around the marker will take this class so you can style it at will.

Options

Option Default Description
zoom 15 The zoom level to apply to the map
fullscreen false If true, the map will be displayed occupying the full browser viewport. Example
search false If true, the plugin will add a autocomplete search box to the map.
center [ 43.540289,
-5.653692 ]		 [ latitude, longitude ] to center the map when it is first displayed to the user.
dropper null Represents the element ( marker ) that will be used to gather user input. It can be:
- null, so the default marker will be displayed
- string, that should correspond to a jQuery selector
- object, i.e., the result of a jQuery selection
dropperTitle Drop me in
the map		 The message to add in the title attribute of the droppable element, if supported.
dropperWrap true Set to false if you don't want your droppable element to be wrapped by a container. To allow styling of this containing wrapper, you can specify your own wrapper class with option dropperWrapClass.
dropperWrapClass gmuiWrapClass The class to apply to the container wrapping the droppable element(s)
type ROADMAP The default map type. Available options are: ROADMAP, SATELLITE, HYBRID, TERRAIN. Any other value will default the map to ROADMAP
defaultMarker images/default_marker.png The icon to be used as the droppable marker. By default, it will be the same icon added to the map each time it is dropped. To add modify the actual icon that is placed in the map, see option addMarkerShadow
addMarkerShadow false When the user drops a droppable marker in the map, if this option is set to true, the icon of the marker added to the map will be replaces by <defaultMarker>_shadow<extension>. For example 'images/default_marker.png' will be replaced by 'images/default_marker_shadow.png'
singleMarker false If set to true, the plugin will allow the user to drop the droppable marker only once in the map. Note that once dropped, the user will still be able to relocate it around.

Public methods

Accesing the plugin's public methods

Once instantiated, the plugin will store a self reference into the container's data, in field 'gmUserInput'. So, to retrieve the plugin in order to access it's public methods, you can do: 

        		
<script>
    $( '#myMap' ).data( 'gmUserInput' ).publicMethod();
<script>

centerMapInMarker

Centers the map in the coordinates of the provided marker.

Parameters:

centerMapInLatLon

Centers the map in the latitude and longitude provided.

Parameters:

getMarkers

Returns the list user's input in the form of Google Map's marker objects.

getMarkersAsItems

Returns the list user's input in the form of javascript objects with following attributes:

addMarker

Adds a marker to the map.

Parameters: a javascript object with following attributes:

addMarkers

Adds a list of marker to the map. Each marker in the list must be a javascript object as described in method addMarker.

removeMarker

Removes a marker from the map.

Parameters: the reference to the marker as

Events

These events are triggered in the plugin's container.

The data provided to the callback data parameter is always a Google's Map marker object. The plugin always adds to this object a new attribute: item. This attribute is a javascript object with following attributes:

Additionally, for markerlocated event, the plugin will provide the attribute details containing the geolocatization result in in Google's Geocoder result format.

markeradded

Triggered when the user drops the droppable marker in the map. Note that this event is triggered before markerlocated, so the attribute marker.item.loc will be missing.

markerlocated

Triggered when the plugin has geolocated a marker that has just been added to the map. The data provided to the event callback will contain the attribute details containing the geolocatization result in in Google's Geocoder result format.

If the plugin fails to locate the marker, the attribute details will be null and the marker's associated address in marker.item.loc will be set to NO_ADDRESS_AVAILABLE.

markerselected

Triggered the user selects a marker that has been previously added to the map.