Release notes for 4.22

December 2021

AnimatedFlowRenderer

The AnimatedFlowRenderer (released in beta) allows you to visualize your UV or MagDir raster data with animated streamlines. This renderer can be used to visualize flow direction and magnitude information in ImageryLayers and ImageryTileLayers in a MapView. The direction of the raster defines the direction of movement, and the magnitude defines the visible length of the streamline.

This new renderer also works well with layer effects and blendModes, as shown in this sample: AnimatedFlowRenderer with effects and blending. The AnimatedFlowRenderer is still in beta. We plan to add more support in the upcoming releases for things like the TimeSlider widget, visual variables, and more!

3D updates

Weather

Make your scenes more realistic by adding weather. A new property on SceneView.environment allows you to configure a range of weather conditions from sunny to cloudy and even foggy. Adjust cloud cover, fog strength and time-of-day to enjoy a new atmosphere and weather visualizations at ground level.

Use this new sample to see San Francisco in different weather conditions.

Line patterns

Use patterns on lines or polygon outlines to symbolize additional information, for example to differentiate between planned and existing features. A new class LineStylePattern3D provides a variety of styles compatible with existing 2D capabilities. Patterns can be driven by attribute values and combined with visual variables.

Examples of different line patterns are used in the following hiking map sample.

Voxel layer

VoxelLayer (released in beta) allows you to display multidimensional volumetric data in local scenes. Powered by WebGL2 you can now visualize atmospheric or oceanic data, geological underground models, or space-time cubes using voxel layers. Upcoming releases will add support for explorative tools and popups to inspect individual voxels.

A new sample visualizes sea water temperature in the Caribbean at various depths.

Improved performance and stability

As part of our ongoing efforts to improve performance, we reduced memory usage up to 50% for applications with FeatureLayers using simple polygons and simple polygon outlines by streamlining how vertex data is encoded. This will help increase stability on resource-constrained devices such as phones and tablets.

Visualization

Faster smart mapping statistics

Logic for calculating unique values, summary statistics, class breaks, and histogram in smart mapping for client-side layers moved from the main thread to workers. This prevents UI freezing and makes statistic calculations 6x faster than in previous versions of the API. This applies to statistic calculations in FeatureLayers created from client-side graphics, CSVLayer, GeoJSONLayer, WFSLayer, OGCFeatureLayer, and any service-based FeatureLayer using an Arcade expression in its renderer.

In the animation below, note the UX improvement in the ArcGIS Online Map Viewer as it generates statistics for histograms and class breaks much faster when using version 4.22 of the API than version 4.21.

Legend support for layer effects

The Legend widget now supports layer effects in operational layers. It does not support FeatureEffect. Compare the following images showing the Legend for a layer that has the invert effect applied. In 4.22, the Legend much more accurately depicts what is rendered on the map.

4.21	4.22

More than 500 color ramps now available

We added 167 colorblind-friendly color ramps to the Smart Mapping color APIs. These ramps include dozens of newly designed above-and-below ramps that emphasize middle values in addition to the values above and below the critical middle value. Traditionally, above and below color ramps use neutral hues that blend in with the basemap for the middle values, making it difficult to see those features. There are many scenarios where that is desirable (i.e. where the important values are further from the center). However, making the middle values more obvious can help users to easily see the locations of all data points, especially when middle values are important to highlight in addition to the extremes.

These new color ramps can be accessed in the following ways:

1. As color schemes with suggested symbol properties based on geometry type and desired background color.
2. As an array of colors via the colorRamps module.
3. Directly from the Esri Color Ramps topic. On this page, you can preview all available ramps and filter them based on theme, color, and background and copy and paste the colors directly into your app.

High density data guide topics

We added a new chapter to the Visualization guide called High density data. This chapter demonstrates seven effective ways you can visualize data with overlapping features. Covered topics include the following:

• Clustering
• Heatmap
• Opacity
• Bloom
• Aggregation
• Thinning
• Visible scale range

