Working with Google Map object (for Javascript programmers)

This section describes how to access the original Google Map object - JavaScript object that is used in creation of the map.

The map object

The MapEx creates a global JavaScript variable called WidgetkitMaps. It's an array of objects, each object has following fields:

• id - the unique id of the widget. This id is generated randomly every time the web page is displayed. This id is assigned to the id attribute of the div tag of the MapEx widget. The id is a string of a form wk-map-exXXX, where XXX - is a random sequence of digits and letters.
• map - the Google Map object used for the widget.

Global JavaScript functions available:

• function getWidgetkitMap(id) - returns map object for specified id or null if object with this id not found.

Map object usage examples (JavaScript)

Initialization

You can work with Google Map object(s) only after it's ready:

• The Google Map script has been loaded
• The MapEx widget has initialized and configured the Google Map object(s)

The Google Map is usually loaded in asynchronous mode, it means that it will execute and be ready at the end, so you should wait until it becomes available.

Processing the initialization event

The MapEx triggers a custom JavaScript event named MapExInit when all the MapEx widgets and Google Map objects have been initialized and are ready for use. This event has no parameters. So, to work with Google Map object(s), you should start with the following code:

<script>
	jQuery(function($){
		$(document).on("MapExInit", function(){
			/*
			Here you can write your code 
			to access the Google Map object
			
			...
			
			*/
		});
	});
</script>

Please, keep in mind, that custom events may not be supported in all browsers, please, refer to the following documentation for more information:

• jQuery Custom Events
• jQuery Trigger Event Function
• Feature support: EventTarget.dispatchEvent
• Custom Event at MDN web docs

Alternative method

I'm not aware of any other alternative stable method to detect when the Google Map object becomes initialized. Probably you could try setting some timeout event, but I don't recommend to do that. The example below is for demonstration purposes only, don't use it at production websites!

<script>
	jQuery(function($){
		/*
		We set timeout for 3 seconds here, believing 
		that it's enough to load the Google Map API script
		and initialize the MapEx widgets.
		*/
		setTimeout(function(){
			/*
			Here you can write your code 
			to access the Google Map object
			
			...
			
			*/
		}, 3000);
	});
</script>

Access to specific Google Map object

It may not be obvious how to know the id of desired map if the id is generated randomly. In this case you may put the widget inside a div with predefined HTML id attribute, for example:

<div id="my_map">
	[widgetkit id="12"]
</div>

Now we can use the id of the container above in the JavaSript calls to identify the widget:

<script>
	jQuery(function($){
		//Waiting until the Google Map object becomes available:
		$(document).on("MapExInit", function(){
			//Get the id of the widget based on the HTML container id:
			var map_id = $('#my_map>div').attr('id');
			if (!map_id){
				console.log("Error! MapEx widget not found");
				return;
			}
			
			//Get the map object by its widget id
			var map_object = getWidgetkitMap(map_id);
			if (!map_object){
				console.log("Error! Failed to get the MapEx object");
				return;
			}

			/*
			Now you can interact with the map object, for example,
			let's change the zoom level of the map
			*/
			map_object.setZoom(8);
		});
	});
</script>

Listing all Google Map objects (MapEx instances)

If you have several MapEx widgets on a page, you can list them, using the following code:

<script>
	jQuery(function($){
		//Waiting until the Google Map object becomes available:
		$(document).on("MapExInit", function(){
			//All MapEx containers have "widgetkit-map-ex" CSS class
			$('div.widgetkit-map-ex').each(function(index, element) {
				/*
				index is a zero-based index of the MapEx instance
				element - HTML object-container
				*/
				var map_id = $(element).attr('id');
				if (!map_id){
					console.log("Error! MapEx widget not found");
					return;
				}
				
				//Get the map object by its widget id
				var map_object = getWidgetkitMap(map_id);
				if (!map_object){
					console.log("Error! Failed to get the MapEx object");
					return;
				}

				/*
				Now you can interact with the map object, for example,
				let's change the zoom level of the map
				*/
				map_object.setZoom(8);
			});
		});
	});
</script>