Release notes for 4.21

September 2021

Performance improvements

Version 4.21 introduces many performance improvements that will decrease the draw time of your layers. These improvements are focused on polygon features and maps with multiple layers.

Complex polygons

For complex polygons with a large number of vertices, layer draw time has significantly improved. Behind the scenes, we added a new simplification algorithm to preprocess the geometries and optimize memory management. We now use web assembly for triangulation for the majority of use cases. As you can see in the example below, this Arctic sea ice layer loads over 5x faster than the same layer in 4.20. The improvement varies layer by layer, but for most polygons with a large number of vertices, you will see at least a 2-3x improvement.

Large layers with many polygons

Because of the optimizations mentioned above and the switch to web assembly, you should also see performance improvements for layers with a large number of polygon features. The following example shows a layer with over 73,000 polygons. On average, we are seeing a 20% improvement in draw time.

Maps with many layers

We've also added some optimizations for the way we handle maps with a large number of feature collections. These optimizations have resulted in an improved start time and an improved frame rate for smoother map panning.

Enterprise point FeatureLayers

At version 4.19, we improved the performance of point FeatureLayers hosted on ArcGIS Online. Version 4.21 brings these changes to ArcGIS Enterprise point services.

Control the drawing order of features

You can configure the order features are drawn in the view by setting the orderBy property of a FeatureLayer, CSVLayer, GeoJSONLayer, and OGCFeatureLayer.

This property allows you to sort features using any field or Arcade expression that returns a number or a date.

1
2
3
4
5
6
layer.orderBy = [{
  order: "descending",  // or "ascending"
  field: "Population",
  // or alternatively...
  valueExpression: "$feature.Poverty / $feature.Population"
}];

In layers with date fields that have many overlapping features, this property allows you to ensure the most recent features are drawn on top of older ones. This property is also important in proportional symbol maps where smaller features are typically rendered on top of large ones to maximize the visibility of overlapping features in the view.

ascending (small values on top)	descending (large values on top)

Check out the Configure feature sort order sample for more information.

Layer updates

Refreshable layers

We've added the following optimizations and improvements for working with refreshable layers — layers that update their data at a specified interval. A layer is refreshable if it has a refreshInterval property.

• To reduce load on the server and minimize unnecessary requests, the FeatureLayer will only request data at its specified refreshInterval if the lastEditDate in the layer's metadata has changed. If the FeatureLayer does not have lastEditDate info, then the layer will refresh unconditionally.
• All refreshable layers emit a refresh event that will indicate when the data has been refreshed.
• WFSLayer is now a refreshable layer.

Raster layer updates

ImageryLayer

Two new query methods were added to ImageryLayer: queryRasterCount and queryObjectIds. The FeatureTable widget can display raster catalog info associated with an ImageryLayer that has a mosaic dataset. For example, you can examine resolution and cloud cover information associated with each image in the service.

ImageryTileLayer

The VectorFieldRenderer renderer is supported on ImageryTileLayer in addition to ImageryLayer.

Widget updates

User interface for configuring snapping

The SnappingControls widget was added to provide a simple user interface to handle all snapping functionality. This widget provides the ability to control whether snapping is enabled, which layers to snap to, and other snapping settings. SnappingControls can only be used in conjunction with the Sketch, SketchViewModel, Editor, and EditorViewModel.

This is included in the Sketch widget by default. In the future, we plan to add this as part of the Editor and Measurement widgets.

SketchViewModel - updated drawing symbology

The SketchViewModel has been updated to override the active drawing symbology, if there is a pointSymbol, polygonSymbol, or polylineSymbol set. The defined graphic symbols will now be shown while in an active drawing state. In earlier versions, the defined graphic symbols set would not be visible until the drawing operation completed.

4.20	4.21

Additionally, a point symbol was added to the mouse cursor when drawing using the SketchViewModel or Sketch widget. You can override the default symbol by setting the pointSymbol property.

An updated and improved Editor widget is coming

In version 4.22, we will introduce a significant update to the look and feel of the Editor's UI and workflow. In addition to the UI/UX improvements, there will be support for batch editing workflows and options for snapping and selections.

Although these updates will add additional functionality and improve the overall editing experience, the user experience will deviate slightly from the current implementation. We do not anticipate any loss of functionality or breaking changes. Anything that is currently supported will continue to be supported in upcoming releases. As with any API redesign, we intend on taking these Editor updates slowly and incrementally. Version 4.22 will be the first release with these Editor updates. As it matures, additional capabilities will be implemented.

If you would like an early look at these changes, check out the /next repo where we will post early development updates.

FeatureTable - support for additional layers

The FeatureTable widget added support for the following layer types: CSVLayer, GeoJSONLayer, ImageryLayer, and WFSLayer. The FeatureTable already supported FeatureLayers and SceneLayers.

TimeSlider actions

The TimeSlider widget has been updated to support custom actions, which allows you to execute custom code such as such as setting the timeExtent to a specific date or copying the timeExtent to the browser's clipboard. The trigger-action event fires whenever an action in the menu is clicked.

Popup and Feature

Popup error messages

The Popup widget has been updated to display an error message if any errors occur when accessing its content.

Configure what elements are queried and displayed

You can override what content is queried and displayed in the Popup or Feature widgets with the featureViewModelAbilities and abilities properties, respectively. By default, any pre-defined content types are displayed. This is useful in circumstances where there may be an already-defined popup (e.g. carried over from an existing webmap), and you don't want to query and display all of its content.

The images below show the default behavior of a popup with an associated feature attachment as opposed to the same popup without the attachment. The popup view model's featureViewModelAbilities.attachmentContent is set to false.

Default popup displaying feature attachment	Popup with featureViewModelAbilities.attachmentContent = false

Search suggestions

We enhanced the Search widget suggestion behavior to make the search experience smoother and faster. First, we increased the default minimum characters required before suggestions are displayed, from 1 to 3 characters. Second, we increased performance for searching on hosted layers by refining the internal SQL query. Third, we increased the default suggestion delay before suggestions are displayed, from 150ms to 350ms.

3D updates

Local scene support for WGS84

SceneView now allows you to fully leverage your WGS84 scene layers by combining them with Web Mercator layers in local scenes.

In addition, local scenes now support geographic coordinate systems, giving you more flexibility in displaying data. Constrain the view by defining a clipping area for example.

WebGL2 support

SceneView now uses WebGL2, if available in the browser, as the underlying rendering engine. This change is the basis for future visualization capabilities and performance enhancements. WebGL1 context can still be explicitly requested for apps using externalRenderer.

Clustering updates

You can access clustered features using Arcade expressions within the cluster popup via the $aggregatedFeatures global variable. This allows you to filter, sort, and calculate statistics on a cluster's aggregated features exclusively using Arcade.

While you can already query clustered features using JavaScript, using Arcade allows cluster popup content to be saved and persisted in webmaps so users can understand more detailed information about clusters without having to implement cluster query logic with custom JavaScript in each app that loads the webmap. This also means the popup will be persisted if the webmap is loaded in any other ArcGIS app, such as ArcGIS Pro or an app built with ArcGIS Runtime.

Check out the Point clustering - filter popup features sample, which filters and displays information about a subset of features included in the cluster.

Utility Network

In the previous release, we implemented initial support for utility network, viewing associations, SubtypeGroupLayer, and simple network tracing. For this release, we improved upon network tracing by providing the ability to create custom trace configurations using the TraceConfiguration class. Some of the trace settings that can be configured with this class are functions, barriers, traversability, outputs, and filters. Tracing was also improved to return more relevant asset information after performing a trace. To learn more details about the Utility Network for this release, take a look at the following blog: What's new in Utility Newtork JavaScript API 4.21.

API keys

In this version, we added support for fine-grained control of API keys for closestFacility.solve() and serviceArea.solve() methods. The closestFacility.solve() method uses a new ClosestFacilityParameters.apiKey property, and the serviceArea.solve() method uses a new ServiceAreaParameters.apiKey property. Both methods work with either a global or a fine-grained API key.

Smart mapping updates

All smart mapping functions, including those that generate renderers, popups, labels, statistics, and clustering configurations, now support OGCFeatureLayer.

WebMap persistence updates

Layer effects can be persisted in the WebMap. This allows for easier configuration of effects — you can use the Map Viewer to explore effects and configure them in your WebMap, then those predefined effects will show in any apps where the WebMap is used.

WMSLayer and WMTSLayer can also be persisted in a WebMap at version 4.21.

Content Security Policy

Most CSP directives are supported and certified within the ArcGIS for JavaScript API. The API’s 3D functionality, in addition to the projection engine makes use of WebAssembly (wasm). Wasm requires unsafe-eval in the script-src directive. Adding this in CSP goes against the protection that it is supposed to provide. There is a WebAssembly GitHub proposal that discusses this in more detail. Until this is addressed, applications that make use of these two parts of the API will not be able to take advantage of using CSP.

Documentation updates

Calcite Design System guide page

This new guide page details how you can use the Calcite Design System in your applications. Browse the library of Calcite icons and view samples that use Calcite components with the ArcGIS API for JavaScript.

CIM Symbol Builder - support for lines and polygons

The CIM Symbol Builder has been updated to support line and polygon symbols. Combine different symbol layers, update symbol layer properties, and watch how the CIMSymbol updates. When you've created your perfect symbol, get the symbol JSON and use it to create CIMSymbols in your own applications.

Added Classes, Properties, Methods, Events

Deprecated Classes, Properties, Methods, Events

Breaking changes

• Field configurations can no longer be set on the FeatureForm. Instead, configure the fields via the FieldElement or GroupElement. Set these elements on either the form or feature layer's formTemplate.
• ShadowAccumulation widget has been renamed to ShadowCast widget.
• ShadowAccumulationViewModel has been renamed to ShadowCastViewModel.
• The FeatureForm widget has changed the way it handles a value’s input. Prior to version 4.21, field values were processed and applied using onBlur. Moving forward, this has been updated to use onInput with values getting validated as a user types. Date values will only be applied onInput if the value is valid. It will subsequently be committed or discarded onBlur based on the final value.

The following classes, methods, properties and events have been deprecated for at least 2 releases and have been removed from the API:

Please refer to the Breaking changes guide topic for a complete list of breaking changes across all releases of the 4x API.

Bug fixes and enhancements

• BUG-000132900: Fixed an issue with WMTSLayer requesting tiles that were not within the coverage of the TileMatrix.
• BUG-000135406: Fixed an issue where switching renderers on a FeatureLayer with clustering enabled did not update the symbology until the Map was panned or zoomed.
• BUG-000137190: Fixed an issue where labels in a VectorTileLayer render irrespective of the style layer's visibility range.
• BUG-000140810: Groups within the FeatureForm widget no longer fail to open read-only fields when set to display sequentially.
• BUG-000141284: Fixed an issue with WMSLayer where custom parameters would be added to the GetLegendGraphic request with a ? instead of an &, causing the request to fail.
• BUG-000141323: Fixed an issue with SketchViewModel where creating a polygon with defaultCreateOptions.hasZ = true failed with cannot read property '0' of undefined. This also affected the Editor on polygon layers with hasZ = true.
• BUG-000141553: Fixed an issue where the locationToAddress() method was missing a URL parameter.
• BUG-000141653: Fixed an issue where using a Gamepad causes the MapView to stop responding after changing web maps.
• BUG-000141956: Fixed an issue where the doNotLocateOnRestrictedElements property was sent as a standalone parameter rather than as part of DataLayer, NetworkFeatureSet, or NetworkUrl.
• BUG-000142000: Fixed an issue where the listItemCreatedFunction of the LayerList widget gets called an excessive number of times.
• BUG-000142027: Fixed an issue with the DistanceMeasurement2D widget returning incorrect readings at very large scales.
• BUG-000142800: Fixed an issue with 2D FeatureLayer labels failing to display for one layer when there are overlapping identical layers.
• Esri Community - 1085769: Fixed a regression with being unable to create a single point multipoint graphic with SketchViewModel.
• Esri Community - 1086457: Fixed an issue where editingEnabled was returning true even if the feature layer wasn't editable.
• Esri Community - 1087391: Fixed an issue where CIMTextSymbols were getting cut off within a CIMSymbol.
• Esri Community - 1093495: Fixed an issue where primitiveOverrides were not being applied to CIMPictureMarker symbol layers in CIMSymbols.
• Fixed an issue in SketchViewModel where scaling graphics was still possible despite setting enableScaling = false.
• Fixed an issue when signing into multiple authenticated layers from federated sources. The modal dialog now displays as expected, i.e. one at a time, when the user clicks cancel.
• Fixed an issue where layer effects were not being applied to ImageryLayer.
• Fixed an issue where Layer.fromPortalItem() was not working with WMTSLayer portal items.
• Fixed an issue where Legend didn't correctly display above and below theme when per feature transparency was enabled.
• Fixed an issue where Legend didn't correctly display custom symbols.
• Fixed an issue where Legend flickered when using a slider to adjust transparency on a MapImageLayer sublayer.
• Fixed an issue where MapImageLayer made multiple requests for legends.
• Fixed an issue where returnDistinctValues queries returned incorrect results when used on LayerViews.
• Fixed an issue where VectorFieldRenderer would not update when used with the TimeSlider widget.
• Fixed an issue where websocket events were not being emitted when StreamLayer.geometryDefinition was being set on a map pan.
• Fixed an issue with CIMSymbol where the tintColor was not applied to CIMPictureMarker symbols.
• Fixed an issue with clustered labels where they didn't render properly on edges of the view.
• ENH-000138022: Added the hideLayersNotInCurrentView property to the Legend widget. This property determines whether the Legend displays layers visible in the current view extent.
• ENH-000131075: Added the orderBy property to the FeatureLayer to order and draw features based on attribute values.
• Esri Community - 1069711: Enhanced the CoordinateConversion widget's Copy to clipboard popup to be smaller and more subdued.
• Enhanced the geodesicUtils.geodesicDistance() method to return azimuth and reverseAzimuth values in the range of 0-360°.
• Improved navigation performance in 3D.
• Updated the Editor widget to temporarily disable either the Update or Add buttons after onClick. This stops duplicate applyEdits requests from being sent if either of these buttons are accidentally clicked before the edit process is finished.
• WFSLayer can now be added to a web scene.

Additional packages

Version 4.21 of the ArcGIS API for JavaScript uses ArcGIS Arcade 1.15 (since 4.21).

Downloads

The downloads for version 4.21 of the API and the SDK will be available on October 6th. The API installation has been simplified, so you no longer need to modify any files. Just download and start using. We've also added a test application to the API downloads to quickly verify your API installation.

Previous Releases