Introducing The New Javascript API 1.3: Improved Interactivity and Customization

7 min - Author: Marine

.rb-lazy { display: none; }

At Woosmap, we’re always improerseing our products based on your feedback. We would like developers and users of Woosmap to benefit from these latest updates. Today, the Woosmap developers team has released a new version of the Woosmap Javascript API (1.3).

This release comes with three major changes:

Maps build with Woosmap Javascript API can now be boosted with new parameters from Google Maps, Version and Region, and new mouseover event to ease map exploration (get info on assets on the map with a simple hover).
Developers can easily and quickly count and filter assets on a map extend (“Here is a map with assets you’re looking for. By the way, there is X assets matching to your search fo this type, Y of this type and Z of this type.”)
Custom attributes can now be part of the search queries to fit with specific customer needs (“What’s the nearest asset of this brand (Type), with this service (Tag) and this property (Custom Attribute)”).

Mouse Events

You’re now able to register all kinds of mouse events using the BaseView class or an extended child class, woosmap.View and woosmap.TiledView. The name of the event should be one of the following: click, mousedown, mouseout, mouseover, mouseup.

An action may trigger multiple events. For instance, a click first triggers mousedown, when the button is pressed, then mouseup and click when it’s released. For touchscreen and touchpad devices mouse events also happen, they are emulated.

Let’s test yourself the mouse events with the following example (based on jsFiddle)

Here is the highlighted javascript snippet used to register the mouseover event and display hovered stores attributes using the woosmap.TemplateRenderer object.

var mapView = new woosmap.TiledView(map, {/*options*/});
//Use a template to render store properties as HTML
var customTemplate =  "<div class='store-photo'>< img src=''/></div>"
+ "<div class='store-title'>Introducing The New Javascript API 1.3: Improved Interactivity and Customization</div>"
+ "<div class='store-address'> </div>";
//Register the mouseover event
mapView.addListener('mouseover', function(store) {
// Render the hovered store info using woosmap.TemplateRenderer
var templateRenderer = new woosmap.TemplateRenderer(customTemplate)
var renderedTemplate = templateRenderer.render(store.properties);
woosmap.$('#mouse-hover-content').html(renderedTemplate);
});

See EventListeners on Woosmap Doc for more details.

Combine Local Search With Filtering

The Woosmap devteam has introduced a new way to search your assets by combining attributes filtering with geographical regions. You’ll need to implement the woosmap.search.SearchParameters({}) and specify, for geographic bias, the location properties (lat/lng and maxDistanceFromUser) and build the Query property for attributes search. All the fields listed in the data api section are also available for search within the Javascript API.

The following example focuses on how to filter by type and tag taking into account a user geocoding input.

Here is what the SearchParameters dictionary looks like.

var paramForSearch = {};
// set Geography Bias based on user geocoding input
paramForSearch.lat = latitude;
paramForSearch.lng = longitude;
paramForSearch.maxDistanceFromUser = parseInt(woosmap.$("#stores-distance").val()) * 1000;
// set the Query that looks like "type: 'myType' AND tag: 'myTag'"
paramForSearch.query = typeCondition + operator + tagCondition ;
// finally, build a SearchParameters object and pass it to the mapView
var searchParameters = new woosmap.search.SearchParameters(paramForSearch);
mapView.setSearchParameters(searchParameters);

Instead of building yourself the Query string, you could use some woosmap helper class as shown in the next example.

Combine Search in Attributes with Bounds

Using the SearchParameters object enable you to search, filter and count your assets confined to the bounds of the map view. To implement this feature you have to set the bounds property with a Google LatLngBounds object.

As you can see, we also count and zoom to the returned assets. To do so, you have to use woosmap.DataSource object.

var dataSource = new woosmap.DataSource();
dataSource.countStoresByParameters(searchParameters, function(totalStores) {
woosmap.$('#count-store-value').text(totalStores.count);
});
dataSource.storesBoundsByParameters(searchParameters, function(extent) {
if (extent.bounds.south) {
var bounds = new google.maps.LatLngBounds().union(extent.bounds);
mapView.fitBounds(bounds);
}
});

All of the sample code presented above is hosted on jsFiddle, an online code playground that provides a customized environment to test your JavaScript, HTML, and CSS code right inside your browser. Don’t hesitate to fork all previous jsFiddle samples and play with them using your own public key.

Support For Version and Region Google Maps Options

When you load the Google Maps JavaScript API via Woosmap (by default, when loading Woosmap Javascript API, Google Maps is also loaded), you can customize several parameters like your Client ID or Google Maps API Key. We recently added two new parameters, region and version.

Region

If you want to alter your application to serve different map tiles or bias the application, you can add a region parameter. The region parameter accepts Unicode region subtag identifiers which (generally) have a one-to-one mapping to country code Top-Level Domains (ccTLDs). For example, region: "GB". See the google doc for details on Google API version.

Version

You can indicate which version of the Google Maps Javascript API to load in your application by specifying the version parameter. The following options are supported:

The experimental version, specified with version:"3.exp".
The release version, specified with version:"3".
A specific version number. For example version:"3.26". or version:"3.27".

If you do not explicitly specify a version, you will receive the experimental version by default if you are on the standard plan (this includes customers who do not provide a key). If you’re on the premium plan and don’t specify a version, you will receive the release version by default. See here for details on Google API version.

Sample

Here is a complete sample of MapsLoaderOptions object that load Google Maps API version 3.26 for the french region.

var mapsOptions = {
key: "xxx_Your_Google_Maps_Browser_Key_xxx",
clientId: "a_client_id",
librariesToLoad: ["places"],
channelId: "a_channel_id",
language: "fr",
region: "FR"
version: "3.26"
}
var loader = new woosmap.MapsLoader(mapsOptions);

See Woosmap Maps Loader Supported Options for more details.

Changelog

You can check the full changelog on Woosmap Developers Documentation. Here is the summarized changelog:

Adds eventListeners option to renderers constructor allows registering handlers for named events on markers.
Adds woosmap.query namespace to handle new style queries.
Adds woosmap.search.SearchParameters query property that allows passing raw string queries.
markers parameter in woosmap.View constructor may also be a BaseViewOptions object.
Adds support for region parameter in MapsLoaderOptions
Adds support for version parameter in MapsLoaderOptions
Adds bounds and count support to woosmap.DataSource
Adds addListener & removeListener methods to woosmap.BaseView. This allows registering events for the event view independently of the event source (TiledImageLayer, DefaultRenderer, MarkersRenderer or a custom renderer).

Useful Links

Woosmap Javascript API 1.3 reference.
Changelog of Woosmap Javascript API.

If you have any questions about the content or the process described, please don’t hesitate to reach out to me through the contact page.