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 – Test button

d – Tabs to display globals, functions, constants, and existing expressions

Arcade editor
View larger image

Globals are special variables that can be used in expressions. $feature references the feature you click on your map to open the pop-up. This global 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 categorized into mathematical, text, data, logical functions, and so on. For example, Round is a mathematical 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.

Constants are fixed variables that can be used in expressions. For example,  TextFormatting.NewLine inserts a new line, or line break, into the text.

Existing returns all existing expressions, making it easy to reuse and modify them. This tab is not available when creating Arcade content blocks.

 

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 that more meaningful and easier to recognize.

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

c – Click the Globals tab.

d – Click the arrow to the right of the feature globals 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 — Click the Functions tab to view the available functions. Scroll down and use the function name to identify possibilities. Click to add the function to the expression.

Arcade editor
View larger image

Tip: Click the information button (circled in green in the image above) to learn more about the function.

Proper function

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 expression

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

Test 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 expression

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.

Text formatting

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 (Content Expressions) 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 – Name. 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 Globals and Functions tabs to construct Arcade. This is the same as done with attribute expressions.

d – Use Arcade functions and globals to assign variables that will be used in the returned text. The goal of all functions, globals, and variables in the context of explicitly returned text is to create the building block to be used in 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 editor
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")

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')

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.

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:

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 with the Network Management Release Plan

Read this article