UtilityNetworkTraceViewModel | References | ArcGIS Maps SDK for JavaScript

import UtilityNetworkTraceViewModel from "@arcgis/core/widgets/UtilityNetworkTrace/UtilityNetworkTraceViewModel.js";

Inheritance:: UtilityNetworkTraceViewModel→Accessor

Since: ArcGIS Maps SDK for JavaScript 4.22

Provides the logic for the UtilityNetworkTrace widget and component.

See also

Constructors

Constructor

Parameters

Parameter	Type	Description	Required
properties	`UtilityNetworkTraceViewModelProperties`

See the properties table for a list of all the properties that may be passed into the constructor.

Properties

Any properties can be set, retrieved or listened to. See the Watch for changes topic.

Property	Type	Class
`declaredClass` readonly inherited	`string`	Accessor
`defaultGraphicColor`	`GraphicColor`
`enableResultArea`	`boolean`
`flags`	`FlagProperty[]`
`resultAreaProperties`	`ResultAreaPropertiesExtend`
`selectedTraces`	`string[]`
`selectOnComplete`	`boolean`
`showGraphicsOnComplete`	`boolean`
`showSelectionAttributes`	`boolean`
`state` readonly	`UtilityNetworkTraceViewModelState`
`traceResults`	`Array<TraceResultExtend>`
`utilityNetwork`	`UtilityNetwork \| null \| undefined`
`view`	`MapView \| null \| undefined`

declaredClass

readonlyinherited Property

Type: string

Inherited from: Accessor

The name of the class. The declared class name is formatted as esri.folder.className.

defaultGraphicColor

Property

Type: GraphicColor

Since: ArcGIS Maps SDK for JavaScript 4.23

The default color to assign the aggregated geometry of a trace result.

Default value: { color: [255, 255, 0, 0.6], haloOpacity: 0.9, fillOpacity: 0.2, hex: "#FFFF00" }

enableResultArea

Property

Type: boolean

Since: ArcGIS Maps SDK for JavaScript 4.27

When true, provides the ability to show the convex hull or buffer.

Default value: false

flags

Property

Type: FlagProperty[]

An array of map points to load into the widget to lookup flags.

Default value: []

Example

const unt = new UtilityNetworkTrace({
 view: view,
 showSelectionAttributes: true,
 selectOnComplete: true,
 showGraphicsOnComplete: true,
 selectedTraces: ["{E8D545B8-596D-4656-BF5E-16C1D7CBEC9B}"],
 flags: [
   {
     type: "starting-point",
     mapPoint: {
       spatialReference: { latestWkid: 3857, wkid: 102100 },
       x: -9814829.166046409,
       y: 5127094.1017433
     }
   },
   {
     type: "barrier",
     mapPoint: {
     spatialReference: { latestWkid: 3857, wkid: 102100 },
       x: -9814828.449441982,
       y: 5127089.085566963
     }
   }
 ]
});

resultAreaProperties

Property

Type: ResultAreaPropertiesExtend

Since: ArcGIS Maps SDK for JavaScript 4.27

The properties to determine the size and color of the result area convex hull or buffer, and determines if it displays on the map when the trace completes.

Default value: { type: "convexhull", distance: 10, unit: "meters", areaUnit: "square-meters", color: { color: [255, 165, 0, 0.5], haloOpacity: 0.9, fillOpacity: 0.2, hex: "#ffa500" }, show: false }

Example

const unt = new UtilityNetworkTrace({
 un: un,
 view: view,
 enableResultArea: true,
 resultAreaProperties: {
   type: "buffer",
   distance: 10,
   unit: "feet",
   areaUnit: "square-feet",
   color: {
     color: [255, 165, 0, 0.5],
     haloOpacity: 0.9,
     fillOpacity: 0.2,
     hex: "#ffa500"
   },
   show: true
 }
});

selectedTraces

Property

Type: string[]

An array of global Ids of traces to select on initial load.

Default value: []

selectOnComplete

Property

Type: boolean

When true, the utility network elements are selected in the view when traces are completed.

Default value: true

showGraphicsOnComplete

Property

Type: boolean

When true, a graphic layer is added to the view to highlight the utility network elements when traces are completed.

Default value: true

showSelectionAttributes

Property

Type: boolean

