Dashboards That Pop: Arcade
I’m back with another Dashboards That Pop. Today we’ll be talking about advanced formatting and Arcade. Not an Arcade guru? That’s ok, because neither am I! My brain just isn’t cut-out for scripting in any language, but I do have some easy and versatile Arcade tips to snazz-up your dashboards. If I can do it, then so can you.
Here is our starting dashboard. This dashboard displays USGS Volcano Status data from the Living Atlas.
There is some conditional formatting applied to the indicators that changes the text color if there are any alerts.
Now let’s apply some Arcade to the dashboard.
The conditional formatting of the indicators has also been taken up a notch by using Advanced formatting.
Advanced Formatting with Arcade
You can use Arcade in the table, list, and indicator elements by enabling Advanced Formatting.
Once you enable Advanced Formatting, the Arcade editor will open up. Each of these elements has their own specific return statement that includes all of the configurable portions of the element. Watch how changing the values of various return elements changes the indicator’s appearance.
💡Tip: If you are unsure of what a specific return element is, add a value and see what changes in the preview.
You may have noticed that some of the elements in the return statement are a bit grayed out and begin with //. This means that they have been ‘commented out’, and that they are being ignored. You will need to remove the // to use that element.
If you have an element uncommented, but do not provide a value. The default value will be used. In this example, I have not provided a value for the background color, top text color, top text outline color, middle text color, or middle text outline color. Therefore, the default dashboard theme values for element background color and text colors are used.
To use default values, you will need to have empty quotes. If you remove the quotes and just leave it completely blank, you will get an error.
Value Types
Now that we know how the return statement works, let’s look at the different types of values you can use in your return statement. There are three types of values you can add to each individual return element:
- Hard-coded values
- Data attributes
- Arcade variables
Hard-Coded Values
These are the most straightforward. Simply add the value you want used in-between quotes. Color elements can use hex codes or HTML color names.
When you hard-code values like this, they will not be dynamic. The value is always what you provided. There are certain situations where this is perfectly fine. I hard-coded the background colors for my conditional return in the example dashboard.
💡Tip: If you are going to be using conditional formatting, turn on conditional formatting FIRST and then enable Advanced formatting. This way, the conditional formatting return statement is created for you.
Data Attributes
This is when you’re pulling values straight from your data.
As your data changes, so does your display.
When using attribute data, you do not need to use the quotes, so be sure to remove them before adding your attribute. I always use the Globals pane to add my attributes. That way I don’t have to worry about getting the syntax correct or any typos.
Arcade Variables
If you want to use values that are not a part of your dataset, but still need them to be dynamic this is the way to go.
While the alert level has a color value assigned in the data, the threat level does not. If we want to focus on the threat level and have dynamically changing colors that highlight very high threats, we will need to use Arcade to do so.
I’ll start with a simple when statement. When the threat level is Very High Threat, give me red, otherwise leave it blank.
When($datapoint.Threat == 'Very High Threat', 'red', '')
We have our Arcade statement to dynamically change the color from the default to red when the feature has a Very High threat level. However, we can’t use it anywhere yet, because we have not assigned it to a variable.
Let’s assign it to a variable called ThreatColor.
var ThreatColor = When($datapoint.Threat == 'Very High Threat', 'red', '')
Now wherever we want to use our dynamic color, we simply add ThreatColor. Because it is a variable and not a hard-coded value, we will not need to include it in quotes.
If we look at a volcano that doesn’t have a very high threat level, we can see that we do not get the red text.
Mix and Match
You can mix and match the types of values you are using in the return statement to get exactly the look you want.
Arcade Attributes
What if you want to use Arcade to create dynamic values that aren’t used in the predefined configuration options? This is where all those attribute lines in the return statement come into play.
Let’s start with this simple list.
💡Tip: Wondering how I got that square icon in there? Read my Icons blog to learn about HTML symbols.
We have two goals:
- Dynamically change the square next to the threat level’s color based on the threat level.
- Turn our observation field into something more usable.
Let’s enable Advanced formatting to make it happen.
First, we will make our Arcade expression to create the threat color. We want each threat level to have its own color this time, so we’re just going to add onto the expression we used above. We'll also add a default color to be applied for any other values.
var ThreatLevel = When(
$datapoint.Threat == 'Very High Threat', '#780116',
$datapoint.Threat == 'High Threat', '#981e1d',
$datapoint.Threat == 'Moderate Threat', '#f7b538',
$datapoint.Threat == 'Low Threat', '#1f4d2e',
$datapoint.Threat == 'Very Low Threat', '#008040', '#fff1e6')
Looking at our return statement, we only have a single text color element and if we use it, all of our text changes color. This is not at all what we want.
Instead of using our ThreatLevel variable in the textColor element. We’ll instead return it as an attribute.
We will need to uncomment all of the attribute elements, and then add our variable to attribute1. We’ll remove attribute2, as we’re only returning this single attribute.
We’ve added our ThreatLevel variable to the return statement, but nothing has changed in our list. This is because these attributes are not used unless we explicitly add them.
The syntax for this is {expression/attributeName}
We’ll add this to our list so we can see it in action.
So, we know our statement is working. Now we just need to use it to change the box color. To do this, we’ll use the rich text editor to change the text color for just our box. It doesn’t matter what color you pick, as we’re only using the editor so that the HTML syntax is created for us.
Now we will use the source button to view the HTML. Look for the hex code that was added and replace it with our ThreatLevel attribute.
We’ll remove our test attribute from the list and here’s what our list looks like now.
Now let’s clean up our Observation field. We will again use a When statement, only this time instead of returning colors, we will return text and our default value will be blank.
var obs = When(
$datapoint.Observation == 'avo', 'Alaska Volcano Observatory (AVO)',
$datapoint.Observation == 'calvo', 'USGS California Volcano Observatory (CalVO)',
$datapoint.Observation == 'cvo', 'USGS Cascades Volcano Observatory (CVO)',
$datapoint.Observation == 'hvo', 'USGS Hawaiian Volcano Observatory (HVO)',
$datapoint.Observation == 'yvo', 'Yellowstone Volcano Observatory (YVO)', '')
Again, we need to return this variable in the attributes section, so we’ll add another attributes line. We could have gone with attribute2, like in their example. However, I find it easier to instead use the variable name. As you get more and more attributes, remembering which one was attribute1 vs attribute4 is hard.
We will move to the list and replace our Observation field with our new Arcade obs field.
When() Function
You may have noticed that I use When() A LOT. This is because it's so versatile and easy. If you only learn one Arcade function, I recommend it be this one. I use it to dynamically change colors, clean up text fields, and even combine it with other functions.
Here’s everything that is powered by a When() statement in my example dashboard.
- When the Alert Level is ‘X’ provide ‘X’ hex code.
- When the threat level is ‘Low’ provide the Alert Level hex code, otherwise provide a light black color. (Repeat for every threat box)
- When the alert date was less than 24 hours ago, provide a volcano emoji, otherwise leave blank. (Combined with DateDiff)
- When the alert date was less than 24 hours ago, provide the length of time from now in hours, otherwise provide it in days. (Combined with DateDiff and Concatenate)
- When the Observation Code is ‘X’ provide an easier to understand value.
💡 Tip: Check out my HTML blog for tips on creating your own status bars.
Happy Dashboarding!