Skip to main content

Building an ArcGIS Web App, Part 2: Creating a simplified layer switcher

It’s always helpful to keep your users’ needs in mind while developing an app so that you know what tools you need to include for them to complete their tasks. However, your users’ needs can also help you make decisions while designing the app’s interface – particularly if you keep in mind things that we as GIS users take for granted, like turning layers on and off in the map. If you are using out-of-the-box tools, you may not have a lot of control over the interface design but sometimes you can make small changes to the JSON that will greatly improve the user experience.

When you’re designing an app, how do you decide what sort of functionality to include, and how the functionality should be presented on screen? If you’re using one of Esri’s Web app templates or app builders, some of these decisions are taken care of for you already or you may have a limited number of options, such as where to place a tool and panel content. However, it’s still useful to step back and consider exactly what your users need to accomplish using the app and what that means for the app design.

A few questions you might ask are: What do your users ultimately need to learn from your data? What do they need to visualize, edit, or analyze? Why do they need to do these things? Or, in a phrase commonly used in user-experience design, what are your users’ “jobs to be done”? Questions like these help you focus on creating a design that matches how your users need to use the app – so that the app is designed to fit your users’ workflows, rather than the other way around.

In the previous post in this two-part blog post, my colleague Anastassios Dardas described an app that our group developed as part of a research collaboration with the Collaborative for Advanced Landscape Planning (CALP) at the University of British Columbia. One component of the CALP Energy Explorer (CEE) is an app that allows users to visualize three different energy-use metrics – greenhouse gas emissions, greenhouse gas emissions intensity, and energy use intensity – for properties in the City of Vancouver. However, we found some usability issues in the app with using a regular layer list to turn map layers on and off, so we created our own “layer switcher” that more closely matched how the layers in the app are structured.

When an ordinary layer list just won’t do

The Web map for the CEE app uses two layers for each energy metric. One is a feature layer that appears when the user zooms in to roughly the neighbourhood level (1:20,000), and the other is a tile layer that appears when the user zooms out beyond this. Using pre-rendered tiles when zoomed out allows a very large number of features to be displayed quickly, while using a feature layer when zoomed in allows you to avoid having to generate and store a large number of tiles. This method is described in more detail in a blog post by Kelly Gerrow-Wilcox at Esri, Inc.

The problem with having two layers for each metric in this case was that if we used a regular Layer List widget in the ArcGIS Web AppBuilder, users would have to turn the individual feature layers and tile layers on and off manually each time they wanted to switch between the energy metrics. This amounts to not a great user experience, and it could get tedious pretty quickly. It could also get confusing – for example, if the user didn’t have any of the tile layers turned on, and then zoomed out far enough on the map, the map would be empty with only the basemap visible.

Screenshot of a Web AppBuilder app with the Layer List widget opened. The Layer List contains separate tile layers and feature layers for each of the three energy metrics.

Example of the default Layer List widget in the Web AppBuilder with the Greenhouse Gases metric displayed. Note that since we’re zoomed in relatively close, the tile layer is disabled (even though it’s toggled on), and the map displays the feature layer instead.

If we had used the ArcGIS Experience Builder and the new ArcGIS Online Map Viewer to build the app, we could have created group layers in our map to group together the tile layer and feature layer for each metric, so the users could turn these on and off as a group. But even this isn’t ideal, since users could still expand the groups and turn the individual layers on and off, and find themselves in the same position of having an empty map when they zoomed out.

Screenshot of group layers in the new ArcGIS Online Map Viewer, where the tile and feature layer for each of the energy metrics are grouped together so that both of these layers can be turned on and off at the same time. On the left side of the image, the groups are collapsed, while on the right side, the groups are expanded to show the layers within each group.

Example of using group layers in the new ArcGIS Online Map Viewer, with the GHGi and EUI groups turned off. In this example, we’re zoomed out on the map and only the tile layers are visible.

One final consideration is that a layer list allows users to turn any combination of layers on and off, which isn’t helpful in our case. Since our layers show the energy usage for each land parcel in Vancouver, all of the layers completely overlap with each other – so if the user turns a layer on without turning a layer off that is above it, they might not see any changes in the map, which could also be confusing.

Thinking about user needs and UI complexity

In user-interface design, one key idea, as described by Alan Cooper in an article in Technical Communication, is the difference between the program’s “implementation model” and the user’s “mental model”. This refers to the difference between how everything is implemented “behind the scenes” to build the app, versus how the user understands the app’s functionality and how they expect to be able to use it. Given how complex the implementation of an app might be, it’s helpful to design the UI in a way that doesn’t force the user to deal with the complexity if they don’t need to.

In the case of the CEE app, having separate tile and feature layers for each of the energy metrics is part of our app’s implementation model, something we did to improve the performance – but in and of itself, this isn’t something that the end users need to know about, and having all these layers also makes the interface more complex. And in a larger sense, if we’re presenting the user with these energy metrics, wouldn’t it make more sense to design the interface around the metrics, rather than around the underlying data layers?

