arcgis-utility-network-trace-configuration-picker | References

ESM

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

Inheritance: ArcgisUtilityNetworkTraceConfigurationPicker→HTMLElement

Since: ArcGIS Maps SDK for JavaScript 5.2

The Utility Network Trace Configuration Picker component selects a named trace configuration and, when applicable, a subnetwork name.

To use this component independently, set utilityNetwork to a loaded UtilityNetwork and provide its named trace configurations through traceConfigurations. The component displays a title for a single configuration or a combobox for multiple configurations.

Read selectedNamedTraceConfiguration for the selection and traceConfiguration for its editable clone. For subnetwork traces with a specified subnetwork name, users can select a compatible subnetwork. The component also displays available domain network, tier, and target tier names for subnetwork-related trace types. This component does not execute traces.

Changing the traceConfiguration list preserves the selectedNamedTraceConfiguration if it is still included in the new list. Otherwise, the component selects the first configuration backed by a UNTraceConfiguration.

Customize the display with heading, hideSubnetworkInfo, hideErrors, and messageOverrides.

Example

This example creates a picker that lets users choose from a list of named trace configurations. It assumes utilityNetwork is an existing, loaded UtilityNetwork.

Set the required properties before adding the picker to the page. Use the network's sharedNamedTraceConfigurations to provide the options users can choose from.

const picker = document.createElement("arcgis-utility-network-trace-configuration-picker");
picker.utilityNetwork = utilityNetwork;
picker.traceConfigurations = utilityNetwork.sharedNamedTraceConfigurations;
document.body.append(picker);

Properties

Property	Attribute	Type
error	error	string \| undefined
heading	heading	string \| undefined
hideErrors	hide-errors	boolean
hideSubnetworkInfo	hide-subnetwork-info	boolean
messageOverrides		Record<string, unknown> \| undefined
selectedNamedTraceConfiguration		NamedTraceConfiguration \| undefined
state	state	"error" \| "loading" \| "ready"
traceConfiguration		UNTraceConfiguration \| undefined
traceConfigurations		NamedTraceConfiguration[]
utilityNetwork		UtilityNetwork \| undefined

error

Property

Type: string | undefined

The current configuration selection error message, or undefined when cleared. The component displays this message unless hideErrors is true. A missing compatible subnetwork can also display a notice without setting this property.

Attribute: error

heading

Property

Type: string | undefined

The heading above the traceConfigurations combobox or title. When not set, the component uses the localized trace configuration label.

Attribute: heading

hideErrors

Property

Type: boolean

Indicates whether to hide error notices. Errors still update error and state and emit @arcgisError.

Attribute: hide-errors
Default value: false

hideSubnetworkInfo

Property

Type: boolean

Indicates whether to hide the domain network, tier, and target tier names from selectedNamedTraceConfiguration. This does not hide the subnetwork selection control.

Attribute: hide-subnetwork-info
Default value: false

messageOverrides

Property

Type: Record<string, unknown> | undefined

Replace localized message strings with your own strings.

Note: Individual message keys may change between releases.

selectedNamedTraceConfiguration

Property

Type: NamedTraceConfiguration | undefined

The selected NamedTraceConfiguration. Set this property to a configuration from traceConfigurations to select it programmatically. Selecting a configuration creates a new traceConfiguration clone. An initial selection is preserved when it is included in the available configurations.

state

Property

Type: "error" | "loading" | "ready"

The current configuration selection state.

error: A configuration selection error has set error.
loading: Compatible subnetwork names are being loaded for the selected configuration.
ready: The initial state, also set when a configuration selection error is cleared or compatible subnetwork loading completes.

Attribute: state
Default value: "ready"

traceConfiguration

Property

Type: UNTraceConfiguration | undefined

A clone of the UNTraceConfiguration associated with selectedNamedTraceConfiguration. The component updates this mutable clone when the user changes the subnetwork name, without modifying the original named trace configuration. Read this object when executing a trace to use the current settings. It is undefined when no valid configuration is selected.

Changes to fields on this object do not emit @arcgisPropertyChange.

traceConfigurations

Property

Type: NamedTraceConfiguration[]

The named trace configurations available for selection. Each configuration must contain a UNTraceConfiguration. Your application must set this property explicitly; the component does not derive the configurations from the utility network or map. For example, assign the loaded utility network's sharedNamedTraceConfigurations.

Changing this array preserves selectedNamedTraceConfiguration if it is still included. Otherwise, the first entry backed by a UNTraceConfiguration is selected. An empty array clears the selection and displays an error.

Example

Provide configurations with a specific tag from an existing utility network.

const picker = document.querySelector("arcgis-utility-network-trace-configuration-picker");
await Promise.all([picker.componentOnReady(), utilityNetwork.load()]);

picker.utilityNetwork = utilityNetwork;
picker.traceConfigurations = utilityNetwork.sharedNamedTraceConfigurations.filter(
  (configuration) => configuration.tags.includes("your-tag-name"),
);

utilityNetwork

Property

Type: UtilityNetwork | undefined

The loaded UtilityNetwork associated with traceConfigurations. The component uses its subnetworks table to query compatible subnetwork names. Changing the network clears the cached subnetworks and the current subnetwork name.

Methods

Method	Signature
componentOnReady inherited	componentOnReady(): Promise<this>

componentOnReady

inherited Method

Signature: componentOnReady (): Promise<this>

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

Returns: Promise<this>

Example

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

Events

Name	Type
arcgisError	CustomEvent<void>
arcgisPropertyChange	CustomEvent<{ name: "selectedNamedTraceConfiguration" \| "traceConfiguration"; }>

arcgisError

Event

arcgisError: CustomEvent<void>

Fires when the component sets a configuration selection error. Read error for the message. This event has no error payload and fires even when hideErrors is true. A notice about missing compatible subnetworks does not emit this event.

arcgisPropertyChange

Event

arcgisPropertyChange: CustomEvent<{ name: "selectedNamedTraceConfiguration" | "traceConfiguration"; }>

Fires when selectedNamedTraceConfiguration or traceConfiguration changes. Read event.detail.name to identify the property, then read its current value from the component. Changes to fields on the configuration clone, such as the subnetwork name, do not emit this event.