Trace how resources flow through a utility network

The new UtilityNetworkTrace widget allows users to run a trace in a WebMap containing a Utility Network. In order to use the UtilityNetworkTrace widget, the WebMap must be published with Named Trace Configurations, which are supported as of ArcGIS Enterprise 10.9. Input flags (starting points and barriers) can be set via the widget. The starting points define the location in the network where the trace begins, and the barrier points mark the locations to stop the trace. The UtilityNetworkTrace widget can execute one or more traces simultaneously. Refer to the blog "Trace a Utility Utility Network with the ArcGIS API for JavaScript" in order to learn more about tracing with the UtilityNetworkTrace widget.

Improved polyline labels

We improved the polyline labeling experience by giving developers more control and configuration options. Previously, the API only allowed for a "curved" labelPosition, which meant each of the label characters followed the curve of the polyline. Now, you can choose between "curved" or "parallel", with "parallel" meaning that the label characters will always be straight, and the orientation of the label will be based on the polyline curve angle.

We also added a repeatLabelDistance property, which indicates the distance between labels on a polyline. The repeatLabel must be true for repeatLabelDistance to be honored. If repeatLabel is false, the label will only appear once per polyline segment. Lastly, allowOverrun specifies whether or not a label can overrun the geometry feature being labeled, e.g. after the end of a polyline segment.

See the images below to compare how the upgraded polyline labeling looks:

4.21 - default configuration	4.22 - labelPosition = "parallel”, repeatLabelDistance = 200

Popup updates

Only show popup for visible features

As of version 4.22, the popup only displays for features visible in the map. If there is a filter applied, only the features that pass the filter will return a popup. We will continue to improve popup behaviors in coming releases.

The map in the following images is filtered by Season = "Winter". Notice how in 4.21, all features return a popup, but in 4.22 only the filtered features return a popup.

4.21 - all features returned	4.22 - only filtered features returned

The popup only makes one query to the server for missing attributes if not all required attributes are available on the client. No server requests are made if all attributes are available on the client. This should translate into a better performance.

Use Arcade to create popup content elements

PopupTemplate now supports a new content type: ExpressionContent. ExpressionContent allows you to use Arcade to create popup content elements, including rich text with HTML, tables, and charts.

Defining dynamic popup content in Arcade expressions as opposed to JavaScript means you can save the popup template in a webmap and load it in other ArcGIS apps, providing a consistent user experience for the same webmap. This feature is especially useful in layers representing aggregated data.

Prior to this release, if you wanted to create a chart from values returned from an Arcade expression, you would have to write a separate expression for each data point in the chart's media infos. With this change, you can create multiple charts with a single expression, allowing you to write more efficient code. Creating charts with ExpressionContent also allows popup content to render 3-4 times faster than when using multiple expressions in a MediaContent element. The increased performance improvement depends on the number and complexity of expressions you would have had to use in a MediaContent element.

Check out these examples of how to use Arcade to create popup content elements.

• Create popup charts from Arcade expressions
• Popup charts for point clusters

Better defaults for popup attachments

Attachment content within Popups now uses auto as the default displayType instead of list. If the feature layer's capabilities support resizing attachments, the content will display in preview mode. If not, it will revert to displaying the attachment as a list.

The images below show the same popup attachment. Take note that the 4.22 version displays as preview since the layer supports resizing attachments.

Default displayType, layer supports attachment resizing - 4.21	Default displayType, layer supports attachment resizing - 4.22

Feature ordering

Improved support for overlapping polygon features

We improved how overlapping polygon features are displayed in the map. Previously, polygon outlines were rendered after polygon fills, causing the outlines to display on top. This made it difficult to differentiate boundaries for overlapping polygons. At 4.22, we now render solid outlines and fills simultaneously for each polygon in the order that each feature is displayed in the map.

4.21	4.22

Support for feature ordering in WFSLayer

WFSLayer added the orderBy property to allow you to configure the order features are drawn in the view. The orderBy property was added to other layer types at version 4.21.

