JavaScript – Esri South Africa Blog

Welcome to the information age! We are part of a lucky generation to be living in a time of great technological change. All around us, data and information about the world is being collected and collated, just waiting for someone to take advantage of it. Based on a recent demonstration we provided to a group of enthusiastic startups, this blog post looks at how to pull in some publicly available data via web services into a basic ArcGIS web app. We are going to use the Public transport data for emerging cities from wheresmytransport through a simple Restful web service.

We will build a basic web (but mobile-ready) app that locates the user and identifies the 10 nearest public transport stops and shows them on a map.

So, where do we begin? With the map of course!

1. Create a web app stub

Open a new project/page in your favourite web development IDE (I still just use notepad++) and create a basic framework for an app. We will pull in the ArcGIS JSAPI and related CSS, a simple HTML structure with some associated CSS classes for controlling how the app will look.

<!DOCTYPE html>
<head>
<title>Find My Nearest Transport Stops</title>
<!-- GET ESRI JAVASCRIPT API AND RELEVANT STYLE SHEET -->
<link rel="stylesheet" href="https://js.arcgis.com/4.4/esri/css/main.css">
<script src="https://js.arcgis.com/4.4/"></script>
<style>
#wrapper {
	position: absolute; 
	top: 0; left: 0; right: 0; bottom: 0; 
	background-color: rgb(237,242,245); 
	overflow: hidden;
}
#map {
	position: relative;
	width: 100%;
	height: 100%;
}
</style>
</head>

<body>
<div id="wrapper">
	<div id="map"></div>
</div>
</body>
</html>

You wont see much when opening this, but here is a tip for how I view and debug my “mobile-ready” apps – open Chrome Developer tools (F12) and toggle the device toolbar. Dock the dev tools window to the right and choose an appropriate mobile device from the drop-down. You can now easily view your app and follow the console alongside.

2. Add a map control

Using the JSAPI that has been loaded, follow the basic steps for creating a WebMap from an ArcGIS Online web map ID, add it to a MapView and assign it to the dom node you just created called “map”. Place the following code inside a script tag in the document header.

require(["esri/views/MapView","esri/WebMap","dojo/dom","dojo/domReady!"], 
	function(MapView, WebMap, dom) {	
		var webMapID = "d46eaef12c0a4864aec85c8708446f00"; // replace with your web map's ID
		
        // create web map from existing web map ID on ArcGIS Online
		var map = new WebMap({
			portalItem: {
				id: webMapID
			}
		});	
		console.log("Loading map: " + webMapID);

		// add the web map view and hitch to a dom node
		var view = new MapView({
			container: "map",
			map: map
		});
			
		// wait for map to be loaded
		view.then(function(){
			console.log("...Map resources have been loaded successfully.");				
		}, function(error){
			// Use the errback function to handle when the view doesn't load properly
			console.log("The view's resources failed to load: ", error);
		});
	}
);

If you are using the Chrome Developer tip I mentioned, you should see something like this.
Web App - Step 2

3. Add “find me” button
HTML5 provides a handy geolocation API for getting the user’s location based on the best available method on the device. Esri has packaged this method into a simple widget that makes it easy to add to a map. Note that in v4.x of the JSAPI you can now add items to the “ui” of the map using the “view.ui” properties. To add the widget, insert the following code into the main function that will load the widget, add it to the UI and set up a handler that zooms and centres the map to your coordinates.

function addMyLocationButton() {
	console.log("Adding my location button.");
	var gl = new GraphicsLayer();
	map.add(gl);

	var locateWidget = new Locate({
	  view: view,   // Attaches the Locate button to the view
	  graphicsLayer: gl,  // The layer the locate graphic is assigned to
	  goToLocationEnabled: false	// override this to control the zoom level on goto
	});
	view.ui.add(locateWidget, "top-right");
	locateWidget.on("locate", function(event){
		// event is the event handle returned after the event fires.
		console.log("Located your position at: " + event.position.coords.latitude + ", " + event.position.coords.longitude);
		console.log("Taking you there now.");
		view.center = new Point({x: event.position.coords.longitude, y: event.position.coords.latitude, spatialReference: 4326});
		view.zoom = 13; 
	});
}