Determines whether to show the list of selected features from completed traces.

Default value: true

state

readonly Property

Type: UtilityNetworkTraceViewModelState

The view model's state.

Default value: "ready"

traceResults

Property

Type: Array<TraceResultExtend>

Since: ArcGIS Maps SDK for JavaScript 4.27

Stores the result of completed traces.

utilityNetwork

Property

Type: UtilityNetwork | null | undefined

Since: ArcGIS Maps SDK for JavaScript 4.27

Determines the utility network to use.

view

Property

Type: MapView | null | undefined

The view from which the widget will operate.

Methods

Method	Signature	Class
`addFlagByHit`	`addFlagByHit(type: TraceLocationType): Promise<boolean>`
`addResultAreaToMap`	`addResultAreaToMap(trace: TraceResultExtend): Promise<void>`
`addResultGraphicToView`	`addResultGraphicToView(trace: TraceResultExtend, color: GraphicColor): Promise<void>`
`addTerminal`	`addTerminal(selectedTerminal: string, feature: FlagProperty): void`
`callTrace`	`callTrace(): Promise<boolean>`
`changeResultGraphicColor`	`changeResultGraphicColor(color: GraphicColor, trace: TraceResultExtend): void`
`checkCanTrace`	`checkCanTrace(): ValidSetup`
`checkSelectionExist`	`checkSelectionExist(): boolean`
`clearResult`	`clearResult(trace: TraceItem): void`
`createResultAreaGraphic`	`createResultAreaGraphic(traceResults: TraceResultExtend): Promise<Graphic \| null \| undefined>`
`emit` inherited	`emit<Type extends EventNames<this>>(type: Type, event?: this["@eventTypes"][Type]): boolean`	EventedMixin
`executeTrace`	`executeTrace(traceItem: TraceItem, url: string, params: TraceParameters): Promise<TraceResultExtend>`
`getValidSources`	`getValidSources(): Array<NetworkSourceJSON>`
`hasEventListener` inherited	`hasEventListener<Type extends EventNames<this>>(type: Type): boolean`	EventedMixin
`loadUtilityNetwork`	`loadUtilityNetwork(): Promise<UtilityNetwork \| null \| undefined>`
`manageFilterBarrier`	`manageFilterBarrier(status: boolean, feature: FlagProperty): void`
`mergeSelection`	`mergeSelection(status: boolean, trace: TraceItem): void`
`on` inherited	`on<Type extends EventNames<this>>(type: Type, listener: EventedCallback<this["@eventTypes"][Type]>): ResourceHandle`	EventedMixin
`queryFeaturesById`	`queryFeaturesById(dataItems: NetworkElement[]): Promise<FeatureSetInfo[] \| null \| undefined>`
`queryFlagByHitTest`	`queryFlagByHitTest(event: CreateEvent, flagType: TraceLocationType): Promise<boolean>`
`removeAllResultAreaGraphics`	`removeAllResultAreaGraphics(): void`
`removeFlag`	`removeFlag(flag: FlagProperty): void`
`removeResultAreaFromMap`	`removeResultAreaFromMap(trace: TraceResultExtend): void`
`removeResultGraphicFromView`	`removeResultGraphicFromView(trace: TraceResultExtend): void`
`removeSelection`	`removeSelection(): void`
`removeTerminal`	`removeTerminal(selectedTerminal: string, feature: FlagProperty): void`
`reset`	`reset(): void`
`selectFeaturesById`	`selectFeaturesById(resultSet: NetworkElement[]): void`
`selectResults`	`selectResults(resultSet: NetworkElement[]): void`
`selectTraces`	`selectTraces(state: boolean, traceId: string): void`
`selectTracesOnLoad`	`selectTracesOnLoad(): void`
`zoomToAsset`	`zoomToAsset(geometry: GoToTarget2D \| GoToTarget3D): void`

addFlagByHit

Method

Signature: addFlagByHit (type: TraceLocationType): Promise<boolean>

Adds a flag point graphic for the click event on the view if there is a feature to query.

Parameters

Parameter	Type	Description	Required
type	`TraceLocationType`	The type of flag can be a `"starting point"` or a `"barrier"`.

Returns: Promise<boolean>
When resolved, response is true if there is a feature to query in the view.

addResultAreaToMap

Method

Signature: addResultAreaToMap (trace: TraceResultExtend): Promise<void>

Since: ArcGIS Maps SDK for JavaScript 4.27

Creates a graphic from the trace result and adds it to the map. If a trace has both aggregated geometries and elements as results, aggregated geometries will be used to generate this area.

Parameters

Parameter	Type	Description	Required
trace	`TraceResultExtend`	The aggregate of the trace configuration settings and the results for that trace.

Returns: Promise<void>

addResultGraphicToView

Method

Signature: addResultGraphicToView (trace: TraceResultExtend, color: GraphicColor): Promise<void>

Create a graphic on the view's MapView.graphics for the aggregated results of all the features returned by the trace.

Parameters

Parameter	Type	Description	Required
trace	`TraceResultExtend`	The aggregate of the trace configuration settings and the results for that trace.
color	`GraphicColor`	The color for the graphic of the trace results in the view's MapView.graphics.

Returns: Promise<void>
Resolves when the graphics are added to the view.

addTerminal

Method

Signature: addTerminal (selectedTerminal: string, feature: FlagProperty): void

Adds the selected terminal to a flag point.

Parameters

Parameter	Type	Description	Required
selectedTerminal	`string`	The terminal id of the selected terminal.
feature	`FlagProperty`	The flag to assign the terminal.

Returns: void

callTrace

Method

Signature: callTrace (): Promise<boolean>

Get all parameters for the trace type selected to be run before executing the trace.

Returns: Promise<boolean>
When resolved, response is true when the parameters from the trace type have loaded.

changeResultGraphicColor

Method

Signature: changeResultGraphicColor (color: GraphicColor, trace: TraceResultExtend): void

Change the graphic color for the aggregated results of a trace.

Parameters

Parameter	Type	Description	Required
color	`GraphicColor`	The color for the graphic of the trace results in the view's MapView.graphics.
trace	`TraceResultExtend`	The aggregate of the trace configuration settings and the results for that trace.

Returns: void

checkCanTrace

Method

Signature: checkCanTrace (): ValidSetup

May be used to verify if all requirements are met to execute a trace (at least 1 starting point and at least 1 trace type selected).

Returns: ValidSetup
Represents whether a trace is setup correctly.

checkSelectionExist

Method

Signature: checkSelectionExist (): boolean

Indicates if any selection exists on the view.

Returns: boolean
Returns true if selection exists on the view.

clearResult

Method

Signature: clearResult (trace: TraceItem): void

Removes a specific trace from the results. This will also clear any graphics or selection in the view for that trace.

Parameters

Parameter	Type	Description	Required
trace	`TraceItem`	The trace that will be cleared.

Returns: void

createResultAreaGraphic

Method

Signature: createResultAreaGraphic (traceResults: TraceResultExtend): Promise<Graphic | null | undefined>

Creates a buffer or convex hull graphic of the trace result.

Parameters

Parameter	Type	Description	Required
traceResults	`TraceResultExtend`	The aggregate of the trace configuration settings and the results for that trace.

Returns: Promise<Graphic | null | undefined>
Buffer or convex hull graphic of trace result.

emit

inherited Method

Signature: emit <Type extends EventNames<this>>(type: Type, event?: this["@eventTypes"][Type]): boolean

Type parameters: <Type extends EventNames<this>>

Inherited from: EventedMixin

Emits an event on the instance. This method should only be used when creating subclasses of this class.

Parameters

Parameter	Type	Description	Required
type	`Type`	The name of the event.
event	`this["@eventTypes"][Type]`	The event payload.

Returns: boolean
true if a listener was notified

executeTrace

Method

Signature: executeTrace (traceItem: TraceItem, url: string, params: TraceParameters): Promise<TraceResultExtend>

Executes the trace and returns all trace results as graphics and/or feature selections and functions.

Parameters

Parameter	Type	Description
traceItem	`TraceItem`	The trace item input for the trace.
url	`string`	The URL of the service being traced.
params	`TraceParameters`	The trace input parameters.

Returns: Promise<TraceResultExtend>
Represents the trace results and its properties.

getValidSources

Method

Signature: getValidSources (): Array<NetworkSourceJSON>

Gets the valid edge and junction layers within the view that are part of the Utility Network and can be used for placing flags in the view.