Layer updates

Better support for CSVLayer and GeoJSONLayer

We've added the following enhancements and improvements to CSVLayer and GeoJSONLayer.

• CSVLayer and GeoJSONLayer can now be refreshed, meaning that you can fetch new data after those layers are initialized and loaded to the map.
• We added support for customParameters on both CSVLayer and GeoJSONLayer. This property can be used to set additional query parameters when the layer is initialized or refreshed. Check out this sample to see refresh and customParameters in action on the GeoJSONLayer.
• GeoJSONLayer now supports string and number feature ids in its objectIdField.
• GeoJSONLayer now can be persisted in a WebMap and WebScene.

Raster layers

At this release, we added time support for ImageryTileLayer and WCSLayer.

For imagery centric workflows that use image coordinate systems, we added computeAngles() and computePixelSpaceLocations() methods on ImageryLayer and imageService. These methods can help imagery analysts know the corresponding up and north angles and the pixel space locations for image coordinates.

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.

• GeoRSSLayer is now can be refreshed by setting its refreshInterval property or calling refresh() method.
• CSVLayer and GeoJSONLayer can also be refreshed now. See details from the previous section.
• All refreshable layers emit a refresh event that will indicate when the data has been refreshed. This event now has a payload to indicate if the layer's data has changed.

Widget updates

Easier graphic selection for Sketch

Using Sketch and SketchViewModel, you can select and move point graphics in the map by clicking anywhere on the symbol. Previously, it was only possible to move a point graphic directly from the location of the point geometry. These changes are specifically for CIMSymbol, PictureMarkerSymbol, and TextSymbol.

In the images below, the point geometry is represented by an orange circle. In 4.22, you can move the graphic by clicking anywhere on the symbol, instead of only on the point geometry.

4.21	4.22

Time-enabled bookmarks

The Bookmarks widget now supports bookmarks that are time-enabled, or have a specified time extent. When a time-enabled bookmark is selected in the bookmarks widget, the view's time extent will update to match the time extent of the selected bookmark. A time extent will only be set on a bookmark if View.timeExtent is defined when the bookmark is created.

TimeSlider - get properties from WebMap

TimeSlider.getPropertiesFromWebMap() allows you to easily configure your TimeSlider based on settings saved in a WebMap.

Print widget

By default, the map extent is now preserved instead of the map scale in the printout. This allows you to print all the features in the current view. To preserve the scale instead, use the TemplateOptions.scaleEnabled property.

If using a custom print service, customTextElements are now supported for each print template with the Print widget. The widget calls the Get Layout Templates Info task on the GPServer to discover possible customTextElements values for each template. Values found there will be populated in the Print widget under Advanced options. These values can be overwritten in the Print widget UI, or programmatically using the Print.templateCustomTextElements property. If the Get Layout Templates Info task is named differently on the custom print service, then no values will be populated in the Print widget under Advanced options, and it will not be possible to support customTextElements. In this scenario, we recommend republishing the print service to use the standard Get Layout Templates Info name.

Lastly, the Print widget and print support printing layers with non-standard URLs (e.g. no MapServer, FeatureServer, or ImageServer in the URL) by sending a layerType property in the print request. However, this requires a print service from ArcGIS Server 10.9.1 or later.

Search widget

When the scale of the MapView or SceneView is less than or equal to 300,000, the Search widget supports prioritization of candidates based on their distance from the center of the view by passing in the location parameter. This default behavior can now be changed by using the localSearchDisabled property.

Feature effect support for layers

We added featureEffect to CSVLayer, GeoJSONLayer, FeatureLayer, OGCFeatureLayer and WFSLayer, which allows you to draw attention to features of interest. The corresponding layerViews of those layers also support the featureEffect property, and it should be used in place of effect. Feature effects that are set on layers can be persisted in a WebMap.

MapView.hitTest improvements for GraphicsLayer

