jQuery Simple Google Map Usage

The plugin is designed to provide a quick way to implement a Google Map. Based on user interaction, it will geocode the address provided, and display the location on a map.

It is recommended to invoke the plugin on a clickable element, such as a link or button. The focus of this plugin is to only execute on a user initiated request.

Get an API key.

Obtaining and using an API key is now required. You can find out more about obtaining a Google API key by visiting this link.

Once you get your key, provide it the plugin before invoking the Simple Map Plugin. The following will apply your key directly to the plugin's defaults. Make sure to whitelist your domain, otherwise anyone can use your key, and eat up those precious requests.

    
$.fn.simpleMap.defaults.googleApiKey = 'your_key_here';
    

Include the assets.

Just like any other jQuery plugin, load jQuery, then load the plugin. If you plan on using the overlay, load the stylesheet too.

Load CSS (if you plan on using the built-in overlay)

<link rel="stylesheet" href="jquery-sm-style.css">

Load jQuery

<script src="jquery.min.js"></script>

Load Simple Maps

<script src="jquery.simpleMap.js"></script>

Initializing the plugin.

The plugin may be initialized by invoking it on the target HTML element. Where button is the item that will trigger the map. Reference the ID of the html element that will contain the map. The mapElementId option is required to tell the plugin where to draw the map.

    
$('button').simpleMap({
    mapElementId: 'your-map-element-id'
});
    

Providing an address.

The Simple Map Plugin offers two main ways of passing in an address to be geocoded and placed on a map. The recommended method is to provide a data-sm_address="address to be geocoded" on the element you are invoking the plugin on.

    

    View Map

    

Alternatively, You can pass an option to the plugin by assigning an address to options.address. If the address is already provided in the data attribute like in the above example, then that address will be used. This way, you can use this option to provide the plugin with a default address.

    
$('button').simpleMap({
    theAddress: "1301 N Summit St, Toledo, Ohio",
    mapElementId: 'your-map-element-id'
});
    

Using the overlay.

The Simple Map Plugin comes with a built-in overlay you can use to display the map. When using the built-in overlay, you do not need to provide options.mapElementId

Set the options.useOverlay to true.

    
$('button').simpleMap({
    useOverlay: true
});
    

Autoloading the map.

Although the plugin is designed for user input, it can be self invoked on an element and load within that element automatically. You do not need to provide options.mapElementId when auto loading the map.

    
$('#my-map-container').simpleMap({
    autoLoad: true
});
    

Ethos

The Simple Map Plugin is designed to only load assets and draw maps if the user requests it. When a user clicks on the invoked element, the plugin will then load the Google Maps API and draw the map. If the user never requests a map, then the API never loads, and the plugin is merely invoked and ready for user input.

Google Maps API Handling

The plugin will load the Google Maps Javascript API for you. If the Google Maps API is already loaded, or if it is loaded by other means, you can turn the API loading off by passing options.isApiLoaded to true. This will bypass the loading of the API.

The plugin keeps track of whether the API is loaded, so no worries if you have multiple targets on one page.

    
$('button').simpleMap({
    mapElementId: 'your-map-element-id',
    isApiLoaded: true
});
    

Google Maps Passthrough Options

This plugin is meant to be quick and simple, so only a few Google Maps options are available for passthrough. Refer to the Google Map Javascript API Reference for possible values.

Map Options

    
mapSetup: { //some basic Google Maps options
    scrollwheel: true, //bool: enable disable scroll zooming on mousewheel
    streetViewControl: false,//bool: enable street view controls UI
    panControl: false, //bool: enable the pan controls UI
    zoom: 10, //int: the map zoom level
}
    

Map Marker Options

    
markerConfig : {
    title: null, //string: the title of the marker as a string
    icon: null //string: the URL of the marker icon as a string
}
    

Infowindow Options

Note: The infowindow will only be applied if there is a value available for html

    
infoWindowConfig: {
    autoShow: false, //bool: auto show the map info window
    maxWidth: 240, //int: set the info window max width
    html: null//string or $(element).html(): The HTML to display in the info window
}