If you use ESRI’s Javascript API to build web maps you have probably noticed that your ability to manage base map layers is somewhat limited. You really only have three out-of-the-box alternatives:
- Define an ArcGIS.com basemap in the map constructor
- Create and fill a Basemap Gallery
- Switch between two basemaps with Basemap Toggle
But what if you don’t want to use an ArcGIS.com basemap, you want to use something other than thumbnail images to switch between basemaps or you have more than two basemaps to switch between? In that case, you probably need something a little more flexible.
I recently found myself in one of those situations. I wanted to be able to switch between a vector basemap and a basemap of current imagery as well as give viewers the opportunity to choose imagery as far back as the 1930s. I really didn’t want to show thumbnails for every year of imagery. Instead, it seemed to make more sense to allow selection by year from a drop down menu.
So I went ahead and built my own little version of a basemap switcher to handle different situations. To be fair, I could have used the ESRI Basemap Toggle dijit to handle the two main basemaps but I like having more control over my code than Dojo based dijits allow.
I put together a simple map to demonstrate switching multiple basemaps through various means like buttons, thumbnails and drop downs. The html markup and CSS styling is pretty basic. We create a header as a toolbar (in this case our switcher is the only tool), a div for the map to be injected and markup for the the jQuery UI dialog box that will hold our switching controls.
Edit: FC Basson’s comment got me thinking about the code samples here being too complicated for what they were actually doing. I went back through and removed the toolbar and all jQuery UI and jQuery code. None of these added anything special to the app and since Dojo is already available to us, it should be used instead
<!doctype html>
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=7, IE=9, IE=10">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="apple-mobile-web-app-capable" content="yes">
<meta name="apple-mobile-web-app-status-bar-style" content="translucent-black">
<title>Custom Basemap Switcher</title>
<script src="http://js.arcgis.com/3.7/"></script>
<link rel="stylesheet" href="http://js.arcgis.com/3.7/js/dojo/dijit/themes/nihilo/nihilo.css">
<link rel="stylesheet" href="http://js.arcgis.com/3.7/js/esri/css/esri.css">
<style>
html, body, #map
{
height: 100%;
width: 100%;
margin: 0;
padding: 0;
overflow: hidden;
}
#map
{
position: fixed;
}
#basemapButton
{
position: absolute;
top: 25px;
left: 70px;
z-index: 100;
}
button
{
border-radius: 4px;
background-color: #F1F1F1;
font-size: 1em;
color: #33A7DE;
}
#basemapDialog
{
background: white;
display: none;
font-size: 0.75em;
height: 200px;
left: 65px;
position: absolute;
top: 70px;
width: 300px;
border: 0.5px solid black;
border-radius: 5px;
}
#basemapDialog ul, li
{
list-style: none;
margin-top: 1em;
}
a img
{
border: 1px solid black;
}
a:hover img
{
border: 1px solid white;
}
</style>
</head>
<body class="container tundra">
<button id="basemapButton" title="Open a basemap switching dialog">Switch Basemaps</button>
<div id="map"></div>
<div id="basemapDialog" title="Choose a Basemap">
<ul>
<li>
<button id="wldImagery" title="Load the World Imagery layer as a basemap using this button">Imagery</button> Select by button</li>
<li><a id="streetView">
<img title="You can use an image thumbnail like this one to select a basemap" src="http://ryanrandom.com/examples/images/vegas.jpg" alt="Street Map View" height="50" width="50" />
</a> Select by thumbnail</li>
<li id="differentBase" title="View historical imagery as a basemap">
<select name="bmSelect" id="bmSelect" title="Selecting a basemap from a dropdown is handy when you have many choices, like historical basemaps">
<option value="none" selected>None Selected</option>
<option value="topo">Topo</option>
<option value="relief">Shaded Relief</option>
</select> Select by dropdown
</li>
</ul>
</div>
</body>
</html>
The code needed to run the switcher isn’t too complex either. You just need to create an ESRI Javascript map reference, create variable references to the basemaps you want to use then create a function that does the actual changing of the layers. The rest of the code is just some jQuery Dojo/JavaScript to interact with the controls.
<script>
require([
"esri/map",
"esri/layers/ArcGISTiledMapServiceLayer",
"esri/geometry/Extent",
"dojo/dom",
"dojo/dom-attr",
"dojo/dom-prop",
"dojo/on",
"dojo/query",
"dojo/NodeList-traverse"
], function (
Map, ArcGISTiledMapServiceLayer, Extent, dom, domAttr, domProp, on, query
) {
//We can set an extent like this one which takes us to Las Vegas, NV
var initialExtent = new Extent(-115.68, 35.77, -114.75, 36.45);
//Create an empty array to store a reference to the currently selected basemap layer
currentBasemap = []
map = new Map("map", {
extent: initialExtent,
logo: false,
slider: true
});
//create references to all of your basemap layers but only add one to the map initially
imagery = new ArcGISTiledMapServiceLayer("http://services.arcgisonline.com/ArcGIS/rest/services/World_Imagery/MapServer");
//add the current basemap layer to the currentBasemap array so you can keep track of what is active.
currentBasemap.push(imagery);
map.addLayer(imagery);
//call reorderLayer on the map object and set your basemap to zero every time you change basemaps. This ensures that your basemap is always the bottom layer.
map.reorderLayer(imagery, 0);
street = new ArcGISTiledMapServiceLayer("http://services.arcgisonline.com/ArcGIS/rest/services/World_Street_Map/MapServer");
topo = new ArcGISTiledMapServiceLayer("http://services.arcgisonline.com/ArcGIS/rest/services/World_Topo_Map/MapServer");
relief = new ArcGISTiledMapServiceLayer("http://services.arcgisonline.com/ArcGIS/rest/services/World_Shaded_Relief/MapServer");
//Opens and closes the basemap dialog using the basemaps button
on(dom.byId("basemapButton"), "click", function () {
if (!(dom.byId("basemapDialog").style.display == 'block')) {
dom.byId("basemapDialog").style.display = "block";
} else {
dom.byId("basemapDialog").style.display = 'none';
}
});
//This function does just what its name says and changes the layer
function changeLayer(layerName) {
map.removeLayer(currentBasemap[0])
currentBasemap.length = 0;
currentBasemap.push(layerName)
map.addLayer(layerName)
map.reorderLayer(layerName, 0);
}
//Here is where we switch the basemap using a button
on(dom.byId("streetView"), "click", function () {
domProp.set(query("#differentBase option")[0], "selected", true);
changeLayer(street)
});
//Here is where we switch the basemap using a thumbnail image
on(dom.byId("wldImagery"), "click", function () {
domProp.set(query("#differentBase option")[0], "selected", true);
changeLayer(imagery)
});
//Here is the code for handling changing your basemap based on a html select box dropdown.
dom.byId("bmSelect").onchange = function () {
var newBasemap = dom.byId("bmSelect").value
//Default to the imagery basemap if "none Selected" is the choice in the dropdown
if (newBasemap === "none") {
changeLayer(imagery)
} else {
//The following allows you to map the dropdown values with an object reference to the tiled service layers created above
var bmList = ({
"topo": topo, "relief": relief
})
//Find the selected basemap in the array above and use the associated object to add the selected theme layer to the map
for (var x in bmList) {
if (x === newBasemap) {
changeLayer(bmList[x])
}
}
}
}
});
</script>
You will notice in the code above that we have create an empty array called currentBasemap. This array is the key to making the tool work. We store a reference to the currently loaded basemap here. That way we can access it, remove it’s corresponding basemap and load a reference to whatever new basemap that we want to display.
That’s all there is to it. You can get the full code from GitHub. You can also view a working example of the code.
Let me know if you have any suggestions on how to make it better.
Thanks for the tips – I’ve implemented a simpler version of your example. I agree that the standard API methods are a bit limiting.