ArcGIS Online

Pop-ups: Arcade essentials

Layer pop-ups are an important part of crafting the complete map information experience. Pop-ups can transform an otherwise dull list of attributes into a far more meaningful display of intuitive and engaging information for your audience. Arcade can be thought of as a collection of useful tools that can be applied to craft the very best pop-ups, leveraging functions and logic to perform calculations and geometric operations, format text, access data from other layers, and much more.

What is Arcade?

Arcade is an expression language that is supported across ArcGIS. It can be used to perform calculations, manipulate text, and evaluate logical statements. Arcade exists within a profile, or context, that defines the parameters that are available to the script as global inputs and the output expected from the script. This blog article focuses only on the Popups profile and offers an overview of how it is used to craft layer pop-ups.

Arcade in pop-ups can be used in two ways; to create attribute expressions used in text elements that can be evaluated like fields, or as separate Arcade content elements that return a complete block of content. Using Arcade expressions and elements, you can take your pop-ups to the next level. Pop-ups: the essentials provides an overview of pop-ups and how they can be configured.

Why use Arcade?

Arcade enables you to work with data dynamically to perform calculations and manipulate data on-the-fly. If you have improperly formatted attributes, need to do a conversion, need to perform mathematical operations (e.g., sum values or calculate percentages), use logical expressions for branching, or perform geometric operations (e.g., calculate areas or intersections).

Arcade provides a straightforward, Excel-like way, to manipulate data without having to go back to the source. This is especially useful if you don’t own the source—Arcade can be applied to any feature layer in a map.

Quick links

Use these links to jump to a section of interest. Open the Arcade examples map to follow along.

Arcade attribute expressions

Arcade content blocks

Arcade editor

Create attribute expressions

Create Arcade content blocks

Commonly used Arcade

More information

 

Arcade attribute expressions

You can follow along by viewing the sample map that has the layers and expressions covered in this blog article. To view the expressions, open the layers pane from the Contents (dark) toolbar and select the layer you want. On the Settings (light) toolbar, click Pop-ups, then Attribute expressions.

Attribute expression

If the layer already has attribute expressions they will be listed. Click to open any existing attribute expression or click Add expression to begin a new one.

Attribute expressions

Tip: A great way to learn more about how to author and use Arcade expressions is to open any Living Atlas map or layer, then examine the pop-ups and expressions.

In pop-ups, Arcade expressions are used in text elements. Open any text element in the sample map to view how the expressions are used. Expressions appear in curly braces – {expression/expr0} – and are numbered starting at zero.

Text element with expression

 

Arcade content blocks

Pop-up content blocks, or elements, are the building blocks of pop-up information. Pop-ups can be composed of field lists, text, charts, images, or Arcade.

To view the content blocks, open the layers pane from the Contents (dark) toolbar and select the layer you want. On the Settings (light) toolbar, click Pop-ups, then view the list of content blocks. Arcade elements are listed using the code symbol – </> – and titled Arcade.

Arcade element

To add a new Arcade content block, click Add content and choose Arcade.

Arcade element

 

Arcade editor

The Arcade editor is used to create new attribute expressions and Arcade content blocks, or edit existing ones. It includes the following:

a – Name

b – Expression

c – Run (test) button

d – Action bar with options to display profile variables, functions, suggestions, and help

e – Action pane, with more information about the selected action.

Arcade editor
View larger image

Profile variables are special global variables that can be used in expressions. For example, $feature references the feature you click on your map to open the pop-up. This variable is used to retrieve specific attributes (fields) for the feature. For example, $feature.name returns the content of the field “name” for the feature.

Functions are used to calculate values in expressions. Functions are grouped and categorized into constants, data functions, feature functions, math functions, text functions, and so on. For example, Round is a math function that rounds the input numerical value to the specified number of places, and returns the new rounded number. Each function has built-in help so you can learn how to use them. You can also create your own custom functions for use in expressions.

Suggestions provide a list of existing expressions so that you can copy some or all of an expression into a new one.

Help links to the Arcade help documentation.

The Arcade editor also includes Intellisense, helping to reduce errors and helping to complete the expression as you write it. Warnings also appear in the editor, helping you understand when there’s something in your expression that could be a problem or could be improved.

Intellisense and error checking
View larger image

 

Create attribute expressions

