Arcade is a lightweight expression language for customising your ArcGIS maps and apps. Whether it’s for enhancing your pop-ups, integrating other data layers, performing on-the-fly calculations, or so much more, Arcade is a helpful tool to understand.
We’ve already written a few blogs about Arcade and featured it in our webinars. In this blog, I’d like to dive deeper into one of Arcade’s building blocks – keywords. After addressing what they are, we’ll look at some examples in ArcGIS Quick Capture. And don’t worry, you do not need to have coding experience to be successful with Arcade.
I’ll say it again for the people in the back – with all the documentation, sample code and built-in error checks available to you, it’s possible and beneficial to include Arcade in your workflow regardless of your level of scripting experience.
Now that I’ve stepped off my soapbox, let’s learn some Arcade.
What are keywords
Keywords command Arcade to run a specific task or set of tasks in a statement. They are reserved words specifically kept for instructing Arcade to do things.
Some common keywords are var, if, else and return.
var
Perhaps one of the most important keywords, var declares a variable. Variables store data values in memory and are a useful shorthand so that you do not have to explicitly call out your data every time it is being used. They improve the code’s overall design, minimise repetition, improve readability and can make your code more efficient.
return
Another important command is return, which specifies the result that you’d like your expression to show and ends the expression.
if
The if keyword indicates the start of a block of statements to run when a condition (defined in parentheses) evaluates to true. If it evaluates to false, then the block of code is code skipped. This is useful for 1) returning something when a variable matches certain conditions or 2) to handle multiple conditions, like in data categorisation.
else
else goes hand in hand with if. When the if statement evaluates to false, the else keyword defines a code block to run instead.
All together now
Now let’s see how these keywords interact in the wild, starting with a simple example. Each step is explained using comments – text ignored by Arcade that can help you, and others, understand the expression. Comments are signposted with backslashes, “//”.
Tip: It is good practice to comment at each block of your script. This will help you, and others, understand what everything is meant to do within the expression. In this example I’ve expanded the comments to explain what the code does:
Using the Arcade Expression Editor in ArcGIS Map Viewer to write a simple expression.
ArcGIS QuickCapture Specific
Here is another example of Arcade keywords: within ArcGIS QuickCapture’s coding environment from a presentation at our Annual Conference. Arcade is streamlining a Storm Survey Report to make data capture more efficient for remote workers monitoring storm incidents. The script pulls in other data layers to find the nearest building title to each incident feature, pulling in other data layers to do so. This data enrichment process saves remote workers the time of having to cross-reference each point with the supplemental data themselves.
Let’s step through it…
Tip: If you get lost, remember the comments!
An Arcade script in ArcGIS QuickCapture’s coding environment.
1) Our first three statements set up the rest of the expression by defining variables. The var keywords call and store a buildings featureset from a layer within the map (var Buildings), a buffer around each incident reported feature (var pointBuffer), and define a variable storing the number of buildings intersecting this buffer (var allInRange). You can find a full list of functions available in Arcade here.
2) This if statement builds off the previously defined variables. To see what it’s evaluating, we just need to look at what’s inside of the parentheses. In this case, the allInRange variable is being evaluated for whether its value is less than one, ie no buildings within the reported feature’s buffer.
3) So, how do we know what happens if this if statement evaluates to true? The return keyword prints NULL, letting us know that there aren’t any buildings within the buffer.
4) And, when the if statement is false, else takes over and runs a different code block. This if-else check helps avoid running extra code, which can speed up performance. They are also a clear way to show different outcomes, making your code easier to follow.
While not a keyword, this code contains another important element – loops. Loops run a code block repeatedly until a specified condition is no longer met (a process also called iteration). In this example a for loop is being used to iterate through a featureset, for is a keyword. For each building that is within the incident feature’s buffer, defined earlier as allInRange, the loop evaluates:
- how close each building is to the feature (var addressDist)
- whether the building’s distance is closer than the current closest building distance, and if so, its ID is stored as var nearestBuilding
This iterates through all the buildings within the buffer, and when complete, Arcade returns the closest building to the incident feature. A systematic and dynamic way to evaluate a dataset.
Tips
While writing this blog, I caught up with James and Adriana (some wonderful and knowledgeable colleagues) who have a few tips to help your scrips run smoothly.
Enriching your data
You can use Arcade to reference other layers within your map, other data within your organization, or more broadly from the Living Atlas of the World. This can help you avoid cluttering your map with too many layers.
Filters
With whatever layers you bring into your expressions, filtering improves their efficiency by retrieving only relevant information. This tutorial offers a great example.
Note: This is especially useful to avoid retrieving geometries. If you filter by name or ID, it’s typically less computationally expensive than comparing geometries. It also avoids precision errors that can result from spatial reference issues.
Console
There are a few ways to debug your code, including the Console function, which checks what is being run at the specific point in your script. In the QuickCapture example, it is being used to check how many buildings are within the buffered feature. It can be a useful tool to ensure that specified steps in your script are doing what you intended! Just because your Arcade script runs, it doesn’t mean it is doing what you expect.
Geometry functions
You can do spatial calculations in Arcade, including comparing and measuring geometries on-the-fly. There are plenty of geometry functions, like AreaGeodetic or Angle, which you can learn more about here.
Sample code
The world is your repository. If you’ve clicked on any of the links in this blog, you’ll have realised how comprehensive the documentation is. So, use what is already out there and adapt it.
Wrap up
We started with defining keywords, applying them, and seeing how critical they are to instructing Arcade. Now that you’re familiar with a few keywords, if only there was a way to apply what you’ve learned… why not return to the Arcade coding environment for some practice using them?