In this tutorial you will learn:
- The purpose of a layer group
- How layer groups are organized in the configuration file
- How to add a new layer group object
- Additional properties for customizing a layer group object
To start this tutorial, you need:
- A MapBuilder web application. If you do have one, visit the tutorial Step 2: Create a MapBuilder application in ArcGIS Online
- An understanding of how to edit your configuration file in ArcGIS Online
What is a layer group?
A layer group refers to one or more layers organized in the same section of the left panel in a MapBuilder application. Usually, the layers in a group relate to a similar topic or theme. The screen shot below highlights three of the default layer groups in MapBuilder:
Layer groups 2 and 3 above are collapsed and therefore the layers are not visible for the user to toggle them on.
There are 6 layer groups by default:
- Land Cover Dynamics: Contains layers related to the changing global landscape.
- Custom Layers: Contains layers defined in the ArcGIS web map associated with the application.
- Land Cover: Contains layers related to describing the surface of the earth.
- Climate: Contains layers related to the earth’s climate systems.
- Recent Imagery: Contains one layer related to viewing Sentinel-2 and Landsat 8 satellite imagery.
- Basemap: Contains several basemap layers that appear underneath all other layers.
Layer group organization in the configuration file
All the layer groups in MapBuilder are defined in the layerPanel property in the configuration file. The screenshot below shows a MapBuilder application on the left and the corresponding configuration file on the right.
The layerPanel property is an object that contains other objects and is highlighted in green above. Each object within it represents a single layer group—one of these is highlighted in red above.
How to add a new layer group
1. Define a new layer group object
To add a new layer group, you need to define a new layer object to place in the layerPanel property. At a minimum, the layer group object needs to begin with a unique property key and contain the following properties:
- label: An object that contains translations for the title of your layer group. Each language is defined by a property key and value pair. The key is a two letter ISO code and the value is the corresponding text. Read the GitHub documentation for label objects to see the languages you can define.
- layers: An array of layers that are included in the layer group. Read more about layers here.
Here is an example of the most basic layer group object you could define:
Note that the layer group in the example above does not have any layers specified in the layers property, so it will appear empty in the main MapBuilder panel.
2. Add the new layer group object to the layerPanel object in the configuration file
Type or paste this new layer group object into the existing layerPanel object in the configuration file. You can do this directly in ArcGIS Online, but it is usually easier to edit the configuration file in a text editor, then paste it back into ArcGIS Online. Read more about this process here.
Each layer group object in the layerPanel object is separated by a comma (,). If your configuration file is not saving properly in ArcGIS, make sure that you have a comma separating each layer group.
3. Save your configuration file in ArcGIS Online
After you edit your configuration file to include the new layer group, be sure to save it in ArcGIS Online.
4. Verify your layer group is visible, then add new layers
Read this tutorial to understand how to add layers to you new layer group.
Additional properties for customizing a layer group
There are other useful properties that you can define in your layer group object to customize a layer group:
- order: A numeric value that specifies where the layer group is placed in the MapBuilder application panel. The first (top) position should have the value 0, the second position should have the value 1, and so on.
- groupType: A text value that specifies how the layout of the layer group. There are three options:
- checkbox: This is a default group type with toggles to turn layers on and off. With this group type, more than one layer may be on at a time
- radio: Only one layer may be on at a time within the same group. You may optionally choose to turn this group off when any other radio group is selected.
- nested: This group allows for layers to be grouped further within a layer panel within an existing layer group.
Read about all of the options for customizing a layer group on the MapBuilder GitHub wiki.
Visit the MapBuilder GitHub Wiki to learn about all the available properties you can edit in the Configuration File.
If you need additional assistance, please do not hesitate to contact us.