The ArcGIS Arcade documentation pages recently underwent a significant revision in an effort to clarify language features and improve the introduction to the language.
You can access the updated documentation at https://developers.arcgis.com/arcade/. Before showing off some of the changes, I’ll provide a brief overview of why these changes were needed.
Why update the documentation?
Prior to this update, Arcade’s introduction lacked the basic terminology and definitions typically required for people attempting to learn any scripting or expression language. Some topics were incomplete and difficult to discover from the home page.
Concepts specific to Arcade, like profiles and profile variables (formerly known as global variables), previously weren’t described in depth. Finally, the concepts listed in the table of contents, in retrospect, could have been ordered in a more helpful manner.
Revisions
Now let’s take a look at a few of the major revisions made to the documentation.
Home page and table of contents
The home page was simplified to only describe what Arcade is, where it is used, and why it was created. We added an expandable Language features section, which describes core language features, such as statements, variable declarations, type casting, and reserved words. This was deliberately placed right after the introduction since it contains important information for learning the language, which we deemed more important than the pages below it.
We also added two new pages: Supported products and Resources. Supported products lists all the ArcGIS products where you can author Arcade expressions. Please note that it does not reflect all the apps where an existing expression may run if loaded from a web map. Resources is intended to be a place where you can find additional learning material, including presentations and blogs, where you can learn how to use Arcade in specific scenarios.
Language features
The Language features section replaces the former Structure and logic page with 15 new pages that describe the Arcade syntax and language constructs. You will find detailed documentation about the rules that were always present, but weren’t previously documented. This includes variable naming conventions, reserved words, implicit type casting, and a more complete definition of profiles to name just a few. We also added best practices, debugging tips, and suggestions for writing performant expressions.
Giving these topics proper pages makes them more discoverable on the left hand table of contents and better suited to assist someone new to Arcade to learn expressions.
Profiles
The Profiles page was updated to define the various parts that make up a profile. This should add clarity to how a profile is defined, why profiles matter, and which functions are available in each.
While there is a profiles topic in the table of contents, for your convenience we have added a dedicated header tab as illustrated below.
This organizes each profile’s documentation in its own page as opposed to how they were listed previously on a single page, making it very long.
Each profile page was updated with consistent headings that describe the profile’s description, context (or parts of the apps and APIs where the Arcade profile is implemented), the profile’s variables (renamed from globals) available to expressions in each context, function bundles (more on this later), valid return types, and finally examples of expressions written in that profile.
Functions
We reorganized the built-in Arcade functions from seven categories to 13. Functions are categorized based on the data types the functions are designed for, and in some cases, the context or purpose of each function.
For example, we previously documented 59 “data functions”. The data functions was a catch-all category for functions that helped you work with data in any form. It was large, and therefore difficult to discover specific functions.
Functions, like Count, were difficult to discover depending on the type of input data you used. For example, Count can be used to return the number of items in an array or a FeatureSet, or the number of characters in a text value. Previously, if you looked for Count in Text functions, you wouldn’t find it there. Now you can find function overloads for Count in Text, Array, and FeatureSet functions.
Function bundles
Not all functions are available in every Arcade profile. For example, you can use FeatureSet functions in popup expressions, but not in expressions used in layer styles. The new documentation attempts to make what is included and excluded in each profile more transparent by introducing function bundles.
A function bundle is a set (or bundle) of functions available in a specific context. For example, the core bundle includes functions available in every Arcade profile. This means no matter where you write Arcade, these functions will always be available to you. Other bundles, such as data access, bundle functions for accessing data through database queries.
Each profile page lists the bundles available in the profile.
And each function lists the bundle and profiles to which it belongs.
Conclusion
We hope you find the new Arcade documentation intuitive and easy to navigate. We plan on making future enhancements to the documentation to make testing and experimenting with Arcade expressions more friendly. If you have any feedback, please send us a message with your email address by clicking on the link in the Was this page helpful? section below the right table of contents menu on each page.
Article Discussion: