Explore Arcade expressions in a web map

Maps have always been powerful tools for understanding our world. Today, however, maps have even greater potential, thanks to interactivity. Interactive maps and apps can store and convey far more data and experiences than the static maps of the past. The ability to zoom in, open pop-ups, control what is visible on the map, and change how it is visualized aren't just extra tools available to the map reader; they are new dimensions in mapping. A single interactive map can now do the job of many static maps at once.

In this tutorial series, you'll explore four interactive maps and apps and learn how they surpass the traditional understanding of cartography. In this tutorial, you'll explore some of the ways ArcGIS Arcade can be used to enhance interactive maps. Arcade is a scripting language for creating custom content in ArcGIS applications. You can use it to perform mathematical calculations, format text, and evaluate logical statements. Unlike other scripting languages, Arcade can manipulate feature and geometry types used in mapping. Arcade can make your data more flexible and prevent you from having to change its structure or schema.

This tutorial was last tested on January 26, 2024.

Requirements

Explore Arcade expressions in a web map

Explore Arcade labels

Web GIS allows you to share, borrow, and repurpose data from diverse sources. You are no longer limited to the data that your organization collects and maintains. However, data from other sources is often formatted in ways that don’t suit your particular needs. ArcGIS Arcade allows you to adapt other people’s data and make it suitable for your visualization and storytelling. It frees you from the constraints of how the data is structured.

You’ll start this tutorial by exploring an example of Arcade used to format map labels from a date field.

1. Open the Anti-Shipping Activity Messages app.

   The symbols on this map represent hostile acts against ships and mariners, also known as piracy. This data was created by the National Geospatial-Intelligence Agency (NGA) and the ArcGIS Living Atlas of the World team at Esri.

   Note:

   To learn more about the data, click the Info button below the navigation controls on the map.

   

2. Zoom and pan to explore the map.
3. Click any of the points on the map.

   A pop-up appears, which includes a description of the hostile activity.

   

   This map was created using several Arcade expressions. The expressions aren’t visible in the app, but rather are working behind the scenes to ensure the app communicates clearly. Next, you’ll open the web map and explore some of these Arcade expressions.

4. Open the Anti-Shipping Activity Messages web map.
5. Zoom in on the map until labels appear.

   

   Each point is labeled with its year.

6. If necessary, on the Contents (dark) toolbar, click the Layers button to open the Layers pane.

   

7. In the Layers pane, next to Anti-Shipping Activity Messages, click the Options button.
8. Click Show table.

   

   The layer’s attribute table appears.

9. Scroll through the table to view the fields.

   There is no field listing the year. There is only the Event Date field. It includes the year, but also the month, date, and time of each incident.

   

10. Close the table.
11. On the Settings (light) toolbar, click the Labels button to open the Label features pane.
12. Under Label field, next to Year, click the expression button.

    

    The expression builder window appears. Year is not the name of a field, but the name of an expression.

    

    The expression is Year(ToUTC($feature.dateofocc)). This short expression extracts just the year information from the Event Date field. Year() is the function that extracts the relevant number. ToUTC() is another function that converts the date format. $feature.datofocc are the features in the Event Date field, which is also named dateofocc.

13. Above the expression, click the Run button.

    

    An output appears below the expression. It shows a year, instead of a longer date.

    

    The results of this expression are labels that look like 1990 instead of 1990-06-02T21:00:00-03:00. The shorter labels are easier to understand and make for a less cluttered map.

14. Close the expression builder window.

    Note:

    To see another example of an app with Arcade labels, see USGS Global Earthquakes. Select the Recent Earthquakes – Events by Magnitude layer and open the Labels pane to view an expression that only labels recent earthquakes.

Explore Arcade pop-ups

Next, you’ll explore how multiple Arcade expressions contribute to the pop-ups in this map. In particular, you’ll learn how Arcade can be used to set the color of text in the pop-up based on attribute values in the data.

1. On the map, click any pink, red, or purple symbol to open its pop-up.

   Note:

   If the map only contains yellow symbols, click a yellow symbol instead. Pink, red, and purple symbols are used for incidents that occurred in the current year.

   

   The pop-up shows the incident type and date in bold text that matches the symbol color for the incident type. It also shows a description of the incident.

2. On the Settings toolbar, click the Pop-ups button to open the Pop-ups pane.
3. Click Attribute expressions.

   

   There are three expressions used in this pop-up. Date Conversion is similar to the expression used for the labels. Hostility Type Classification and Hostility Type Color both determine the category of incident.

4. Click Hostility Type Color.

   

   This expression lists the values from the hostilitytype_1 field and assigns each a color, defined by hex codes.

   

   For example, line 3 says when the type (the value in the hostilitytype_1 field) is equal to 1, set the color to #e055a8 (pink). The gray text in the expression are comments, listing the description of each type.

   Next, you’ll see how this expression is used in the pop-up.

