arcgis-utility-network-trace-results | References | ArcGIS Maps SDK for JavaScript

ESM

import "@arcgis/map-components/components/arcgis-utility-network-trace-results";

Inheritance: ArcgisUtilityNetworkTraceResults→HTMLElement

Since: ArcGIS Maps SDK for JavaScript 5.2

The Utility Network Trace Results component displays the outcome of a single utility network trace, including its results, an empty result, or an error.

This component displays results for the following trace result types: elements, aggregated geometries, and functions.

Each result type is displayed by a result item component. By default, this component displays the result items for the result types returned by the trace. To choose which result items are displayed or configure their properties individually, add the elements result item, aggregated geometry result item, or functions result item to this component's default slot. When the default slot has content, the component displays the slotted content instead of the default result items.

Use in the trace analysis component's results slot

By default, the arcgis-utility-network-trace-analysis component displays aggregated geometry, elements, and functions in its results tab when those result types are returned by the trace. You do not need to slot a results component for this default display configuration. Only slot this component into the trace analysis component's results slot when you want to customize the result items in the results tab: choose which items are displayed, configure their properties, or add custom result items.

When this component is slotted into the results slot of the trace analysis component, the parent trace analysis component sets the trace result, trace error, utility network, and view properties.

See the custom result items example.

Use in a custom app outside the trace analysis component

See arcgis-utility-network-trace-results-pane for guidance and examples of displaying multiple trace results outside the trace analysis component.

See also

Examples

The following example customizes the display of element results. Other result types are not displayed because the component's default slot contains only an element result item.

<arcgis-map item-id="471eb0bf37074b1fbb972b1da70fb310">
  <arcgis-utility-network-trace-analysis slot="bottom-left">
    <arcgis-utility-network-trace-results slot="results">
      <arcgis-utility-network-trace-elements-result-item
        heading="Feature results"
        hide-action-bar
      ></arcgis-utility-network-trace-elements-result-item>
    </arcgis-utility-network-trace-results>
  </arcgis-utility-network-trace-analysis>
</arcgis-map>

Using the markup above, register these listeners before running a trace to respond to result and error changes and access queried features after all result items finish processing.

const results = document.querySelector("arcgis-utility-network-trace-results");

results.addEventListener("arcgisPropertyChange", (event) => {
  if (event.target !== results) {
    return;
  }

  if (event.detail.name === "traceResult") {
    console.log("Trace result:", results.traceResult);
  } else if (event.detail.name === "traceError") {
    if (results.traceError) {
      console.error("Trace error:", results.traceError);
    }
  }
});

results.addEventListener("arcgisResultsReady", () => {
  console.log("Result items ready:", results.traceResultFeatures);
});

Properties

Property	Attribute	Type
actions		ArcgisFeaturesNext["actions"] \| undefined
aggregatedGeometryResultsGraphicsColor	aggregated-geometry-results-graphics-color	Color
aggregatedGeometryResultsSize	aggregated-geometry-results-size	number
autoDestroyDisabled	auto-destroy-disabled	boolean
disableHighlightFeatureResults	disable-highlight-feature-results	boolean
expandable	expandable	boolean
expanded	expanded	boolean
heading	heading	string \| undefined
hideActionBar	hide-action-bar	boolean
hideFeatureResults	hide-feature-results	boolean
hideGraphics	hide-graphics	boolean
hidePlaceholder	hide-placeholder	boolean
includeDefaultActionsDisabled	include-default-actions-disabled	boolean
layers		Layer[]
messageOverrides		Record<string, unknown> \| undefined
numFeatureResults readonly		number
referenceElement	reference-element	ArcgisReferenceElement \| string \| undefined
state readonly		UtilityNetworkTraceResultItemState
traceError		EsriError<TraceErrorDetails> \| undefined
traceResult		TraceResult \| undefined
traceResultFeatures readonly		Graphic[]
utilityNetwork		UtilityNetwork \| undefined
view		MapView \| undefined

actions

Property

Type: ArcgisFeaturesNext["actions"] | undefined

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.

See also

aggregatedGeometryResultsGraphicsColor

Property

Type: Color

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. The default is yellow with 0.6 opacity.

Attribute: aggregated-geometry-results-graphics-color

aggregatedGeometryResultsSize

Property

Type: number

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. The default is 12.

Attribute: aggregated-geometry-results-size
Default value: 12

autoDestroyDisabled

Property

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-results auto-destroy-disabled></arcgis-utility-network-trace-results>

utilityNetworkTraceResultsElement.autoDestroyDisabled = true;

disableHighlightFeatureResults

Property

Type: boolean

Whether to disable highlighting trace result features on the map.

Disabling highlights does not prevent the component from querying features or affect aggregated geometry graphics.

Attribute: disable-highlight-feature-results
Default value: false

expandable

Property

Type: boolean

Whether the component can be expanded and collapsed.

Attribute: expandable
Default value: false

expanded

Property

Type: boolean

Whether the component and its contents are expanded when expandable is true.

Attribute: expanded
Default value: false

heading

Property

Type: string | undefined

The description displayed below the component's localized trace results heading.

Attribute: heading

hideActionBar

Property

Type: boolean

Whether to hide the action bar that holds the feature's arcgis-features-next.actions when viewing trace result features.

See also

Attribute: hide-action-bar
Default value: false

hideFeatureResults

Property

Type: boolean

Whether to hide the elements result item and its features list.

When true, the component displays a placeholder instead. Features are still queried and remain available from traceResultFeatures. This property does not disable highlighting; use disableHighlightFeatureResults to hide feature highlights.

