ArcGIS Online

Introducing new Arcade documentation

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.

The former structure and logic page
Formerly, all Arcade language features were described on a single page called "Structure and logic". The topics didn't follow an intuitive order. Ironically, leading with built-in logical functions and case-insensitivity isn't the most logical way to learn a new language.

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.

The new home page for the Arcade documentation.
The home page was simplified to describe the what, where, and why of Arcade. We reordered the table of contents to include new pages for resources and information about which products allow you to author Arcade expressions.

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.

The new Arcade documentation guide pages.
The Arcade documentation added 15 new pages introducing language features in a logical order with clear definitions and more example snippets.

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.

The new profiles pages.
Profile documentation was enhanced to more clearly describe what a profile is, including its essential elements and rules.

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.

Popup profile documentaion.
Each profile page follows the same structure, defining a profile's context (or where it is implemented), profile variables, available functions, valid return types, and examples.

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.

The function reference of the Arcade documentation.
The new function reference landing page. Functions are now grouped into 13 categories, making it easier to find documentation depending on your data and use case.

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.

Function bundles matrix
This matrix describes which functions are included in each bundle.

Each profile page lists the bundles available in the profile.

Function bundles in the Popup profile.
The available functions in a profile are documented as "function bundles". Each bundle includes a list of functions that may be used in expressions within the given context.

And each function lists the bundle and profiles to which it belongs.

Profiles and bundles listed for the Domain function.
The documentation for each function lists the profiles it is included in, along with the function bundle to which it is assigned.

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.

The location of the link for providing feedback.
Click the thumbs up or thumbs down icon to send feedback for the documentation. You may use it to report errors, typos, or suggest improvements to the site.

About the author

Kristian is a Senior Product Engineer at Esri. His work focuses on data visualization and Arcade integration in the ArcGIS API for JavaScript. His goal is to help developers be successful, efficient, and confident in building web applications with the JS API, especially when it comes to visualizing data. Prior to joining Esri he worked as a GIS Specialist for an environmental consulting company. He enjoys cartography, GIS analysis, and building GIS applications for genealogy.

Connect:
1 Comment
Oldest
Newest
Inline Feedbacks
View all comments

Next Article

Migrate to the new World Population Estimate Maps

Read this article