We, as developers, likely all started with a “Hello World” app way back when we were young and hungry for code. This widget builds upon the lessons learned in the “Hello World” example.
Ready? Great. Let’s take a deeper dive into building a functional integration.
Surprise. It snowed here in Canada
Winter came a bit early here last week- and as the day was winding down I found myself tabbing over to Google Maps to see exactly how bad the traffic was. Wouldn’t it be great if I could do that right within my digital workplace?
So let’s build an integration widget that gives us a Google Map with the Traffic overlay.
We’ll start out by downloading the Hello World widget template and unzipping it – following the same instructions in the example.
First things first, let’s add our credentials. The credentials.json file takes your Azure account name and your Azure key. You should have received those when you registered for the developer program.
{
"account": "awesomedeveloperaccount",
"key": "800your-api-key==",
"url": "https://your.integration.url/integrations",
"environment": "Sandbox",
"provider": "azure"
}
We’ll then edit package.json and add the widget name, and populate the author and description:
{
"name": "ig-traffic-widget",
"version": "0.0.1",
"description": "",
"main": "deploy.js",
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1"
},
"author": "David Bistolas, Igloo Software",
"license": "ISC",
"dependencies": {
"@igloosoftware/ig-deploy": "^0.4.4"
}
}
Next, we’ll go over to the app directory, and open up the integration.json file. Here we’ll set the version, id, name and description. Remember[GU4] this file, we’re going to come back to it.
{
"version": "0.0.1",
"id": "google-traffic",
"name": "google-traffic",
"description": "Google Maps Traffic Widget",
"vendorName": "@igloosoftware",
"categories": [],
"published": "",
"userConfig": []
}
Now we’re ready to start on the actual integration widget. The widget code itself lives in app/content.html. Most widgets are built with straight HTML and JavaScript.
Google’s APIs are really well documented. We can make their example code work with almost no modifications. The example code below was lifted almost verbatim from Google’s examples page.
Here’s the complete file. Note: I’ve omitted the iframe resizer that’s at the end of this file.
<html>
<head
><meta name="viewport" content="initial-scale=1.0, user-scalable=no" charset="utf-8">
<style>
/* Google says to always set the map height explicitly to define the size of the div
* element that contains the map. */
#map {
height: 550;
}
</style>
</head>
<body> <!-- This is the map DIV, where the map will be displayed -->
<div id="map"></div>
<script>
// This is google's 'initMap' callback. It builds the map, attaches it to the DIV and sets the center and initial zoom.
function initMap() {
var map = new google.maps.Map(document.getElementById('map'), {
zoom: 13,
center: { lat: 88.1234, lng: 123.4567 }
});
var trafficLayer = new google.maps.TrafficLayer();
trafficLayer.setMap(map);
}
</script>
<script src="https://maps.googleapis.com/maps/api/js?key=your_google_api_key&callback=initMap">
</script>
<script data-igloo-iframe-client>
/*! Note: I’ve removed the iframe resizer client code from
this example so it would fit into this blog article. */
</script>
</body></html>
There are three parts to this code: the CSS:
#map {
height: 550;
}
The JavaScript function that initializes the map (initMap):
function initMap() {
var map = new google.maps.Map(document.getElementById('map'),
{ zoom: 13, center: { lat: 88.1234), lng: 123.456} });
var trafficLayer = new google.maps.TrafficLayer();
trafficLayer.setMap(map);
}
And finally, a <div> tag that will host the map itself.
<div id="map"></div>
The JavaScript code loads the google map into the ‘map’ div and implements the traffic Layer.
That’s it. Save the file and execute node deploy.js from the project’s root directory and you’ll have a google maps widget ready to go.
Having the longitude and latitude statically defined in the widget is really only useful to people AT that latitude and longitude. Wouldn’t it be great if we could make that configurable?
We can! If we add this function to our widget:
function createConfiguration() {
if (window.frameElement.getWidgetConfig) {
var config = window.frameElement.getWidgetConfig();
window.widgetConfig = {};
if (config) {
for (key in config) {
window.widgetConfig[key] = config[key].toString();
}
}
return window.widgetConfig;
}
}
We’ll also need to set up the ‘userConfig’ section in our integration.json file. (Told ya we’d come back to it!)
{
"version": "0.0.2”,
"id": "google-traffic",
"name": "google-traffic",
"description": "Google Maps Traffic Widget",
"vendorName": "@igloosoftware",
"categories": [],
"published": "",
"userConfig": [
{
"name": "lat",
"label": "Latitude",
"type": "text",
"default": "43.4499149",
"description": "Enter the latitude to center your map on"
},
{
"name": "lng",
"label": "Longitude",
"type": "text",
"default": "-80.49038",
"description": "Enter the longitude to center your map on"
},
{
"name": "zoom",
"label": "Zoom",
"type": "number",
"default": 13,
"description": "Set your map's inital 'zoom' level."
}
]
}
Finally, we’ll update the initMap() function to use our new config object so it all looks like this:
<script>
// We can access configuration items from within the widget. These are defined in the widget's integration configuration panel.
// This is a rather generic function that will populate all of the configuration items and return it...
function createConfiguration() {
if (window.frameElement.getWidgetConfig) {
var config = window.frameElement.getWidgetConfig();
window.widgetConfig = {};
if (config) {
for (key in config) {
window.widgetConfig[key] = config[key].toString();
}
}
return window.widgetConfig;
}
}
// So we'll assign it to 'config'.
var config = createConfiguration();
// This is google's 'initMap' callback. It builds the map, attaches it to the DIV and sets the center and initial zoom.
function initMap() {
var map = new google.maps.Map(document.getElementById('map'), {
zoom: parseInt(config.zoom),
center: { lat: parseFloat(config.lat), lng: parseFloat(config.lng)}
});
var trafficLayer = new google.maps.TrafficLayer();
trafficLayer.setMap(map);
}
</script>
After running #>node deploy.js, we can add our widget to our site and configure it:
Notice the new fields? Your users can now configure the widget when they install it- so you don’t have to hard-code site specific values. In fact, we could add multiple widgets to the same page and show maps of your different offices.
Here’s what our widget looks like, using our Kitchener Office as the center point in the map:
Looks like traffic has (mostly) cleared here at Igloo HQ- so it’s time to head on home.
There’s lots more we can be doing with this widget. Our next steps should be to add unit testing, documentation, and to minify it.
Additional features we could add would include – a dropdown for preconfigured locations (if your office has multiple sites, for example), geolocation based on your IP or GPS coordinates, a ‘home’ location and show travel times to/from the office, city names as titles…
There are so many possibilities!