JQuery Plugin: imGoogleMaps

This Plugin has been updated. See imGoogleMaps 0.9 – Multiple Addresses, Street View

Although there are other JQuery plugins that enable a developer to integrate Google maps API into websites, I wanted to create a simpler implementation, one that did not have all the options, only the basics. I think that in most situations, a website owner only wants an end-user to be able to view the owner’s address and be able to map directions to that address. In addition, I wanted a plugin that displayed a map interface that is similar to what one would see on Google Maps (auto mode) while also giving the developer the ability to style their own interface (manual mode). This plugin will also display certain Google Map errors codes. In addition, this plugin will allow you to use Ajax to retrieve an address as well as Reverse Geocoding.

Before using the imGoogleMaps plugin, you first need to get an API key for Google Maps. You can obtain a key from here.

Next, download the imGoogleMaps plugin (the plugin can be downloaded from Google Code or JQuery Plugins).

Setup:

This plugin has two modes: auto and manual. There are 5 components used in the plugin interface (regardless of the mode):

Interface Container: This container will hold all the other components of the plugin.
Menu Bar: The menu bar will display the “Get Directions”, “Print Map” and “Print Directions” menu items.
Search Container: The “From” and “To” address input fields and a search button.
Directions: As you may have guessed, the directions will be displayed on this element.
Map Container: container for the map.

Auto Mode:
The plugin is set to “auto” mode by default. In “auto” mode, you only have to style the Interface Container for the plugin. Style the container to your liking. I generally don’t set a height, as the height will be set by the other elements within the container. The following is the div style that I used in the “Auto Mode” demo. You will find that you still have a lot control over the look and feel of the plugin in auto mode.

#mapInfo {
     float: left;
     width: 640px;
     color: #fff;
     font: bold 11px Helvitica, Arial, sans-serif;
}

Using The Plugin

$('#mapInfo').imGoogleMaps({
     address: ‘Cheyenne Mountain Colorado Springs, CO’,
     //optional
     map: {“width”: “400px”, “height”, “400px”},
     //optional
     directions: {"background": "#fff", "text": "#000"},
     //optional
     menu_bar: {"background": "#3366cc", "text": "#fff"},
});

Options:
Note: the directions and menu_bar options are optional. If not set, each will default to a white background with black lettering.

Interface Container: In this case, “#mapInfo”.

Address: The initial address to be mapped. Note: In the example above, the address is of Stargate Command. I really wanted to map the address of the “Lost City”, but apparently, the address can’t be mapped. Interesting…

Directions: In auto mode, this div will be styled automatically. The background and text colors can optionally be entered. The default setting is:

{”background”: “#fff”, “text”: “#000″}

The directions option should adhere to the following format:

{“background”: “#color”, “text”: “#color”}

Map Container: {“width”: “..px”, “height”: “..px”}. This is optional. The default setting is: width: 400px, height: 400px;

MenuBar: In auto mode, this div will be styled automatically. The background and text colors can optionally be entered. The default setting is: {”background”: “#3366cc”, “text”: “#fff”}

As with the “directions” option, the menuBar option should adhere to the following format:

{“background”: “#color”, “text”: “#color”}

Manual Mode:

$('#mapInfoManual').imGoogleMaps({
         address: ‘Cheyenne Mountain Colorado Springs, CO’,
         map: 'googMap',
         directions: 'googDir',
         menu_class: 'googControls',
         print_class: ‘googPrint’,
         search: ‘googSearch’,
         button_class: 'button',
         mode: "manual"
});

You have a bit more control of the design in “manual” mode. As with “auto” mode, you style the Interface Container (in this case, “#mapInfoManual”). But you also have the ability to style the other components within the plugin.

Note: While you do not have the ability to change the layout, you have the ability to add borders, add and image gradient to the background of a component, etc.

Address: From a value on the page
map: ID Selector
directions: ID Selector
menu_class: Class Selector
print_class: Class Selector – the print control container (Print Directions and Print Map links)
search: ID Selector – the search container. This holds the From and To fields.
button_class: Class Selector – the style of the search button.
mode: “manual” – this is mandatory for manual mode

Ajax Address Retrieval Option

In both auto and manual mode, the value for the initial address can be retrieved Ajaxally using a ‘Get’. So instead of using the “address” option, you could do the following:

$('#mapInfo').imGoogleMaps({
        data_url: '../includes/controllers/dbActionController.php',
        data: [{name: "action", value: "doGetAddress"}, {name: "page", value: "venues"}, {name: "venue_id", value: vid}, {name: "lookup", value: "states"} ],
        //optional
        map: {“width”: “400px”, “height”, “400px”},
        //optional
        directions: {"background": "#fff", "text": "#000"},
        //optional
        menu_bar: {"background": "#3366cc", "text": "#fff"},
});

data_url: The URL where you will retrieve the address
data: Any data that you want to send to the data_url. The format for this option should be:

[{name: "name1", value: "value1"}, {name: "name2", value: "value2"}, etc. ]

The options will be converted into name=value pairs and sent to the data_url. The data returned should be of type text.

Reverse Geocoding:

Another way to map an address using this plugin is by using reverse geocoding above. Just supply the Latitude and Longitude and the address (if known) will be displayed on the map.

$('#mapInfo').imGoogleMaps({
        lat_lng: {“lat”: “0.232’, “lng”: “454”}
        //optional
        map: {“width”: “400px”, “height”, “400px”},
        //optional
        directions: {"background": "#fff", "text": "#000"},
        //optional
        menu_bar: {"background": "#3366cc", "text": "#fff"},
});

Error Codes

The imGoogleMaps plugin will also display the following Google Map errors:

G_GEO_UNKNOWN_ADDRESS: No corresponding geographic location could be found for one of the specified addresses. This may be due to the fact that the address is relatively new, or it may be incorrect.\
G_GEO_UNAVAILABLE_ADDRESS: The geocode for the given address or the route for the given directions query cannot be returned due to legal or contractual reasons.
G_GEO_SERVER_ERROR: A geocoding or directions request could not be successfully processed, yet the exact reason for the failure is not known
G_GEO_MISSING_QUERY: The HTTP q parameter was either missing or had no value. For geocoder requests, this means that an empty address was specified as input. For directions requests, this means that no query was specified in the input.
G_GEO_BAD_KEY: The given key is either invalid or does not match the domain for which it was given.
G_GEO_BAD_REQUEST: A directions request could not be successfully parsed.

Click here to view demos of the imGoogleMaps plugin.