TIP: don’t forget to add the new requires: “esri/widgets/Locate”,”esri/layers/GraphicsLayer”

And, then call the new function once the map has loaded (i.e. within the “view.then(function(){“ function).

addMyLocationButton();

Your output should look a little like this after clicking the new button:
Web App - Step 3

4. Get stops from wheresmytransport
First, I recommend going to check out wheresmytransport.com and read up on their cool data service that provides real-time access to consolidated public transport information in many major global cities (including Joburg and Cape Town). Use of their API is free if you sign up as a developer here: https://developer.whereismytransport.com/ – you will need to do this to get a client id and secret to run the app.
Now, we will add a new button that will call the service by adding the following code into your main function:

view.ui.add({
	component: "stopsButton",
	position: "bottom-right",
	index: 0
});
console.log("Get stops button added to the UI");

And add a dom node to host the new button to the HTML body:

<div id="stopsButton" class="esri-widget-button esri-widget esri-interactive" role="button" tabindex="4" title="Get stops">
		<span class="esri-icon esri-icon-map-pin" role="presentation" aria-hidden="true"></span><span class="esri-icon-font-fallback-text">Get stops</span>
</div>

Now that we have a button, let’s listen for it’s click event and then call the wheresmytransport service – by adding this code to the main function:

setTimeout(function () { // short delay to wait for the ui element to be loaded into the DOM, then attach an event listener for the click event
		
	document.getElementById("stopsButton").addEventListener("click", function(){
		console.log("Get Stops button clicked.");		
	});
}, 100);

Now, before you can use the wheresmytransport service, you need to request a security token. Add this code into the function you just created.

// get API token						
	console.log("Getting WMT secure token...");
	var CLIENT_ID = 'enter your client ID here from the developer portal';
	var CLIENT_SECRET = 'enter your client secret here from the developer portal';
	var payload = {
		"client_id": CLIENT_ID,
		"client_secret": CLIENT_SECRET,
		"grant_type": "client_credentials",
		"scope": "transportapi:all"
	};

	var request = new XMLHttpRequest();
	request.open('POST', 'https://identity.whereismytransport.com/connect/token', true);
	request.setRequestHeader('Accept', 'application/json');
	request.onreadystatechange = function () {
		if (request.readyState == 4 && request.status == 200) {
			var response = JSON.parse(request.responseText);
			//console.log('WMT token: ', response.access_token);
			console.log('...WMT token created successfully.');
			var token = response.access_token;
			localStorage.setItem('token', token);
		
			// now, with the token, go get the nearest stops
			getStops(token);	

			// and log the request
			//logRequest(view.center);
		}
	};

	var formData = new FormData();
	for (var key in payload) {
		formData.append(key, payload[key]);
	}
	request.send(formData);

You will notice that the successful callback runs a new function called “getStops(token)” to which it passes that new token. The getStops function looks like this.

function getStops(theToken) {
	console.log("Loading stops from wheresmytransport...");		
	var payload = {
		"point": view.center.latitude +","+ view.center.longitude,
		"radius": 1000
	};
		
	// convert the payload into url parameters
	var payloadParams = Object.keys(payload).map(function(key) { return key + '=' + payload[key]; }).join('&');
	var getLocalStops = getWMTdata('stops', payloadParams, theToken);		
}

This code only sends the request, now we need to handle the response by adding “then” and “catch” callbacks for the promise variable we created called “getLocalStops”. This code will process the results by creating a new Esri graphic and adding to the graphics layer with the specified symbology.

getLocalStops.then((successMessage) => {
	var theStops = JSON.parse(successMessage);
	console.log("..." + theStops.length + " stops successfully loaded.");
	console.log("Now creating map features.");
				
	graphicsLayer = new GraphicsLayer();
	var stopSymbol = new SimpleMarkerSymbol({
		style: "circle",
		color: "yellow",
		size: "8px",  // pixels
		outline: {  // autocasts as esri/symbols/SimpleLineSymbol
		color: [ 255, 255, 0 ],
			width: 1  // points
		}
	});
				
	theStops.forEach(function(stop, i){
		// create a new graphic object for each result (stop)
		graphicsLayer.graphics.add(new Graphic({
			geometry: new Point({x: stop.geometry.coordinates[0], y: stop.geometry.coordinates[1], spatialReference: 4326}),
			symbol: stopSymbol,
			attributes: {
				name: stop.name,
				modes: stop.modes.toString(),
				agency: stop.agency.name
			}
		}));
	});
	// now add the graphics layer to the map			
	map.add(graphicsLayer);
				
});
getLocalStops.catch((errorMessage) => {
	console.log(errorMessage);
});

TIP: Remember to add the new requires “esri/symbols/SimpleMarkerSymbol”, “esri/Graphic” and “esri/geometry/Point”

Finally, for the eagle-eyed among you, there is a utility function called from within the code called “getWMTdata” that takes the url, token and payload which you can use generically for calls to those services.

function getWMTdata (url, payload, token) {	
	return new Promise((resolve, reject) => {
		var request = new XMLHttpRequest();
		request.open('GET', 'https://platform.whereismytransport.com/api/' + url + "?" + payload, true);
		request.setRequestHeader('Accept', 'application/json');
		request.setRequestHeader('Authorization', 'Bearer ' + token);
			
		request.onload = () => resolve(request.responseText);
		request.onerror = () => reject(request.statusText);
		request.send(null);
	});		
}

That’s it. Run the app and after clicking both the “Locate Me” and the “Get Stops” button, your app should look a little like this:
Web App - Step 4

5. Take it further…
This is a basic example, but think about how you can take this app further, by adding capabilities such as:

Finding the nearest stop based on travel distance/time using the FindNearest method from ArcGIS
Display results back to the user in a table or list for easy viewing
Log requests made by users to be able to assess where the demand for the app is…
Many many more!!

If you would like to try out the sample code, you can download this example here. Let me know in the comments below if you want some more info/help!

Happy app-making

– Richard

jsapi We all know that ArcGIS comes with a very large number of out of the box apps that seemingly do just about everything! Surprisingly though, we often come across the problem of finding an app that “fits just right” with what you need to achieve. The solution to this is to build your own app using an API or Runtime. The beauty of the ArcGIS APIs and Runtimes is that they extend the platform – meaning you can leverage all the power of ArcGIS such as Server, map services, web maps, popups, geoprocessing, etc all in a front-end that suits your workflow, user needs and styling choices. This may seem daunting, but don’t be fooled, anyone can do it!

This post will take you through some basic steps to create your own custom web application using a 3D scene. We will use the ArcGIS JavaScript API 4.0 to make the app.

1. Getting started – setting up your environment

Like I said, this is really simple. There are only two things you need. Firstly, you will need an ArcGIS Online subscription to make a web scene that we will load into our custom app

Secondly, you will need is a JavaScript IDE (editor) such as Notepad++ or WebStorm (link).

And that’s it, we are ready to go!

2. Creating the web scene

Log in to your ArcGIS Online account and click the menu option entitled “Scene”. This is a familiar interface very similar to the “Map” tool that lets you other webmaps. Use this tool to create a web scene with your own data layers, popups and symbology. In my example, I have added the provinces of South Africa as a layer and extruded them to show some 3D.

blog1 — Creating a web scene in ArcGIS Online

Make sure to save the scene when you are done and take note (copy into notepad) of the item id for the web scene. You can grab this from the address bar in your browser. My id is “0390e2ec01fa488a847d4e413f015cd0”.

Note that to make things easier, you can share your web scene publically. This will avoid your app needing to authenticate you when opening it (i.e. logging in). In future, you can add security to your app as required.

More info on how to create a web scene, go to this link.

3. Creating your web page structure

Open up a new, empty html file in your IDE of choice. We will first put in the basic structure of the HTML page to get us going (TIP: I have created myself a template that I can re-use as a starting point each time I want to create a new app – saving me the time of creating the structure). An HTML page consists of some mandatory sections:

HTML doctype declaration – so that a web browser knows that the page is an HTML file (and what version – we are using 5)
Head – this includes all necessary ‘meatadata’ for the web page including the styling and logic (javascript)
- Title – be sure to set a readbale title that you will see on your browser tab
- CSS – this is the styling file and its easiest to pull in the CDN hosted Esri stylesheet
- Javascript libraries – this is the ‘core’ JS library that will enable all kinds of web mapping goodness, we will pull in the CDN hosted JSAPI from Esri (link)
- Javascript – this is the logic of your won app, here will enter our code to load a scene view and any other logic we want from the page
Body – this is the HTML which provides the structure of the page using HTML tags (link)

Here is my basic skeleton template including the links to the CDN CSS and JavaScript libraries that make up the ArcGIS JavaScript API (v4.0):

<!DOCTYPE html>
<html>
<head>

<title>My First 3D Web App</title>

<link rel="stylesheet" href="https://js.arcgis.com/4.0/esri/css/main.css">
<script src="https://js.arcgis.com/4.0/"></script>

<script>
/* section for my custom code */

</script>

<body>
<!-- page layout will go here --> 

</body>
</html>

More info on creating HTML pages, go to this link.

4. Building the HTML page structure

Before we can add a map (or other elements) to the UI, we need to create the structure of the page itself. Now, there are many ways to skin this cat which I wont go into in this post, but I am going to use a couple of layers (“DIV”s in HTML parlance) to layout my page. This is where you can really start to have fun – since you are in full control of everything, you can choose layout, colours, fonts, graphics, etc to make you page look great!

Here is the HTML layout code that is inserted into the “body” section:

<div id="wrapper" style="position: absolute; top: 0; bottom: 0; left: 0; right: 0; background-color: rgb(200,200,200)">

  <div id="mapPanel" style="position: relative; float: left; width: 60%; height: 100%">
  </div>

  <div id="mapDescription" style="position: relative; float: left; width: 40%; height: 100%; background-color: rgb(220,220,220)">
    <p style="margin: 10px; font: normal 10pt verdana;">Welcome to my very first 3D web app! You can click around and navigate the scene.</p>
  </div>

</div>

5. Adding the JavaScript “Scene View”

Since v4.0 of the ArcGIS JavaScript API, Esri now uses a new pattern for adding maps to the view. This is done by first creating the map (which is a container) and then adding a view to that map.

Here is the code for loading my map which is inserted directly into the <script> section:

require([
  "esri/views/SceneView",
  "esri/WebScene",
  "dojo/domReady!"
], function(SceneView, WebScene) {

  var scene = new WebScene({
    portalItem: {
      id: "0390e2ec01fa488a847d4e413f015cd0" // replace with your web scene's ID
    }
  });

  var view = new SceneView({
    container: "mapPanel",
    map: scene
  });

});

Note that I have entered the Item ID from the web scene I created earlier as the reference. This means that the logic will now create a scene container, find the scene item by its id and load that into the scene as a view. Too easy!

More info on the ArcGIS JavaScript API, go to this link.

6. Revel in your mastery

And that’s it! You have created your first 3D web app. To view it, simply open the HTML page in your favourite browser (JSAPI v4.0 is supported in Chrome, Firefox, and IE 11).

Here is a screenshot of my first app: