The Google Maps Widget provides a full set of functionality for geographic search and rendering based on Google Maps and Google Places.

Three kinds of geographical data sets or queries can be sent to the Google Maps Widget for rendering:

• An array of place objects: Each place object must contain some description such as title or name, and geographical location such as latitude and longitude. Search results from the Google Places Library can be generated by the Google Maps Widget, and comply with this format.
• A search string: If a map is showing, the search string will use the boundaries of the map to perform a local search. If there is no map - i.e. no geographical reference - then a text search is performed, so in this case the search term should include some geographic reference such as “pizza in boston”.
• A URL link to a KML file: Your Google Drive account supports creating a new document as Google My Maps. You can obtain a URL to your map by selecting Export as KML, then pass this URL to the Google Maps Widget.

This document describes the Application Programming Interface (API) for the Google Maps Widget. There are two ways to invoke the Google Maps Widget: with a field drawn with fixed dimensions on a page, or as an event popup that is rendered full-screen.

To invoke the Google Maps Widget as a field drawn on a ViziApps page, first draw a field. An Image Field is convenient because you can see the full background, as in the following screenshot. If using an Image Field, set the image scaling to Scaled Fit.

In this example, the field is named mapField. The Google Maps Widget is invoked using the name of the ViziApps field, and would typically be created once, in the app's HTML Header, after the app has started. Note the jQuery convention to making reference to the ViziApps field by name: $('#mapField').

$( document ).on( "DOMContentLoaded", function() 
{
    $('#mapField').googlemaps();
});

Whenever a map is available at a later time (i.e. a list of places or a query string or a KML reference), it can be passed to the Google Maps Widget as a value:

var placeList = [
    { name: 'Chicago', lat: 41.878227, lng: -87.649415 },
    { name: 'Dallas', lat: 32.786036, lng: -96.803094 }
}];
$('#mapField').googlemaps( "value", placeList );

It is not necessary to pre-define a field; the Google Maps Widget can be invoked as a full-screen popup. The dataset is passed as a parameter, and an optional title can be added.

$.viziapps.googlemaps({ value: placeList, title: "Some Cities To Visit" });

You may invoke the Directions, Streetview, and Navigation services without first creating a map. You may also set the value to a specific address or search request:

$.viziapps.googlemaps({ value: "601 Biscayne Boulevard, Miami" });
$.viziapps.googlemaps({ value: "pizza in boston", title: "Where To Find Pizza" });
$.viziapps.googlemaps({ directions: "350 5th Avenue, New York, NY" });
$.viziapps.googlemaps({ streetview: "Golden Gate Bridge, San Francisco" });
$.viziapps.googlemaps({ navigate: "38.624634,-90.185043" });

When invoked as a popup, the Google Maps Widget will always incorporate a control bar at its bottom. When invoked as a ViziApps field, the control bar is included by default but may be removed as an option (see Options, below). The control bar includes:

• An exit button, which closes the popup window
• Selection between map types: Roadmap, Satellite, and Terrain
• Search, which open a search dialog
• Expand, which restore the map to its original bounds
• Listing, which shows a table list of places in the map
• An egress button which appears in overlays such as Streetview or Directions

Various options are available to change the appearance and behavior of the Google Maps Widget. Options may be included when the Google Maps Widget is created, as in the following:

$.viziapps.googlemaps({ value: placeList, travelMode: 'walking' });

Options may also be added any time after the Google Maps Widget has been created:

$('#editorField').googlemaps( "option", "travelMode", "walking");

The following options are available for the Google Maps Widget:

An app can monitor event callbacks to catch changes in the widget.

Callbacks may be defined when the Google Maps Widget is created:

$('#mapField').googlemaps( { 
    created: function( event, ui )
    {
        console.log( 'widget DOM ID = ' + ui.id ); // widget DOM ID = mapField
    },
    change: function( event, ui )
    {
        console.log( 'change: ' + JSON.stringify( ui.places, null, '  ' ) );
    }
});

Callbacks may also be defined as a jQuery event after the Google Maps Widget is created:

$('#mapField').bind( 'googlemapsmarker', function( event, ui )
{
    alert( "You tapped: " + ui.title );
    return false; // prevents default action
});

Some callbacks allow the handler to return false, which prevents the widget from processing its default action. All control events allow the app to hook the control buttons in this way.

Methods may be called using the named field:

var placeList = $('#mapField').googlemaps( "value" );
$('#mapField').googlemaps( "egress" );

When invoked as a popup, you can store the widget's ID in the create callback:

var widgetID;
$.viziapps.googlemaps({
    value: placeList,
    create: function( event, ui ) { widgetID = ui.id; }
});
function getWidgetValue() {
    return $( '#' + widgetID ).googlemaps( "value" );
}