5. Close the expression builder window.
6. In the Attribute expressions pane, click the Back arrow.

   

7. In the Pop-ups pane, click Text. Click Edit text.

   

   Most of the text in the pop-up is derived from the description field, but the bold text at the top of the pop-up is derived from two expressions.

8. Highlight the two expressions, {expression/expr1} and {expression/expr0}, and click the Font Color button.

   

   On the Data-driven tab, the Hostility Type Color expression is selected.

   

   The color of these two lines of text is determined by the selected expression.

9. Click Done.

   The color of the here link at the end of the description text is set in the same way.

10. Click Cancel.
11. On the map, click some of the other symbols to see how the color of the text changes according to the hostility type of the incident.

    

    Arcade expressions allow you to create pop-ups with the most relevant information, formatted in the most relevant way.

    Note:

    To see another example of an app with Arcade pop-ups, see Coral Reef Bleaching Stations. The Coral Reef Station – Null layer uses four expressions to create its pop-ups, including one that creates URLs to feature images.

Explore Arcade symbols

In the final example in this tutorial, you’ll explore a more complex Arcade expression that determines the sizes of the symbols based on the map’s current scale.

1. On the Settings toolbar, click the Styles button to open the Styles pane.

   

   Under Choose attributes, two items are listed. These are not fields from the attribute table, but Arcade expressions. One of these expressions—Current Year Incidents—determines the colors of the map symbols. The other, Set the Symbol Size by Map Scale—determines their size.

2. Click Set the Symbol Size by Map Scale.

   The expression builder window appears. This expression uses the same Event Date (dateofocc) field that you saw in the labeling expression.

   

3. Read lines 8 through 13:
   When(
   vs > 72000000, Old,
   vs > 1700000, 1 + Old,
   vs > 8000000, 2 + Old,
   vs > 3000000, 3 + Old,
   vs > 1000000, 4 + Old, 5 + Old)

   The variable vs was defined earlier in the expression as $view.scale and refers to the current scale of the map. The variable Old was also defined earlier in the expression and sets the size of each symbol. For incidents in the current year, the value of Old is 9. For earlier incidents, the value of Old is 3.5.

   This part of the expression adds numbers to the Old variable as the scale decreases, resulting in symbols that grow larger as you zoom in on the map.

   Note:

   The Old variable is defined on line 6: var Old = Iif (dataYear != Year(Today()), 3.5, 9).

   This line says if the year of the incident (dataYear) is not the same (!=) as the current year (Year(Today())), the value of the Old variable is set to 3.5. Otherwise (if the year is the same as the current year), the value is set to 9. This expression results in large symbols for recent incidents and small symbols for older incidents.

4. Close the expression builder window.
5. Zoom in and out on the map.

   The effect is subtle, but the yellow circles appear smaller when you are zoomed out and larger when you are zoomed in.

   

   Note:

   To see another example of an app with Arcade symbology, see Live Stream Gauges. This map uses a similar expression to control the size of symbols based on the map’s scale. It also uses an expression to determine each feature’s status.

In this tutorial, you saw how ArcGIS Arcade can be used to customize labels, pop-ups, and symbols, to create maps that communicate more clearly. With a static dataset, new fields might be created and calculated to reformat dates, categories, and colors. However, this map uses a dynamic dataset, which receives new records every day and which is owned and managed by someone else. Creating new fields isn’t an option, but it’s also not necessary since you can derive new values from the existing fields with Arcade expressions.

ArcGIS Arcade is an important tool for interactive maps, allowing you to create maps that are designed to match the stories you need to tell, rather than just the data you have available. Arcade transforms data into powerful information expressions. Try the tutorial Get started with ArcGIS Arcade to learn how to write expressions in your own maps.

The Anti-Shipping Activity Messages app that you explored in this tutorial maps activity on the surface of the ocean. Try the next tutorial in this series, Explore a 3D app, to learn how interactive maps and apps can depict the ocean’s depth.

Acknowledgements

• The Anti-Shipping Activity Messages data was created by the National Geospatial-Intelligence Agency (NGA) and the ArcGIS Living Atlas of the World team. The map and app were created by Esri for this tutorial.
• Human Geography Dark Map sources: Esri, HERE, Garmin, FAO, NOAA, USGS, OpenStreetMap contributors, and the GIS User Community
• GEBCO Bathymtery 2022 sources: GEBCO Compilation Group (2022) GEBCO_2022 Grid (doi:10.5285/e0f0bb80-ab44-2739-e053-6c86abc0289c)