Returns: Array<NetworkSourceJSON>
The edge or junction layer info.

hasEventListener

inherited Method

Signature: hasEventListener <Type extends EventNames<this>>(type: Type): boolean

Type parameters: <Type extends EventNames<this>>

Inherited from: EventedMixin

Indicates whether there is an event listener on the instance that matches the provided event name.

Parameters

Parameter	Type	Description	Required
type	`Type`	The name of the event.

Returns: boolean
Returns true if the class supports the input event.

loadUtilityNetwork

Method

Signature: loadUtilityNetwork (): Promise<UtilityNetwork | null | undefined>

Reads the web map and loads the UtilityNetwork if it exists.

Returns: Promise<UtilityNetwork | null | undefined>
Resolves when the UtilityNetwork has been loaded.

manageFilterBarrier

Method

Signature: manageFilterBarrier (status: boolean, feature: FlagProperty): void

Enables or disables the filter barrier setting on barrier flags.

Parameters

Parameter	Type	Description	Required
status	`boolean`	Whether the filter barrier is enabled or disabled.
feature	`FlagProperty`	The barrier flag for which the filter barrier is enabled or disabled.

Returns: void

mergeSelection

Method

Signature: mergeSelection (status: boolean, trace: TraceItem): void

Is used to merge the feature selections in the layer views when multiple traces are run.

Parameters

Parameter	Type	Description	Required
status	`boolean`	If true, the trace selection results are part of the merged selection set.
trace	`TraceItem`	The trace for which the status is defined.

Returns: void

on

inherited Method

Signature: on <Type extends EventNames<this>>(type: Type, listener: EventedCallback<this["@eventTypes"][Type]>): ResourceHandle

Type parameters: <Type extends EventNames<this>>

Inherited from: EventedMixin

Registers an event handler on the instance. Call this method to hook an event with a listener.

Parameters

Parameter	Type	Description	Required
type	`Type`	An event or an array of events to listen for.
listener	`EventedCallback<this["@eventTypes"][Type]>`	The function to call when the event fires.

Returns

ResourceHandle

Returns an event handler with a remove() method that should be called to stop listening for the event(s).

Property	Type	Description
remove	Function	When called, removes the listener from the event.

Example

view.on("click", function(event){
  // event is the event handle returned after the event fires.
  console.log(event.mapPoint);
});

queryFeaturesById

Method

Signature: queryFeaturesById (dataItems: NetworkElement[]): Promise<FeatureSetInfo[] | null | undefined>

Query the layers by ObjectID for more attributes not present on the trace result elements.

Parameters

Parameter	Type	Description	Required
dataItems	`NetworkElement[]`	An array of NetworkElements.

Returns: Promise<FeatureSetInfo[] | null | undefined>
When resolved, an array of FeatureSetInfo is returned.

queryFlagByHitTest

Method

Signature: queryFlagByHitTest (event: CreateEvent, flagType: TraceLocationType): Promise<boolean>

Takes the result of a hit test to lookup the asset to create a flag for the trace.

Parameters

Parameter	Type	Description	Required
event	`CreateEvent`	The create event.
flagType	`TraceLocationType`	The type of flag. It must be either `"starting point"` or `"barrier"`. The `stopping-point` type is reserved for future use.

Returns: Promise<boolean>
When resolved, returns true for a successful hitTest.

removeAllResultAreaGraphics

Method

Signature: removeAllResultAreaGraphics (): void

Removes all the graphics from the result area graphic layer

Returns: void

removeFlag

Method

Signature: removeFlag (flag: FlagProperty): void

Removes the selected flag from the view.

Parameters

Parameter	Type	Description	Required
flag	`FlagProperty`	The FlagProperty to identify the flag to be removed.

Returns: void

removeResultAreaFromMap

Method

Signature: removeResultAreaFromMap (trace: TraceResultExtend): void

Since: ArcGIS Maps SDK for JavaScript 4.27

Removes the result area graphic from the Map.

Parameters

Parameter	Type	Description	Required
trace	`TraceResultExtend`	The aggregate of the trace configuration settings and the results for that trace.

Returns: void

removeResultGraphicFromView

Method

Signature: removeResultGraphicFromView (trace: TraceResultExtend): void

Removes a specific trace result graphic from the view's MapView.graphics.

Parameters

