Tabris Maps 2.0 released

Moritz Post
August 30, 2016 | 3 min Read

With the recent advancements in maps features on Android and iOS we also took the time to overhaul the tabris-plugin-maps plugin. The new version 2.0.0 provides completely new APIs that are more in line with Tabris.js and offer a higher degree of control.

Creating a map in your Tabris.js application is as simple as the following snippet:

new esmaps.Map({
  left: 0, right: 0, top: 0, bottom: 0
}).on("ready", function() {
  // Paris with a radius of 2000 meters
  this.moveToPosition([48.8644458, 2.3589976], 2000);
}).appendTo(page);

Note how we introduced a new namespace called esmaps to access the Map widget. All following interactions have to be done after the ready callback fired.

New Properties

One of our main goals was to provide better control over how to position the map on a certain region. For that purpose we introduced the properties position, camera and region. Each of these properties is able to control the map with a certain granularity.

Position

The position is the simplest way of placing the camera at a certain point. It moves the camera to a given position while keeping the current zoom level.

map.set("position", [48.8644458, 2.3589976]);

Camera

The camera is a more sophisticated object to reposition the map. At the moment it only holds the position property but it will be expanded to also provide e.g. tilt.

map.set("camera", {position: [48.8644458, 2.3589976]});

Region

The region allows the finest control. It spans a certain region on the map, allowing to also affect the zoom level. The region is given as the two positions southWest and northEast.

map.set("region", {
  southWest: [48.8644458, 2.3589976],
  northEast: [48.8821597,2.3856527]
});

Events

To give finer grained control when reacting to changes on the map position we have introduced new API to differentiate between user initiated and programmatic changes. The event change:camera is fired whenever the visible map changed, be it via user interaction or by any of the map APIs. Additionally the cameramove event is fired when the user interacted with the map.

Functions

To simplify camera positioning and to give some more control on the way the camera change happens we have added the following functions on the map.

moveToPosition

The function moveToPosition(position, radius, [options]) places the map on a certain position and zooms the map to show all of the given radius. In addition the options parameter allows to apply some padding around the radius and move the camera in an animated fashion.

map.moveToPosition([48.8644458, 2.3589976],
                    500,
                    {padding: 16, animate: true});

moveToRegion

Similar to the function moveToPosition, the function moveToRegion(region, [options]) takes a region to reposition the camera. The options are the same as in moveToPosition.

map.moveToRegion({
  southWest: [48.8644458, 2.3589976],
  northEast: [48.8821597,2.3856527]
}, {
  padding: 16,
  animate: true
});

Marker

In addition to the map itself we also allow to create and react to interactions with markers.

map.addMarker(new esmaps.Marker({position: [48.8560453, 2.3415578]})
              .on("tap", () => console.log("Tapped on marker")));

What’s next?

In addition to the features controlling the camera we made further improvements like showing and getting the user’s location on a map, showing a button to focus on the user, changing the map type and much more. To get a full look into the available API, check the project’s README. If you have any questions or suggestions please feel free to open issues and provide pull requests.

Moritz Post