We can also think about this in terms of the idea of “jobs to be done”. The users of this CEE app don’t need a completely open-ended way to work with the GIS layers – instead, they just need a tool to help them learn more about energy usage across the city, or maybe for their own neighbourhood or dwelling. The GIS layers serve this larger purpose, rather than being the focus of the interaction.

The Solution

For our project, we found a solution to the issues described above using the Web AppBuilder’s Bookmark widget. This widget is normally used to provide a set of predefined map extents that users can navigate to quickly, but what makes it really useful for the CEE app is that you can also specify which map layers should be turned on and off for each bookmark. So, we can have one bookmark for each energy metric, which would turn on only those two layers and would turn off all of the other layers.

However, there is one problem with this approach. Namely, bookmarks navigate the user to a different map extent, which we don’t need. There’s no way to disable this within the Web AppBuilder interface, but there’s a hidden option in the Web AppBuilder app’s JSON code that allows it to ignore the extents! All Web AppBuilder apps (as well as other Esri app templates and app builders) store the app’s configuration in a JSON file that can be edited outside of the main app editor. So, with an appropriate modification, we can create bookmarks with set map extents using the Web AppBuilder Bookmark widget, and then modify the JSON file afterwards to ignore the map extents.

You can make these modifications using the instructions in this document.

The result: a widget that allows users to switch between the themes of data we wanted to show them, without having to handle the GIS layers that are used behind the scenes! The bookmark buttons also serve as nice, big, visual “click targets”, compared to regular checkboxes or radio buttons.

Animated screenshot of the finished app, showing how the user can use the new widget to switch between map layers without the map extent also changing at the same time

The steps in the PDF above will help you create a custom layer switcher, but there are a few other things to be aware of:

  • If you make any changes to the Bookmark widget later on in the Web AppBuilder, you may need to redo the JSON changes.
  • To keep things consistent between the map and the bookmarks, make sure that the layers that are turned on by default in your Web map match one of the bookmarks you created.
  • Unlike the checkboxes in a layer list that show which layers are enabled, the Bookmark widget doesn’t indicate which bookmark is being viewed at any given time. This is a particular issue if the user has opened the map but hasn’t selected a bookmark yet, since they may not know which layers loaded by default. One way to work around this is to create a thumbnail image for each bookmark that represents the bookmark’s contents. In the CEE app, each thumbnail used an icon with colours similar to the layers’ symbology, but we realized afterwards that a better solution would be for each thumbnail to use a screenshot of the map layer(s) that it displays, like in the screenshot below. With any user-interface design project, there will be issues that you don’t notice until you and your users actually start to use the app.

Screenshot of a different Bookmark widget design, where each bookmark’s thumbnail is a screenshot showing how the map would look after switching to the bookmark

  • This layer switcher might not be appropriate if the end users of your app need to be able to choose a custom combination of layers to view on the map. In the case of the CEE app, this wasn’t necessary, and, in fact, was something we were trying not to allow. Remember, in this context, the words of Bill Buxton at Microsoft Research, “Everything is best for something and worst for something else. The trick is knowing what is what, for what, when, for whom, where, and most importantly, why.”
  • You can use a similar JSON modification if you’re using the Experience Builder instead of the Web AppBuilder! The Experience Builder doesn’t have an “isSaveExtent” property to change, but you can remove the “extent” and “viewpoint” code blocks for each bookmark to accomplish the same thing.


In this blog post, we looked at a Web AppBuilder app where we wanted users to switch between pairs of layers. A regular layer list would require users to toggle between too many layers manually, so we re-thought how these layers could be presented to the user. We used the Bookmark widget to create a bookmark for each set of layers, and we disabled the map extent for each bookmark so that clicking the bookmark would change only the layer selection and not the map extent.

Even if you’re using an “out-of-the-box” app template, it’s still possible to “think outside the box” and “modify within the box” a bit with your app design. Stay tuned for more blog posts with user-interface design tips for Esri’s app templates and app builders, and check out the User-Interface Design learning path available on our Higher Education Resource Finder.

This post was translated to French and can be viewed here.

About the Author

Jonathan Van Dusen is a Higher Education Specialist in the Education and Research group at Esri Canada. He develops learning resources and workshops for university and college students, provides assistance with app development and user-interface design for higher-education research projects and leads training sessions at the annual Indigenous Mapping Workshop. Jonathan completed a Bachelor of Environmental Studies with a Computer Science minor at the University of Waterloo, and also has a certificate in User Experience Design from the University of Toronto. A lifelong fan of maps, geography and technology, Jonathan is passionate about combining these through GIS to help solve current social and environmental challenges, as well as designing technology appropriately to meet user needs.

Profile Photo of Jonathan Van Dusen