Parameter	Type	Description	Required
trace	`TraceResultExtend`	The trace for which the graphic will be removed.

Returns: void

removeSelection

Method

Signature: removeSelection (): void

Removes the selection from the layer view.

Returns: void

removeTerminal

Method

Signature: removeTerminal (selectedTerminal: string, feature: FlagProperty): void

Removes the selected terminal from the flag.

Parameters

Parameter	Type	Description	Required
selectedTerminal	`string`	The terminal id of the selected terminal.
feature	`FlagProperty`	The flag to remove the terminal.

Returns: void

reset

Method

Signature: reset (): void

Clears all inputs (flags, trace types) and all results (selections, graphics) in the view.

Returns: void

selectFeaturesById

Method

Signature: selectFeaturesById (resultSet: NetworkElement[]): void

Performs a selection on a layer view based on a list of ObjectIDs.

Parameters

Parameter	Type	Description	Required
resultSet	`NetworkElement[]`	An array of NetworkElements.

Returns: void

selectResults

Method

Signature: selectResults (resultSet: NetworkElement[]): void

Loops through the trace result elements to group them by network source id and selects them on the layer view.

Parameters

Parameter	Type	Description	Required
resultSet	`NetworkElement[]`	An array of NetworkElements.

Returns: void

selectTraces

Method

Signature: selectTraces (state: boolean, traceId: string): void

Set the trace type to be run from the available trace configurations in the WebMap.

Parameters

Parameter	Type	Description	Required
state	`boolean`	This is `true` if the trace is selected.
traceId	`string`	The globalid of the trace configuration.

Returns: void

selectTracesOnLoad

Method

Signature: selectTracesOnLoad (): void

Preset a trace type to be run from the available trace configurations in the WebMap when the widget loads.

Returns: void

zoomToAsset

Method

Signature: zoomToAsset (geometry: GoToTarget2D | GoToTarget3D): void

Zoom to a flag's feature or a result feature in the view.

Parameters

Parameter	Type	Description	Required
geometry	`GoToTarget2D \| GoToTarget3D`	The geometry to zoom to.

Returns: void

Type definitions

UtilityNetworkTraceViewModelState

Type definition

Type: "ready" | "loading"

TraceItem

Type definition

TraceItem extends the named trace configuration and adds a property to manage the selection on the view.

Supertypes: NamedTraceConfigurationProperties

selected

Property

Type: boolean | undefined

Returns true if there is a selection on the view for a trace.

DisplayField

Type definition

DisplayField represents the attribute field used as a display label for flags and selected features.

field

Property

Type: string | null | undefined

The feature's display field.

value

Property

Type: string

The value of the field.

FlagProperty

Type definition

FlagProperty represents the properties to define each flag point (starting points and barriers).

Supertypes: TraceLocationProperties

type

Property

Type: TraceLocationType

The flag type being set. Must be either "starting point" or "barrier". The stopping-point type is reserved for future use.

Possible Values

Value	Description
starting-point	The flag set will be the starting location of the trace.
barrier	The flag set will mark the location to stop the trace.

allTerminals

Property

Type: TerminalConfiguration | null | undefined

The available terminals to define the permissible paths based on the terminal configurations. The default terminal is always set.

selectedTerminals

Property

Type: Array<number> | null | undefined

The terminals that are selected for the flag (this can be the default terminal or terminals selected by the end-user).

displayValue

Property

Type: DisplayField | null | undefined

The display field of the flag.

mapPoint

Property

Type: Point | null | undefined

The geometry point of the flag.

details

Property

Type: any | null | undefined

All the information returned by the hitTest.

mapGraphic

Property

Type: Graphic | null | undefined

The flag graphic.

id

Property

Type: number | null | undefined

The id of the flag.

GraphicColor

Type definition

GraphicColor represents the color for the trace result graphic in the graphics layer.

color

Property

Type: [ number, number, number, number ]

The color of the trace result graphic in the view.

haloOpacity

Property

Type: number

The opacity of the graphic symbol's halo.

hex

Property

Type: string

The color of the trace result graphic in the color picker.

ResultAreaPropertiesExtend

Type definition

ResultAreaPropertiesExtend represents the properties to determine the size and color of the result area convex hull or buffer, and whether it displays on the map when the trace completes.