I wanted to try out a new widget in Mendix (that one will be a post later on so stay tuned!) that to ensure it performed as I wanted, I needed to show a map on the page in a web app. Historically, I’ve used the Google Maps widget in the Mendix App Store but I noticed Mendix had released a new “Maps” widget and decided to try it out. What I ran into were a number of issues getting it to work so like always I decided to capture my findings for future reference while sharing with all of you, the Mendix Maker Community! If you want to understand a bit more than the documentation explains, this is the place to be!
The Maps Widget
This is pretty straightforward. Inside of your application, navigate to the Mendix App Store (shopping cart icon in the top right of Mendix Studio Pro) and search for Maps. Or navigate here to download and import into your project manually if you so desire. Pay attention to the version number to ensure it is compatible with your project.
Where to put the widget?
The Maps widget is like any other widget for the UI in which you drop it into your page structure. You have two options: Drop it inside of a Data View object to pass in context, or just drop it on the page without context. I’m going to cover using it without context but if you’ve got more than just a minimal understanding of Mendix and using widgets, you should be able to figure out how to use this one with context as well through the menus and I’ll briefly call that out in this write up and how to apply it.
Which Map provider service?
You need to decide which map service your app will use. You can leverage Open Street which is developer friendly and doesn’t have the costs associated that others might in licensing (but only if you plan on making a LOT of map service calls…for basic use all of them are usually without a fee but your mileage will vary). If you decide to use one of the other services such as Google Maps, you will need an Access Token. I will describe how to use Google Maps and that process as it is most likely the choice you will make! Google Maps has really good layers and services that you can fully customize and I personally find it easier to work with for most needs, but I don’t begrudge any other choice either. We’ve built really nice map capabilities using Open street as well so use what fits best for you!
Populating Location Data
When you open the widget, on the Map Properties tab, you have to define where the data will come from for your maps to plot. There are five choices: Static, Context, Database, Microflow, and Nanoflow displayed first as a radio button option.
Hint 1: The choice in the radio button needs to align with the data you provide in the fields below!
This one tripped me up. If you select Context, you must provide an “Input parameter Entity” for example. If you choose Microflow, you must provide a Microflow. Makes sense. But if you choose Database, and provide a Microflow, it will yell at you (errors). Don’t add data that isn’t relevant to your choice as the widget controls don’t handle that. Ideally, it would use display properties to only show or hide the fields based on your selection in the radio buttons, but it doesn’t so keep that in mind!
You really need to use Latitude and Longitude for proper mapping. “But my users don’t know that!” You should be using a separate Geocoding API, you can convert an address into lat long coordinates and use those. It’s how your favorite map app on your phone works. I won’t be covering that but it should be enough to get you started on how to convert readable addresses into lat long positions.
For this example, I created a simple entity that stores a name, a latitude (decimal) and longitude (decimal) and populated a couple of records. I looked up The White House and Washington Monument and got their latitude and longitude positions and keyed them in.
Hint 2: If you want the lat long of an address in Google Maps manually, just right click the marker and select “What’s here?”. A small window will appear at the bottom of the page with the full lat and long position coordinates.
Hint 3: Make sure the precision of your decimal is set to auto or at least seven positions, and make sure your input field is set to the same as the attribute. You might cutoff and round which of course will locate incorrectly on the map!
Back to the widget. In the Data Source, I chose the “Database” option and defined my entity (Map is what I called it), then set the Lat and Long values. For this purpose I did not constrain it as again, anyone who has developed a little bit in Mendix should know how to do those sorts of things. This is about getting Google Maps to run in Mendix with a bit of “styyyyyyyyyyyyyyyle”. ;)
There are others menu tabs in this Locations menu that you can play around with, such as Marker images if you want to override the defaults or images, etc. Maybe I’ll circle back to that in a future post but this will already be quite long so skipping for now.
Once you close the Locations, you can experiment with the other tabs as well. For Google Maps, you can tell the widget whether it can render street view or not and a number of other things. One of those things is the “Map Styles”. We’ll be using that momentarily, mi amigos!
Google Maps Access Token
A quick Google search will tell you how to get your developer token. I’ll save you a few searches and clicks and just have you go here using your Google developer account (nothing special, just know you’ll need a payment method associated). For your developer needs, no need to worry as you won’t use the api calls needed to get charge in terms of volumes, but your company will need their own token with an account because they may get charged if your app exceeds the call limits for free. You’ll need to create a Project for your app, create credentials (API Key) and then copy that access token for use. Google has good documentation about how to do this here. If this seems overwhelming I assure you it isn’t. It takes just a few clicks and ensuring you’ve attached a billing method for the API use and you’re off an running quickly. Again, you can learn how to use Open Street as well for your needs or one of the others if needed.
Once you have the token, be sure to add it to the Maps widget for the map to work. If you run the app and view your data and see a grid watermark, it means it is working correctly but without the payment card associated. You can use this also for your development needs but it does limit what you can do and interaction with the map.
Run your page and view the map!
You’re almost there. Be sure you have data populating and you’ll get a nice interactive view of the map.
But Nolan, I want to kick it up a notch!
Remember when I said I would come back to that property in the Maps widget on the Google Maps tab called “Maps styles”? Here you go and this is why I love Google Maps. Navigate here and have your mind blown with the number of options. You can literally customize everything! In my example, I wanted to have a popup for my locations and I wanted government buildings to show up in bold blue text, while the map is a “retro” style. Click “Finish” and copy/paste the JSON into that “Maps styles” attribute and run your app again.
I ended with a map that looked like this. Just think of the possibilities!
Conclusion
Using the Maps widget is pretty easy…with a guide like this if I do say so myself. You can really get creative with layers, geofencing, routes, and so forth. If you can imagine it, you can likely do it. This even allows for street view which we found useful for a client that needed to lookup business buildings for insurance and financing purposes. Hopefully this guide will help kick-start your Mendix map development needs.
If you like this content, please leave a comment or what I could do better and feel free to use the share options!