The final application will be a mobile dashboard view for the employees of our little start-up which they can either take on the road or use at Gelary HQ to plan their work. It will consist of a map and a floating control panel behind a menu button. The map is used to visualise a route, starting from the user's current position along a series of customers, and the traffic situation along the route. The control panel will enable our delivery drivers to search for nearby ice cream shops, display turn-by-turn directions as well as to calculate the best pick-up location for a group of selected customers. The app will also be able to handle order changes: e.g. if a customer cancels or updates his or her position, the route will automatically be recalculated.
What will we learn in this tutorial?
In this first post we'll setup our work environment and acquire credentials for the HERE APIs. Once everything is up and running we'll learn how to render a basic map view, control the map's basic functionality through code and how to place a marker with a custom icon.
Acquiring credentials for the HERE API
The very first thing we need is to create a HERE account and register our application — no worries, this will just take a moment. Our 90-day free trial will do nicely for this tutorial (and a lot more). After signing up for our account we create a new application and select a name for it. Once that's done, we'll receive two important pieces of information: An "app ID" and an "app code". (You can always looks these up in your account.)
Setting up the skeleton of our app
Once we are all done registering our application, we can finally get our hands dirty and start building our app. (By the way, all the source code is available on GitHub to follow along easily.
|File(s) ||Description |
|mapsjs-core.js ||Core API, provides core functionality for rendering maps, map layers and map objects. |
|mapsjs-service.js ||Provides tile retrieval, routing and geocoding. |
|mapsjs-mapevents.js ||Provides functionality for user interaction. |
|mapsjs-ui.js + mapsjs-ui.css ||Provides user interface for e.g. map settings, zooming and so on. |
In the <body> tag we then add a container for the map — a <div> tag — into which the map will be embedded.
Displaying a basic map
Once you open index.html in your browser you will notice that so far we're stuck with an empty white page — let's change that! We proceed by creating a folder called scripts and a file app.js inside this folder. We then add the code to initialise our map to this file:
Let's also make sure that the map reacts properly when the window is resized. For this purpose we add the following event listener below our map initialisation.
Going further, we include the newly created file in our index.html just before the closing </body> tag:
In order to control the visual appearance of the map, let's also add a dash of CSS. Go ahead and create a folder styles and a file main.css with the following content inside this folder:
This piece of code will ensure that the map always fills the viewport completely.
Now go and refresh your browser window and you should see your beautiful map. Well done!
Interacting with the map
While certainly pretty, our map is frankly not very useful yet. Furthermore, the map center seems fairly randomly selected and zooming in or out is not possible either.
Let's add some interactivity by enabling the event system. In order to do so, add following line just after the initialization of the map inside scripts/app.js.
And that's it. Now we can at least move around the map as well as zoom in and out.
Let's adjust the center point of the map and the initial zoom level of the map as well. This can be done by passing a options object to the constructor H.Map when initialising the map.
Alright, things are starting to shape up nicely!
Pro tip: You can set the map's center pointer and zoom level using map.setCenter and map.setZoom methods at any point in your code.
Adding markers to the map
In the future we will want to highlight locations such as customers or deliveries on the map using place markers. This is easily done using HERE maps. All we have to do is instantiate a new Marker object by passing in the appropriate coordinates and calling map.addObject. Let's try it in our scripts/app.js file:
After refreshing the browser window you should see a marker marking in the middle of the map.
Pro tip: While map.addObject adds new markers, you can remove them again using map.removeObject.
Custom icons for markers
Gelary's designers have done an amazing job with the user interface, but they want us to display customer marker icons. As it turns out, that's not a problem. The Marker constructor takes an options object as a second argument. This allows us to define a custom icon, using the H.map.Icon class:
For now we have set up a very basic interactive map sporting a marker with a custom icon. This work will be the foundation of our amazing ice cream delivery platform.
In the next post we are going to integrate with the browser's geolocation API to keep the delivery drivers updated. Stay tuned!