▾
import "@arcgis/map-components/components/arcgis-utility-network-trace-analysis";- Inheritance
- ArcgisUtilityNetworkTraceAnalysis→
HTMLElement
- Since
- ArcGIS Maps SDK for JavaScript 5.0
Overview
The Utility Network Trace Analysis component allows users to run traces and view trace results in a utility network.
- The component supports selecting a utility network and a named trace configuration in that utility network. Both the utility network and trace configuration must be stored in the map.
- Trace locations (starting points, stopping points, and barriers) are set by selecting features on the view.
- When a subnetwork-based trace is selected, the component displays the domain, tier, and target tier specified by the selected named trace configuration.
- If the user selects a subnetwork trace with a specified subnetwork name, the component provides an option to choose a subnetwork name instead of starting location(s) to run the trace with.
Supported trace types are: connected, upstream, downstream, shortest-path (deprecated), path, subnetwork, subnetwork-controller, loops, and isolation.
The shortest path trace type is deprecated with ArcGIS Pro 3.7 and ArcGIS Enterprise 12.1.
While the shortest path trace will continue to function and be an option until the next major release, it is recommended to use the path trace to return the shortest path. The path trace provides the same functionality to return a shortest path result while offering additional capabilities to find paths in your network.
The component can display the following from a trace result: elements (as features), aggregated geometries, and function results.
The Utility Network Trace Analysis component does not support the following:
- Proxied feature services or feature services that utilize stored credentials.
- The
circuittrace type or thepathsandcircuitsresult types. - Setting grouping properties
firstUnitandlastUnitfor trace locations in a telecom domain network. If a grouped object is used as a trace location, itsfirstUnitandlastUnitattributes are not used in the trace.
Working with nonspatial objects
The Utility Network Trace Analysis component supports selecting nonspatial objects as trace locations by traversing associations.
When selecting a trace location or viewing a trace result feature, information about the feature is displayed according to the PopupTemplate of the layer that the feature belongs to. If the feature's layer has no PopupTemplate, a default template is used to display the feature's attributes.
To select a nonspatial object as a trace location, first select a spatial feature on the map that is associated with the target nonspatial object. The spatial feature's layer must have a PopupTemplate that includes a UtilityNetworkAssociationsContent. Navigate through the spatial feature's associations to the target nonspatial object, then add the object as a trace location.
Examples
This component can be used slotted into an arcgis-map:
<arcgis-map item-id="471eb0bf37074b1fbb972b1da70fb310"> <arcgis-utility-network-trace-analysis slot="bottom-left"></arcgis-utility-network-trace-analysis></arcgis-map>Alternatively, this component can be used outside of a map by providing a referenceElement:
<calcite-shell> <calcite-shell-panel slot="panel-start" position="start" width="l"> <arcgis-utility-network-trace-analysis reference-element="#map-element"></arcgis-utility-network-trace-analysis> </calcite-shell-panel> <arcgis-map id="map-element" item-id="471eb0bf37074b1fbb972b1da70fb310"></arcgis-map></calcite-shell>Note: Sign in to access the data in this demo, U/P: viewer01/I68VGU^nMurF
Demo
Properties
| Property | Attribute | Type |
|---|---|---|
| | ArcgisFeaturesNext["actions"] | undefined | |
| deprecated | aggregated-geometry-graphics-color | |
| aggregated-geometry-results-graphics-color | ||
| aggregated-geometry-results-size | ||
| auto-destroy-disabled | ||
| disable-highlight-feature-results | ||
| readonly | | |
| hide-action-bar | ||
| hide-clear-results-count | ||
| hide-feature-results | ||
| hide-graphics | ||
| hide-placeholder | ||
| include-default-actions-disabled | ||
| deprecated reflected | label | |
| | ||
| reference-element | ||
| readonly | | |
| readonly | | |
| | ||
| readonly | | Graphic[] |
| |
actions
- Type
- ArcgisFeaturesNext["actions"] | undefined
- Since
- ArcGIS Maps SDK for JavaScript 5.2
A collection of action button or action toggle objects. Each action may be executed by clicking the icon or image symbolizing them.
There is a default Zoom To action styled with a magnifying glass icon to zoom in four LODs and center the map on the selected feature. This default action can be removed by setting includeDefaultActionsDisabled to true, or by setting the overwriteActions property to true in a PopupTemplate.
The order of each action is the order in which they appear in the actions Collection. The @arcgisTriggerAction event fires each time an action is clicked.
aggregatedGeometryGraphicsColor
- Type
- Color
The color used to render graphics for aggregated geometries in trace results.
- Attribute
- aggregated-geometry-graphics-color
aggregatedGeometryResultsGraphicsColor
- Type
- Color
- Since
- ArcGIS Maps SDK for JavaScript 5.2
The color used to render graphics for aggregated geometries in trace results, specified as a Color object.
Aggregated geometry is only rendered if the trace configuration specifies aggregated geometry as a result type.
Default color is #FFFF00.
- See also
- Attribute
- aggregated-geometry-results-graphics-color
- Examples
Set the default aggregated geometry graphics color to lime green in JavaScript.
const traceElement = document.querySelector("arcgis-utility-network-trace-analysis");traceElement.aggregatedGeometryResultsGraphicsColor = new Color("lime");Set the default aggregated geometry graphics color to red in HTML.
<arcgis-map item-id="967a4180aa6c46b68996ea9406e8a606"><arcgis-utility-network-trace-analysis slot="bottom-left" aggregated-geometry-results-graphics-color="red"></arcgis-utility-network-trace-analysis></arcgis-map>
aggregatedGeometryResultsSize
- Type
- number
- Since
- ArcGIS Maps SDK for JavaScript 5.2
The size in points used to render graphics for aggregated geometries in trace results.
Aggregated geometry is only rendered if the trace configuration specifies aggregated geometry as a result type.
- Attribute
- aggregated-geometry-results-size
- Default value
- 12
- Example
Set the default aggregated geometry graphics size to 8 points.
const traceElement = document.querySelector("arcgis-utility-network-trace-analysis");traceElement.aggregatedGeometryResultsSize = 8;
autoDestroyDisabled
- Type
- boolean
If true, the component will not be destroyed automatically when it is disconnected from the document. This is useful when you want to move the component to a different place on the page, or temporarily hide it. If this is set, make sure to call the destroy() method when you are done to prevent memory leaks.
- Attribute
- auto-destroy-disabled
- Default value
- false
- Example
- <arcgis-utility-network-trace-analysis auto-destroy-disabled></arcgis-utility-network-trace-analysis>utilityNetworkTraceAnalysisElement.autoDestroyDisabled = true;
disableHighlightFeatureResults
- Type
- boolean
Whether to disable highlighting trace result features on the map.
If true, the features returned by a trace will not be highlighted on the map.
- Attribute
- disable-highlight-feature-results
- Default value
- false
- Example
Disable highlighting trace result features.
<arcgis-map item-id="471eb0bf37074b1fbb972b1da70fb310"><arcgis-utility-network-trace-analysis disable-highlight-feature-results slot="top-right"></arcgis-utility-network-trace-analysis></arcgis-map>
flowItems
- Type
- Collection
- Since
- ArcGIS Maps SDK for JavaScript 5.2
Additional Calcite Flow Items displayed in the Results tab.
Add or remove native calcite-flow-item elements through this Collection.
hideActionBar
- Type
- boolean
- Since
- ArcGIS Maps SDK for JavaScript 5.2
Indicates whether to hide the action bar that holds the feature's arcgis-features-next.actions when selecting trace locations and viewing trace result features.
- Attribute
- hide-action-bar
- Default value
- false
hideFeatureResults
- Type
- boolean
Whether to hide feature results in the results tab.
If true, when features are returned by a trace, they will not be visible in the results tab. A message will be displayed in its place indicating that features were returned by the trace, but are not visible in the results pane. This string can be overridden with the messageOverrides property.
- Attribute
- hide-feature-results
- Default value
- false
- Examples
Do not show features in the results tab.
<arcgis-map item-id="471eb0bf37074b1fbb972b1da70fb310"><arcgis-utility-network-trace-analysis hide-feature-results slot="top-right"></arcgis-utility-network-trace-analysis></arcgis-map>Override the message displayed in the results tab when features are hidden.
const traceElement = document.querySelector("arcgis-utility-network-trace-analysis");traceElement.messageOverrides = { resultFeaturesAreHidden: "Feature results were sent to the results window." };
hidePlaceholder
- Type
- boolean
- Since
- ArcGIS Maps SDK for JavaScript 5.2
Whether to hide the placeholder string when feature results are hidden in the results tab.
When this property and hideFeatureResults are both set to true,
nothing is rendered for trace result elements. However, features are still queried and are available through
traceResultFeatures.
- Attribute
- hide-placeholder
- Default value
- false
- Example
Hide the placeholder when feature results are hidden.
<arcgis-map item-id="471eb0bf37074b1fbb972b1da70fb310"><arcgis-utility-network-trace-analysishide-feature-resultshide-placeholderslot="top-right"></arcgis-utility-network-trace-analysis></arcgis-map>
includeDefaultActionsDisabled
- Type
- boolean
- Since
- ArcGIS Maps SDK for JavaScript 5.2
Indicates whether default actions are disabled (hidden) when
selecting trace locations and viewing trace result features.
This property must be set to true to disable default actions.
- Attribute
- include-default-actions-disabled
- Default value
- false
referenceElement
- Type
- ArcgisReferenceElement | string | undefined
By assigning the id attribute of the Map or Scene component to this property, you can position a child component anywhere in the DOM while still maintaining a connection to the Map or Scene.
- Attribute
- reference-element
traceError
- Since
- ArcGIS Maps SDK for JavaScript 5.2
The error from the most recent failed trace attempt. Read this property when
@arcgisError fires.
This property is reset to undefined before a new trace runs.
traceResult
- Type
- TraceResult | undefined
- Since
- ArcGIS Maps SDK for JavaScript 5.2
The TraceResult
returned by the most recent successful trace. This property is reset to undefined before a new trace runs.
traceResultFeatures
- Type
- Graphic[]
An array of features returned by the trace result.
This array is populated if the trace returned element results.
When @arcgisTraceResultFeaturesReady is raised, trace result features are available. When a new trace has been run, or the trace results are cleared, this array is cleared.
view
The view associated with the component.
Note: The recommended approach is to fully migrate applications to use map and scene components and avoid using MapView and SceneView directly. However, if you are migrating a large application from widgets to components, you might prefer a more gradual transition. To support this use case, the SDK includes this
viewproperty which connects a component to a MapView or SceneView. Ultimately, once migration is complete, the arcgis-utility-network-trace-analysis component will be associated with a map or scene component rather than using theviewproperty.
Methods
| Method | Signature |
|---|---|
| inherited | componentOnReady(): Promise<this> |
| destroy(): Promise<void> |
componentOnReady
- Signature
-
componentOnReady (): Promise<this>
Creates a promise that resolves once the component is fully loaded.
- Returns
- Promise<this>
- Example
- const arcgisUtilityNetworkTraceAnalysis = document.createElement("arcgis-utility-network-trace-analysis");document.body.append(arcgisUtilityNetworkTraceAnalysis);await arcgisUtilityNetworkTraceAnalysis.componentOnReady();console.log("arcgis-utility-network-trace-analysis is ready to go!");
Events
| Name | Type |
|---|---|
| deprecated | |
| CustomEvent<{ name: "aggregatedGeometryGraphicsColor" | "aggregatedGeometryResultsGraphicsColor" | "hideGraphics" | "state" | "traceError" | "traceResult"; }> | |
arcgisError
arcgisError: CustomEvent<void> - Since
- ArcGIS Maps SDK for JavaScript 5.2
Fires when the selected named trace configuration's trace type or trace configuration is unavailable, or when an error occurs while executing a trace. The error is available through traceError before this event fires. This event does not include an error in its payload.
- Example
- const traceElement = document.querySelector("arcgis-utility-network-trace-analysis");traceElement.addEventListener("arcgisError", () => {console.error("Trace failed:", traceElement.traceError);});
arcgisHideGraphicsChange
arcgisHideGraphicsChange: CustomEvent<boolean> Fires when the user toggles displaying aggregated geometry results in the result pane. Event payload contains a boolean representing whether the aggregated geometry graphics are hidden. If true, the aggregated geometry graphics are hidden on the view.
- Example
- const traceElement = document.querySelector("arcgis-utility-network-trace-analysis");traceElement.addEventListener("arcgisHideGraphicsChange", (event) => {const hideGraphics = event.detail;console.log(hideGraphics);});
arcgisPropertyChange
arcgisPropertyChange: CustomEvent<{ name: "aggregatedGeometryGraphicsColor" | "aggregatedGeometryResultsGraphicsColor" | "hideGraphics" | "state" | "traceError" | "traceResult"; }> Emitted when the value of a property is changed. Use this to listen to changes to properties.
arcgisReady
arcgisReady: CustomEvent<void> Emitted when the component associated with a map or scene view is ready for user interaction.
arcgisTraceResultClear
arcgisTraceResultClear: CustomEvent<void> Fires when trace results and errors are cleared from the results tab.
- Example
- const traceElement = document.querySelector("arcgis-utility-network-trace-analysis");traceElement.addEventListener("arcgisTraceResultClear", (event) => {console.log("Trace result was cleared.");});
arcgisTraceResultFeaturesReady
arcgisTraceResultFeaturesReady: CustomEvent<void> Fires when the trace result features are ready. Check property traceResultFeatures for the trace result features.
- Example
- const traceElement = document.querySelector("arcgis-utility-network-trace-analysis");traceElement.addEventListener("arcgisTraceResultFeaturesReady", (event) => {const resultFeatures = traceElement.traceResultFeatures;console.log(resultFeatures);});
arcgisTraceResultReady
arcgisTraceResultReady: CustomEvent<void> - Since
- ArcGIS Maps SDK for JavaScript 5.2
Fires when the trace result is ready.
- Example
- const traceElement = document.querySelector("arcgis-utility-network-trace-analysis");traceElement.addEventListener("arcgisTraceResultReady", (event) => {console.log("Trace result is ready.");});
arcgisTriggerAction
arcgisTriggerAction: CustomEvent<ActionEvent> - Since
- ArcGIS Maps SDK for JavaScript 5.2
Emitted when an action is triggered on the component.
Slots
| Name | Description |
|---|---|
| Slot for instances of arcgis-utility-network-trace-results, for displaying the results of one or more traces. |
results
Slot for instances of arcgis-utility-network-trace-results, for displaying the results of one or more traces.