- It allowed you to calculate new values based on existing field values in your layer. For example, it made sense where service fields couldn’t be modified, or you didn’t own the layer, but wanted to calculate new data values based on values already present in the layer.
- It allowed you to use values provided by end users via UI elements (e.g. input elements, select elements, HTML range sliders, etc.). One example of this is updating an above-and-below visualization based on the value of an HTML range slider moved by the user.
- It allowed you to perform calculations for data not present in your layer. For example, you can query features from other layers and perform geometry operations on them within the renderer’s field function to visualize the results of any spatial operation. This workflow isn’t currently supported in Arcade, but will be soon.
Check out the following app, which visualizes a FeatureLayer representing political boundaries in mainland China using a function set on the field property of the layer’s renderer. This is an above-and-below visualization, which categorizes each feature based on whether the percentage of the population without education is above or below the value of the feature selected by the user.
Arcade: A better approach
In December 2016, Esri introduced Arcade – an expression language for returning new data values client-side. Arcade can be used to calculate and return values for labels, popups, and renderers based on logic defined in an expression.
Several people have already written on various ways Arcade is and has been used for visualization in the JS API. Check out the following blogs to learn more about this.
- Using Arcade expressions in web apps”>Using Arcade expressions in web apps
- Use Arcade Expressions to Map Your Ideas
- Generate Arcade expressions for data exploration web apps
- Persistence throughout the ArcGIS platform. This means you can author and save an Arcade expression for a layer’s renderer within a web app or ArcGIS Online, and the same syntax will be understood and executed properly in other web apps, mobile apps created with the Runtime SDKs, and ArcGIS Pro.
So why take away this support? What about the benefits mentioned above? What if I want to create a visualization based on user input? What about access to outside features, or geometry operations?
The short answer to these questions is that Arcade allows you to create these visualizations.
valueFunction is the name of a function that takes an esri/Graphic instance as a parameter. This function executes for each feature at the time of rendering. For that reason, it is important to keep the code in this function light. Adding heavier code will come with a performance cost to the application.
Each time the user clicks a feature, the app updates the value of the
value variable to the value of the clicked feature, causing the renderer to change.
I used the 4.9 version of the JS API to create the exact same app. But this time I pass an Arcade expression to the valueExpression property of the renderer.
createArcade function returns an Arcade expression that determines whether the feature’s value is similar, above, or below the input value. Note how I use template literals to access the value of the selected feature and insert it to the Arcade expression. This same technique can be used to get user input from other DOM elements.
Since the clicked, or selected value, is a constant in the Arcade expression, the expression must be re-created with the new value and reset on the renderer. Once you update the renderer on the layer, the layer’s layer view will automatically refresh and update the visualization appropriately.
Now the final app looks like the following.
Keep in mind that while this version of the app doesn’t expose any functional differences from the previous version, it does redraw features more slowly than the 4.8 version of the app. We will improve performance in this regard at a future release.
We will add support for all Arcade geometry functions soon, making it possible to use Arcade for this use case with the 4.x JS API. Note that version 3.26 of the JS API already supports Arcade’s geometry functions, so you can use that API if your visualizations require them now.