Attribute: hide-feature-results
Default value: false

hideGraphics

Property

Type: boolean

Whether to hide the aggregated geometry graphics from the map when the trace result contains aggregated geometry results.

Hidden graphics remain available from the arcgis-utility-network-trace-aggregated-geometry-result-item component.

Attribute: hide-graphics
Default value: false

hidePlaceholder

Property

Type: boolean

Whether to hide the placeholder shown when feature results are hidden.

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

includeDefaultActionsDisabled

Property

Type: boolean

Whether default actions are disabled (hidden) when viewing trace result features. This property must be set to true to disable default actions.

See also

arcgis-features-next.includeDefaultActionsDisabled

Attribute: include-default-actions-disabled
Default value: false

layers

Property

Type: Layer[]

The utility network layers and tables used to query trace result features.

When the array is empty, the component uses layers and tables in the map that belong to utilityNetwork. Entries that do not belong to that utility network are ignored.

Set this property before assigning a trace result. Changing it does not requery the current result or restrict highlighting.

messageOverrides

Property

Type: Record<string, unknown> | undefined

Replace localized message strings with your own strings.

Note: Individual message keys may change between releases.

numFeatureResults

readonly Property

Type: number

The number of successfully queried features plus unique trace elements without a matching layer in the map.

If the default slot contains multiple arcgis-utility-network-trace-elements-result-item components, this property returns the result count from the first one. This value can be lower than the number of elements returned by the trace when feature queries fail or return no matching features.

referenceElement

Property

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.

See also

Associate components with a Map or Scene component

Attribute: reference-element

state

readonly Property

Type: UtilityNetworkTraceResultItemState

The processing state of the component: "loading" while result items process a trace result and "ready" when no processing is in progress. A "ready" state does not necessarily mean that every result item succeeded.

Default value: "ready"

traceError

Property

Type: EsriError<TraceErrorDetails> | undefined

The error returned when the trace could not be completed.

When set, the component displays the error instead of traceResult. Changes emit @arcgisPropertyChange.

traceResult

Property

Type: TraceResult | undefined

The trace result to display.

Assigning a new value clears side effects from the previous result and starts a new processing cycle. It does not emit @arcgisTraceResultClear. Changes emit @arcgisPropertyChange.

traceResultFeatures

readonly Property

Type: Graphic[]

The features successfully queried for the current trace result elements.

Read this property after @arcgisResultsReady fires. Elements without a matching query layer are not included. If the default slot contains multiple arcgis-utility-network-trace-elements-result-item components, this property returns features from the first one.

utilityNetwork

Property

Type: UtilityNetwork | undefined

The utility network used to resolve trace result elements to features.

view

Property

Type: MapView | undefined

The MapView used to display and highlight trace results.

Methods

Method	Signature
clearResults	clearResults(): void
componentOnReady inherited	componentOnReady(): Promise<this>
destroy	destroy(): Promise<void>

clearResults

Method

Signature: clearResults (): void

Clears side effects created by the result items, resets state to "ready", and emits @arcgisTraceResultClear.

Clears traceResult and traceError values.

Returns: void

componentOnReady

inherited Method

Signature: componentOnReady (): Promise<this>

Creates a promise that resolves once the component is fully loaded.

Returns: Promise<this>

Example

const arcgisUtilityNetworkTraceResults = document.createElement("arcgis-utility-network-trace-results");
document.body.append(arcgisUtilityNetworkTraceResults);
await arcgisUtilityNetworkTraceResults.componentOnReady();
console.log("arcgis-utility-network-trace-results is ready to go!");

destroy

Method

Signature: destroy (): Promise<void>

Permanently destroy the component.

Returns: Promise<void>

Events

Name	Type
arcgisPropertyChange	CustomEvent<{ name: "aggregatedGeometryResultsGraphicsColor" \| "aggregatedGeometryResultsSize" \| "hideGraphics" \| "state" \| "traceError" \| "traceResult" \| "utilityNetwork" \| "view"; }>
arcgisResultsReady	CustomEvent<void>
arcgisTraceResultClear	CustomEvent<void>
arcgisTriggerAction	CustomEvent<ActionEvent>

arcgisPropertyChange

Event

 arcgisPropertyChange: CustomEvent<{ name: "aggregatedGeometryResultsGraphicsColor" | "aggregatedGeometryResultsSize" | "hideGraphics" | "state" | "traceError" | "traceResult" | "utilityNetwork" | "view"; }>

Emitted when the value of a property is changed. Use this to listen to changes to properties.

arcgisResultsReady

Event

arcgisResultsReady: CustomEvent<void>

Fires when all participating result items finish processing the current traceResult, including when processing produces no results or a result item fails.

Calling clearResults() during processing does not emit this event.

arcgisTraceResultClear

Event

arcgisTraceResultClear: CustomEvent<void>

Fires when clearResults() is called. Replacing or clearing traceResult directly does not emit this event.

arcgisTriggerAction

Event

arcgisTriggerAction: CustomEvent<ActionEvent>

Emitted when an action is triggered on the component.

Slots

Name	Description
default (unnamed)	Default slot for adding trace result items or custom content. Slotted content replaces the component's default result items.

default (unnamed)

Slot

Default slot for adding trace result items or custom content. Slotted content replaces the component's default result items.

Type definitions

TraceErrorDetails

Type definition

url

Property

Type: string | undefined

raw

Property

Type: { extendedCode?: number; message?: string; } | undefined