In this example you will create two very simple expressions: one that converts all upper case text to proper case text and another that converts feet to meters. You can follow along by viewing the sample map and opening the Sample Pop-ups layer group, then selecting and viewing the Peaks (Expressions) layer.

Select layer

The text element shown below uses the {PEAKNAME} and {ELEV} fields to create the pop-up.

Pop-up
View larger image

Follow these steps to create the first expression that converts the upper case name to proper case.

Step 1 — In the Arcade editor, begin by doing the following.

a – Change the default name to something more meaningful and easier to recognize.

b – Add a comment (using the double forward slashes //) to describe what the expression does.

c – Click Profile variables to open the Profile variables pane.

d – Click the arrow to the right of the $feature variable to show all available fields.

Arcade editor
View larger image

Step 2 — Scroll down the list of fields to find PEAKNAME, then click the field to begin the expression. Since we already know the field to use, we could simply have begun the expression by typing $feature.PEAKNAME.

Arcade editor
View larger image

Step 3 — Move on to the next line. Click the Functions tab to view the available functions. Scroll down to the Text functions category to search for applicable functions, or enter the function name to identify possibilities. Click to add the function to the expression.

Arcade editor
View larger image

Tip: Click the arrow (circled in green in the image above) to learn more about the function. Click More information to go to the complete function help documentation.

Function help

Step 4 — The function takes a text value as the input and returns proper case text. Edit the expression so that $feature.PEAKNAME is the function value input.

Arcade editor

The optional parameter ‘everyword’ isn’t needed, since that is the default. But it makes the Arcade more understandable. The other parameter would be firstword to only capitalize the first word in the string.

Step 5 — Click Run to ensure the expression returns the desired result. Click OK when finished to save the expression.

Run expression

Step 6 — Use the expression in the text element just like any other field. Enter the curly brace { in the text element to display a list, the expressions are found at the bottom.

Select expression

The text elements now returns the proper case peak name.

Text element with expression
View larger image

Step 7 — Use similar steps described above to create another expression that converts the elevation in feet to meters.

Arcade editor

This expression can be used in the text element as shown below.

Arcade expression
View larger image

To match the elevation in feet and elevation in meters formatting, the number of significant digits (decimal places) needs to be zero and a comma separator needs to be added. There are two ways this can be handled; by formatting the expression or by managing the returned text in the expression.

Add formatting to the expression

To add text formatting to the expression, return the height in meters as a string using the Text function and add the desired formatting using the hash notation to the returned text.

Arcade editor

Format expressions like fields

Since expressions are treated exactly like fields, we can format the FeetToMeters expression by selecting it in the Fields pane (expressions are found at the bottom of the fields list) and adjusting the formatting.

Formatting

Additional text typography, such as text size, bold or italic text, and color can be applied to expressions, text, and fields to achieve the desired result.

Text element typography
View larger image

 

Create Arcade content blocks

You can follow along by viewing the sample map and opening the Sample Pop-ups layer group, then selecting and viewing the Peaks (Element) layer. In this example the Arcade content element is similar to the pop-up created with attribute expressions above, with some additional HTML styling. Compare Peaks (Expressions) and Peaks (Content Element) to understand the two approaches.

One of the biggest differences between Arcade attribute expressions and Arcade content elements is that attribute expressions are used in text elements, and Arcade content elements are intended to return a complete part of your pop-up, either independently or combined with other elements. While the Arcade behind both expressions and elements is very similar, Arcade content elements are self-contained, so anything you need must be done within the element.

When you open the Arcade editor, there are several templates that help you get started. By default, the Rich text template is opened.

a – Change the default name to something more meaningful and easier to recognize.

b – Edit and add comments to describe what the expression does and also use comments to document the steps along the way. The better you document your Arcade, the more understandable and maintainable it will be.

c – Use the Profile variables and Functions tabs to construct the Arcade expressions. This is the same as is done when creating attribute expressions.

d – Use Arcade functions to assign variables that will be used in the returned text. The goal of all functions, profile variables, and variables in the context of explicitly returned text is to create the building blocks to be used to construct the final returned text.

e – The explicit Return is the block of rich text that the Arcade content element displays in the pop-up. In the case of rich text, this provides full HTML styling to craft the returned content.

Arcade content element
View larger image

The final result is the pop-up shown below.

Arcade content element

This is a simple example using Arcade content, with lots more potential to go beyond the basics. See the Peaks layer in the Final Pop-ups group for an example.

 

Commonly used Arcade

The following are examples of common uses of Arcade in pop-ups. Many of these are used to configure pop-ups in the Arcade samples map used in this blog article. Other examples can be found in ArcGIS Living Atlas maps and layers or the Arcade Function Reference.

Proper case text

This expression will return proper case text. The Proper function has two options – capitalize all words or capitalize the first word only. If COUNTY contains the string “SAN DIEGO COUNTY” the expression returns “San Diego County.”

var txtProper = Proper($feature.COUNTY, 'everyword')
return txtProper

There are many other text functions for working with text. For more information, see Text Functions.

Convert codes or abbreviations to a readable string

Converts an abbreviation or code number to an understandable string. For example, if the field value is “CAC” the expression will return “Cades Cove.”

var distNam = $feature.PARKDIST

When (
    distNam == "CAC", "Cades Cove",
    distNam == "CAT", "Cataloochie",
    distNam == "COS", "Cosby",
    distNam == "DCR", "Deep Creek",
    distNam == "LRI", "Little River",
    distNam == "OCO", "Oconaluftee",
    "Unknown")

Units conversion

This expression will convert feet to meters using a simple conversion factor. The units in feet are in the field ELEV.

Text($feature.ELEV * 0.3048, "#,###")

Remove blanks or empty values

This expression checks the contents of AFIELD and will return “Unknown” if it is null, the field has spaces, or the feature is empty. Otherwise, it returns the field contents.

var valField = $feature.AFIELD
var boolEmpty = IsEmpty($feature.AFIELD)

When(
    valField == NULL, "Unknown",
    valField == " ", "Unknown",
    boolEmpty == true, "Unknown", 
valField)

Another approach is to use DefaultValue to compare against null.

DefaultValue($feature.AFIELD, 'Unknown')

To also catch spaces, add Trim.

DefaultValue(Trim($feature.AFIELD), 'Unknown')

Create a link by combining an attribute value and a root URL string

You can combine feature attribute values with a string to create a URL link to open another web site or to retrieve more information. For example, a parcel map may have a unique parcel ID which can be linked to the assessor records by creating the unique URL that points to the information,

// Return link to unique property record
var txtLink = "https://app1.pinal.gov/Search/Parcel-Details.aspx?Parcel_ID="+$feature.ParcelID
return txtLink

Get attributes from another layer in the current map

Using expressions, you can combine attribute information from other layers in the same map into a single pop-up. Use FeatureSetByName to find the layer using its name.

// Get layer named "Counties" in the map
var fsetCounties = FeatureSetByName($map,"Counties")

Other functions can be applied to the feature set to retrieve the desired information, such as Count or geometry functions such as Intersect.

var numCounties = Count(fsetCounties)
var feaCounty = (First(Intersects(fsetCounty, $feature)))

Get attributes from a layer not in your map

In this case a feature set is returned from another layer that is not in the current map, referenced by its ID. This can be used to retrieve attributes from Living Atlas layers such as current weather, demographic information, air quality, and more.

var fsetStates = FeatureSetByPortalItem(Portal('https://www.arcgis.com/'), 
"774019f31f8549c39b5c72f149bbe74e", 0)

Apply color to text

In text blocks you can add color to expressions in the same way as coloring text or attribute values (select the expression, then use the color picker). In this example two expressions were constructed to evaluate the {STATUS} field which contains one of two attribute values; Active or Inactive. While the logic here may initially seem confusing, we are creating two expressions which return the string value Active or Inactive. If the expression does not evaluate to True, Null is returned and it will not appear in the text block.

The first expression, titled IsActive, evaluates whether the field for the feature contains the word Active.

Arcade expression

The second expression, titled IsInactive, evaluates whether the field for the feature contains the word Inactive.

Arcade expression

Color is applied to the expression, which is treated like a field, in the text editor. The results are shown below.

Text element color
View larger image

 

More information

For more information, see the following:

This blog article was originally published on October 18, 2022, and has been updated.

About the author

Corporate technology evangelist and advocate at Esri, focusing on ways to broaden access to geographic information and helping customers succeed with the ArcGIS system. On a good day I'm making a map, on a great day I'm on one. Email bszukalski@esri.com or connect on LinkedIn (https://www.linkedin.com/in/bernszukalski/).

Connect:

Next Article

What's New in ArcGIS Urban (February 2024)

Read this article