MapView.hittest now returns all features that intersect the specified screen coordinates from a GraphicsLayer. Previously, it only returned the topmost feature from a GraphicsLayer. We will implement this behavior for other layers in upcoming releases.

Updates to identify operation

The identify operation was enhanced to add support for dynamic layers and time extent. We added a sublayers property to allow identify to be performed on MapImageLayer. We also added a timeExtent property to allow users to specify the time extent used by identify.

API keys

• New apiKey property on VectorTileLayer.
• When a global API key is set, the default basemaps displayed in the BasemapGallery widget will default to the basemaps for use with API keys (as defined by the Portal.devBasemapGalleryGroupQuery property).

Support for Bulgarian locale

Version 4.22 adds support for the Bulgarian (bg) locale. See the Localization topic for more information about using different locales.

Content Security Policy

It is no longer necessary to set Dojo's "csp-restrictions" has flag to true when CSP support is needed. Although this flag is no longer necessary, please be aware that there are still limitations when using the JavaScript API with CSP. Please refer to our FAQ section for additional information regarding this.

Added Classes, Properties, Methods, Events

Deprecated Classes, Properties, Methods, Events

Breaking changes

• Attachment elements within popups no longer display list as the default displayType. Instead of list, it defaults to auto.
• Originally released as beta in 4.20, the analysis layers DirectLineMeasurementLayer and AreaMeasurementLayer have been removed in favor of an upcoming implementation.
• Removed justify as a possible value for TextSymbol.horizontalAlignment.
• The basemap parameter in all smartMapping methods within the esri/smartMapping/renderers folder was deprecated at version 4.13 and is now replaced by the view parameter.
• Updated the CoordinateConversion widget by removing the Geometry Service for cases when the coordinateFormatter didn't load due to using an outdated browser. The requestDelay property was removed from the CoordinateConversion widget and CoordinateConversionViewModel.
• Updated the request flow of workers so that an after interceptor receives the expected data type. This means after interceptors that were expecting array-buffers for client-side layers such as GeoJSONLayer and CSVLayer will now receive the expected data types json or text.

The following classes, methods, properties and events have been deprecated for at least 2 releases and have now 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 4.x API.

Bug fixes and enhancements

