arcgis-utility-network-trace-elements-result-item | References

ESM

import "@arcgis/map-components/components/arcgis-utility-network-trace-elements-result-item";

Inheritance: ArcgisUtilityNetworkTraceElementsResultItem→HTMLElement

Since: ArcGIS Maps SDK for JavaScript 5.2

The Utility Network Trace Elements Result Item component displays features corresponding to the elements returned by a utility network trace. It queries utility network layers for features, highlights trace elements in the view, and uses arcgis-features-next to display the queried features in a list.

For traces containing only element results, the features list opens automatically. For traces containing multiple result types, users open the features list by selecting the elements result item in the trace results component. See isFeaturesListShown for details.

Add this component directly to the default slot of arcgis-utility-network-trace-results. The parent supplies the required read-only properties for the trace result, utility network, and MapView. Configure other settings, such as layers, disableHighlight, and hideFeatureResults, on this component.

By default, the arcgis-utility-network-trace-results component displays the aggregated geometry, elements, and functions result items for the result types returned by the trace. Adding content to its default slot replaces all default result items. Add each result item that the custom configuration should display.

Use layers to restrict feature queries to specific utility network layers.

See also

Examples

The following example displays element results in a custom set of trace result items. Providing result items in the default slot replaces the parent's default result items. This example displays only element results.

<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></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 access the queried features when the elements result item is ready and respond when the selected result feature changes.

const resultItem = document.querySelector("arcgis-utility-network-trace-elements-result-item");

resultItem.addEventListener("arcgisResultReady", () => {
  console.log("Trace result features:", resultItem.features);
});

resultItem.addEventListener("arcgisPropertyChange", (event) => {
  if (event.detail.name === "selectedResultFeature") {
    console.log("Selected feature:", resultItem.selectedResultFeature);
  }
});

Properties

Property	Attribute	Type
actions		ArcgisFeaturesNext["actions"] \| undefined
autoDestroyDisabled	auto-destroy-disabled	boolean
disableHighlight	disable-highlight	boolean
emitsArcgisResultReady readonly		true
features readonly		Graphic[]
heading	heading	string \| undefined
hideActionBar	hide-action-bar	boolean
hideFeatureResults	hide-feature-results	boolean
hidePlaceholder	hide-placeholder	boolean
includeDefaultActionsDisabled	include-default-actions-disabled	boolean
isFeaturesListShown readonly		boolean
layers		Layer[]
messageOverrides		Record<string, unknown> \| undefined
numResults readonly		number
referenceElement	reference-element	ArcgisReferenceElement \| string \| undefined
selectedResultFeature readonly		Graphic \| undefined
state readonly		UtilityNetworkTraceResultItemState
traceResult readonly		TraceResult \| undefined
utilityNetwork readonly		UtilityNetwork \| undefined
view readonly		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

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

utilityNetworkTraceElementsResultItemElement.autoDestroyDisabled = true;

disableHighlight

Property

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
Default value: false

emitsArcgisResultReady

readonly Property

Type: true

Whether the component emits event @arcgisResultReady. This property is always true for arcgis-utility-network-trace-elements-result-item.

Default value: false

features

readonly Property

Type: Graphic[]

The features successfully queried for the current trace result elements. Elements without a matching query layer are not included.

heading

Property

Type: string | undefined

The label of the elements result item that opens the features list. If not specified or empty, the component uses its localized default label.

Attribute: heading

hideActionBar

Property

Type: boolean

Whether to hide the action bar when viewing trace result features. The action bar contains the feature's actions.

Attribute: hide-action-bar
Default value: false

hideFeatureResults

Property

Type: boolean

Whether to hide the elements result item and the features list. If true, the component renders a placeholder string instead of the elements result item. When true, features are still queried and are available through features.

This property does not disable highlighting. Use disableHighlight to hide trace-element highlights.

Attribute: hide-feature-results
Default value: false

hidePlaceholder

Property

Type: boolean

Whether to hide the placeholder string when the elements result item and the features list 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 features.

Attribute: hide-placeholder
Default value: false

includeDefaultActionsDisabled

Property

Type: boolean

Whether to hide the default actions when viewing trace result features.

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

isFeaturesListShown

readonly Property

Type: boolean

Whether the features list is currently displayed. Returns true when the component is displaying the features list using the arcgis-features-next component.

Always returns false when hideFeatureResults is set to true.

If hideFeatureResults is not set, the features list opens automatically when a trace result containing only elements loads, or when the user selects the elements result item. Closing the features list causes this property to return false.

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 the map's layers and tables that belong to the selected utilityNetwork. Entries that do not belong to that utility network are ignored.

Set this property before the trace result is processed. Changing it does not requery the current result.

This property restricts which layers are queried for features. It does not restrict highlighting of trace result features.

messageOverrides

Property

Type: Record<string, unknown> | undefined

Replace localized message strings with your own strings.

Note: Individual message keys may change between releases.

numResults

readonly Property

Type: number

The number of successfully queried features.

This value can be lower than the number of elements returned by the trace. For example:

Trace result elements that only differ by a terminal ID are treated as one feature.
Feature queries may fail or return no matching features.

referenceElement

Property

Type: ArcgisReferenceElement | string | undefined

The reference element, or its ID, forwarded to the embedded Features component.

Setting this property does not remove the requirement to use this component as a child of arcgis-utility-network-trace-results.

Attribute: reference-element

selectedResultFeature

readonly Property

Type: Graphic | undefined

The currently selected trace result feature.

This property also returns associated features that have been selected via association content in a PopupTemplate.

state

readonly Property

Type: UtilityNetworkTraceResultItemState

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

Default value: "ready"

traceResult

readonly Property

Type: TraceResult | undefined

The trace result containing the element results to render features for.

utilityNetwork

readonly Property

Type: UtilityNetwork | undefined

The utility network used to query the trace result features.

view

readonly Property

Type: MapView | undefined

The MapView supplied by the parent arcgis-utility-network-trace-results component. Used to query utility network layers and highlight trace elements.

Methods

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

clearResult

Method

Signature: clearResult (): void

Cancels feature queries in progress, removes trace-element highlights from the map, clears features, and traceResult, closes the features list, and resets state to "ready".

Does not emit @arcgisResultReady.

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 arcgisUtilityNetworkTraceElementsResultItem = document.createElement("arcgis-utility-network-trace-elements-result-item");
document.body.append(arcgisUtilityNetworkTraceElementsResultItem);
await arcgisUtilityNetworkTraceElementsResultItem.componentOnReady();
console.log("arcgis-utility-network-trace-elements-result-item is ready to go!");

destroy

Method

Signature: destroy (): Promise<void>

Permanently destroy the component.

Returns: Promise<void>

Events

Name	Type
arcgisPropertyChange	CustomEvent<{ name: "features" \| "hasContent" \| "isFeaturesListShown" \| "selectedResultFeature" \| "state"; }>
arcgisResultReady	CustomEvent<void>
arcgisTriggerAction	CustomEvent<ActionEvent>

arcgisPropertyChange

Event

 arcgisPropertyChange: CustomEvent<{ name: "features" | "hasContent" | "isFeaturesListShown" | "selectedResultFeature" | "state"; }>

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

arcgisResultReady

Event

arcgisResultReady: CustomEvent<void>

Fires when processing the current trace result finishes, including when a query fails. The features property contains the features successfully queried.

Clearing an in-progress result with clearResult() does not emit this event.

arcgisTriggerAction

Event

arcgisTriggerAction: CustomEvent<ActionEvent>

Emitted when an action is triggered on the component.