• BUG-000114502: Fixed an issue where Directions widget did not allow users to add stops on iOS devices.
• BUG-000126231: Fixed an issue where a WMTSLayer would sometimes throw out of bounds requests when used in a SceneView.
• BUG-000126998: Fixed an issue where a WMTSLayer would display blurry tiles when resampled.
• BUG-000127497: Fixed an issue where PictureMarkerSymbol in a feature service had slight blurry texture when displayed in map.
• BUG-000129121: Fixed an issue where WMTSLayer would not redraw all tiles when zoomed in or out if the tiles did not exist at a particular level.
• BUG-000135115: Fixed an issue where TextSymbol with an angle property set was placed at incorrect locations.
• BUG-000135727: Fixed an issue with WMSLayer where the layer would not load if the spatial reference was not defined on the root layer in the service.
• BUG-000135884: Fixed an issue where FeatureTemplate.drawingTool would return the wrong string value if derived from a layer's subtypes.
• BUG-000137602: Fixed an issue where MapView.destroy() would throw errors if the map contained a layer with a different spatial reference than the view.
• BUG-000138336: Fixed an issue where the Popup widget wouldn't honor carriage returns (breaklines) in custom HTML content.
• BUG-000138393: Fixed an issue where Popup was displaying attributes of features that are not visible on the map.
• BUG-000140282: Fixed an issue where it was not possible to select a one-dimensional polygon using the Sketch widget.
• BUG-000140531: Fixed an issue where Multipoint graphics appeared cutoff at tile boundaries.
• BUG-000140562: Fixed an issue with hosting the API under a folder named 'esri'.
• BUG-000141053: Fixed an issue for poor graphic selection and movement experience for graphics with PictureMarkerSymbols and TextSymbols when using Sketch.
• BUG-000141133: Fixed an issue where workers were returning array-buffers in an after interceptor for GeoJSONLayer.
• BUG-000141451: Fixed an issue where ImageryTileLayer could be cropped when printed, depending on the browser window size or the #viewDiv dimensions.
• BUG-000141462: Fixed an issue where the Print widget would show layers in the printed legend that were hidden in the map's legend.
• BUG-000142291: Content Security Policy issue addressed and a few instances of global eval() functions were removed from the API.
• BUG-000142543: Fixed an issue where the Print widget did not support customTextElements.
• BUG-000143043: Fixed an issue with WMTSLayer where duplicate parameters were being included in requests to the service.
• BUG-000143069: Fixed an issue where VectorTileLayer failed to display if it has style-layers with the same name but with different case sensitivity.
• BUG-000143284: Fixed an issue where a point FeatureLayerView's updating status remained true if the layer was not visible within the map view.
• BUG-000143467: Fixed an issue where some point symbols were getting cut off at tile boundaries when panning or zooming in the map.
• BUG-000143654: Fixed an issue with the documentation for the Search widget using the deprecated locator property in code snippets.
• BUG-000143660: Fixed an issue with the documentation for the Conversion class not having a constructor section.
• BUG-000144019: Fixed an issue where the observer position would not update the lines in Line of Sight widget when changed programmatically.
• BUG-000144099: Fixed an issue where the API key was not being sent for some basemaps with labels when printing.
• BUG-000144207: Fixed an issue where labels on client-side FeatureLayer did not load until there was an interaction with the view.
• BUG-000144287: Fixed an issue where printing client-side features using ClassBreaksRenderer failed to print labels.
• Esri Community - 1007866: Fixed an issue where CSVLayer.popupTemplate was not displaying a popup option for overlapping features if the csv file has a field called ObjectID.
• Esri Community - 1101128: Fixed an issue where a CIMPictureMarker would not render when the URL was an SVG.
• Fixed an issue where a map was flashing when it was clicked if it had a VectorTileLayer with an effect.
• Fixed an issue where Layer.opacity was impacting the highlight opacity.
• Fixed an issue where the DirectionsFeatureSet.mergedGeometry had incorrect hasM and hasZ values.
• Fixed an issue where the View.timeExtent was not being honored by TimeSlider.timeExtent.
• Fixed an issue where the - sign in latitude/longitude values were incorrectly displayed with rtl languages in the CoordinateConversion widget.
• ENH-000107617: Updated the LayerList widget with actions sample to demonstrate how to add an opacity slider to the LayerList widget.
• ENH-000126408: Added a support to refresh GeoJSONLayer and CSVLayer.
• ENH-000128160: Added a support to refresh GeoRSSLayer.
• ENH-000133610: Updated the Compass widget's tooltip to now display Reset map orientation instead of Reset compass orientation.
• ENH-000137806: Added a support for customParameters on StreamLayer.
• ENH-000142044: Improved graphic selection and movement behavior for graphics with PictureMarkerSymbols and TextSymbols when using Sketch.
• ENH-000142792: Added better code snippets for the query documentation.
• Added median to SummaryStatisticsResult.
• Enhanced the polygon labelPlacement behavior to better place labels in the center of a polygon.
• Enhanced the Print widget so that the map extent is preserved by default in the printout.
• Enhanced the WMTSLayer by adding support for the TopLeftCorner parameter within TileMatrix.
• Fixed an issue where the feature count within a Popup would overflow when adjusting a browser's zoom and window size.
• The ellipsis button no longer displays within a Popup if actions within it are not visible.
• When using ESM, the Editor widget no longer throws errors when creating a new feature and discarding edits.

Additional packages

Version 4.22 of the ArcGIS API for JavaScript uses ArcGIS Arcade 1.16 (since 4.22).

Version 4.22 of the ArcGIS API for JavaScript uses Calcite Design System (Beta), version 1.0.0-beta.69.

Downloads

The downloads for version 4.22 of the API and the SDK will be available on December 22nd.

Previous Releases