DirectionsViewModel | API Reference | ArcGIS Maps SDK for JavaScript 4.31

Provides the communication and data manipulation logic for the Directions widget.

See also

Example

const layer = new RouteLayer();
map.add(layer);

// Create and instantiate the DirectionsViewModel with an API key and the RouteLayer.
// Use `load()` to load the view model's routing resources including the service description associated with the route layer's routing service.
const apiKey = "<your api key>";
const directionsViewModel = new DirectionsViewModel({ apiKey, layer });
await directionsViewModel.load();

Constructors

DirectionsViewModel Constructor new DirectionsViewModel(properties)

Parameter

properties Object

optional

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

Property Overview

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

Show inherited properties

Hide inherited properties

Type	Summary	Class
String	An authorization string used to access a resource or service.	DirectionsViewModel
String	The name of the class.	Accessor
GoToOverride	This function provides the ability to override either the MapView goTo() or SceneView goTo() methods.	DirectionsViewModel
Object	The network attribute name to be used as the impedance attribute in the analysis.	DirectionsViewModel
RouteLayerSolveResult	The most recent route result.	DirectionsViewModel
RouteLayer	The RouteLayer associated with the DirectionsViewModel.	DirectionsViewModel
Number	The maximum number of stops allowed for routing.	DirectionsViewModel
RouteParameters	Route Parameters object used to call the service.	DirectionsViewModel
TravelMode	The travel mode that will be used by getDirections() when requesting the route and directions.	DirectionsViewModel
ServiceDescription	The Service Description object returned by the Route REST Endpoint.	DirectionsViewModel
String	The current state of the view model.	DirectionsViewModel
Object	The name of the network attribute to use for the drive time when computing directions.	DirectionsViewModel
TravelMode []	An array of available travel modes from the associated RouteLayer's routing service (see RouteLayer.url).	DirectionsViewModel
MapView\|SceneView	The view from which the widget will operate.	DirectionsViewModel

Property Details

apiKey Property apiKey String Since: ArcGIS Maps SDK for JavaScript 4.19 DirectionsViewModel since 4.6, apiKey added at 4.19.

An authorization string used to access a resource or service. API keys are generated and managed in the portal. An API key is tied explicitly to an ArcGIS account; it is also used to monitor service usage. Setting a fine-grained API key on a specific class overrides the global API key.

By default, the following URLs will be used (unless overwritten in the app, or if using different defaults from a portal):

Geocoding URL: https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer

Routing URL: https://route-api.arcgis.com/arcgis/rest/services/World/Route/NAServer/Route_World

declaredClass Inherited Property declaredClass Stringreadonly Inherited from Accessor Since: ArcGIS Maps SDK for JavaScript 4.7 Accessor since 4.0, declaredClass added at 4.7.

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

goToOverride Property goToOverride GoToOverride Since: ArcGIS Maps SDK for JavaScript 4.8 DirectionsViewModel since 4.6, goToOverride added at 4.8.

This function provides the ability to override either the MapView goTo() or SceneView goTo() methods.

See also

esri/views/MapView#goTo
SceneView

Example

// The following snippet uses the Search widget but can be applied to any
// widgets that support the goToOverride property.
search.goToOverride = function(view, goToParams) {
  goToParams.options = {
    duration: updatedDuration
  };
  return view.goTo(goToParams.target, goToParams.options);
};

impedanceAttribute Property impedanceAttribute Objectreadonly

The network attribute name to be used as the impedance attribute in the analysis. The value is defined in the specific routing network layer used in the route.

For more information, see Understanding the network attribute.

Properties: name String

Name of the impedance network attribute.

units String

Units of this network attribute.

lastRoute Property lastRoute RouteLayerSolveResultreadonly

The most recent route result. Returns a RouteLayerSolveResult object containing properties for barriers (if any), stops, and directions.

Properties

directionLines Collection<DirectionLine>

Collection of direction polylines associated with line segments between turns.

directionPoints Collection<DirectionPoint>

Collection of direction items as points with various display information.

pointBarriers Collection<PointBarrier>

Collection of point barriers.

polygonBarriers Collection<PolygonBarrier>

Collection of polygon barriers.

polylineBarriers Collection<PolylineBarrier>

Collection of polyline barriers.

routeInfo RouteInfo

Information about a solved route including the route's geometry and overall distance and time.

stops Collection<Stop>

Collection of stops. Represents the start, end, or midpoint of a route.

Default Value:null

See also

RouteLayer.solve()

layer Property layer RouteLayer Since: ArcGIS Maps SDK for JavaScript 4.24 DirectionsViewModel since 4.6, layer added at 4.24.

The RouteLayer associated with the DirectionsViewModel. The route layer contains stops and barriers and will be used to display and solve routes.

maxStops Property maxStops Number

The maximum number of stops allowed for routing.

Default Value:50

routeParameters Property routeParameters RouteParameters

Route Parameters object used to call the service. Please refer to the RouteParameters documentation for the list of available settings.

selectedTravelMode Property selectedTravelMode TravelMode

The travel mode that will be used by getDirections() when requesting the route and directions.

For a list of available travel modes please access travelModes or the supportedTravelModes property on the serviceDescription.

If the RouteLayer assigned to layer is hosted on ArcGIS Online and ArcGIS Enterprise then this property will attempt to assign the previously used travel mode.

By default, if the layer is not an ArcGIS Online and ArcGIS Enterprise item, this property will be to routing service's default travel mode (see defaultTravelMode of ServiceDescription).

Default Value:null

See also

Default travel modes

Example

// Create a RouteLayer and assign to the DirectionsViewModel.
const layer = new RouteLayer();
map.add(layer);

const apiKey = "<your api key>";
const directionsViewModel = new DirectionsViewModel({ apiKey, layer });
await directionsViewModel.load(); // wait for the view model to load the route service's "service description".

// Print view model's selected travel mode. This will be equivalent to the routing service's default travel mode.
console.log(directionsViewModel.selectedTravelMode.name);

// Assign the "Walking Time" travel mode.
directionsViewModel.selectedTravelMode = directionsViewModel.travelModes.find(({ name }) => name === "Walking Time");

serviceDescription Property serviceDescription ServiceDescriptionreadonly

The Service Description object returned by the Route REST Endpoint. This object contains three properties: currentVersion, defaultTravelMode, and supportedTravelModes.

This information is useful when implementing complex logistics scenarios operating with limitations or preferences on vehicle or stop properties, for example avoiding toll roads, dealing with hazardous materials, working with stop service times, etc.

Default Value:null

state Property state Stringreadonly

The current state of the view model.

Possible Values:"disabled" |"ready"

Default Value:"disabled"

timeAttribute Property timeAttribute Objectreadonly

The name of the network attribute to use for the drive time when computing directions.

Properties: name String

The name of the network attribute to use for the drive time when computing directions.

units String

The units to use when calculating drive time for directions.

travelModes Property travelModes TravelMode[]readonly

An array of available travel modes from the associated RouteLayer's routing service (see RouteLayer.url).

view Property view MapView |SceneView

The view from which the widget will operate.

Method Overview

Show inherited methods

Hide inherited methods

Return Type	Summary	Class
	Adds one or more handles which are to be tied to the lifecycle of the object.	Accessor
	Centers the map at the specified maneuver or stop.	DirectionsViewModel
	Clears any highlighted route segments.	DirectionsViewModel
	Removes the route directions from the directions list, leaving the inputs untouched.	DirectionsViewModel
Object	Returns the cost attribute associated with the parsed name.	DirectionsViewModel
Promise<RouteLayerSolveResult>	Computes a route and directions.	DirectionsViewModel
Boolean	Returns true if a named group of handles exist.	Accessor
Promise	Highlights the specified network feature.	DirectionsViewModel
Promise	This method should be called to load the view model's routing resources.	DirectionsViewModel
	Removes a group of handles owned by the object.	Accessor
	Resets the state of the ViewModel, clearing all the input stops and results in the widget and in the map.	DirectionsViewModel
Promise<PortalItem>	Saves the RouteLayer associated with the view model.	DirectionsViewModel
Promise<PortalItem>	Saves the RouteLayer associated with the view model as a new portal item.	DirectionsViewModel
	Zoom so that the full route is displayed within the current map extent.	DirectionsViewModel

Method Details

addHandles Inherited Method addHandles(handleOrHandles, groupKey) Inherited from Accessor Since: ArcGIS Maps SDK for JavaScript 4.25 Accessor since 4.0, addHandles added at 4.25.

Adds one or more handles which are to be tied to the lifecycle of the object. The handles will be removed when the object is destroyed.

// Manually manage handles
const handle = reactiveUtils.when(
  () => !view.updating,
  () => {
    wkidSelect.disabled = false;
  },
  { once: true }
);

this.addHandles(handle);

// Destroy the object
this.destroy();

Parameters

handleOrHandles WatchHandle|WatchHandle []

Handles marked for removal once the object is destroyed.

groupKey *

optional

Key identifying the group to which the handles should be added. All the handles in the group can later be removed with Accessor.removeHandles(). If no key is provided the handles are added to a default group.

centerAt Method centerAt(stopOrManeuver)

Centers the map at the specified maneuver or stop.

Parameter

stopOrManeuver Graphic

The stop or maneuver where the map should be centered.

clearHighlights Method clearHighlights()

Clears any highlighted route segments.

clearResults Method clearResults()

Removes the route directions from the directions list, leaving the inputs untouched. The route and locations persist on the map.

getCostAttribute Method getCostAttribute(attributeName){Object}

Returns the cost attribute associated with the parsed name.

Parameter

attributeName String

The attribute name specifying the cost attribute used as an impedance.

Returns

Type

Description

Object

The cost attribute associated with the passed name.

Property	Type	Description
name	string	Name of the impedance network attribute.
units	string	Units of this network attribute.

getDirections Method getDirections(){Promise<RouteLayerSolveResult>}

Computes a route and directions. If successful, results will be assigned to lastRoute and returned in a resolving promise. If a view is assigned, it will zoom to the extent of the route.

Returns

Type	Description
Promise<RouteLayerSolveResult>	When resolved, returns a RouteLayerSolveResult.

hasHandles Inherited Method hasHandles(groupKey){Boolean} Inherited from Accessor Since: ArcGIS Maps SDK for JavaScript 4.25 Accessor since 4.0, hasHandles added at 4.25.

Returns true if a named group of handles exist.

Parameter

groupKey *

optional

A group key.

Returns

Type	Description
Boolean	Returns `true` if a named group of handles exist.

Example

// Remove a named group of handles if they exist.
if (obj.hasHandles("watch-view-updates")) {
  obj.removeHandles("watch-view-updates");
}

highlight Method highlight(networkFeature){Promise} Since: ArcGIS Maps SDK for JavaScript 4.24 DirectionsViewModel since 4.6, highlight added at 4.24.

Highlights the specified network feature.

Parameter

The network feature to highlight.

Returns

Type	Description
Promise	Resolves when the highlight has been completed.

load Method load(){Promise}

This method should be called to load the view model's routing resources.

This method downloads service metadata from the assigned routing service. Call this method before accessing properties on the view model or whenever the layer changes.

Returns

Type	Description
Promise	When resolved, the view model has loaded the route service metadata necessary for routing.

removeHandles Inherited Method removeHandles(groupKey) Inherited from Accessor Since: ArcGIS Maps SDK for JavaScript 4.25 Accessor since 4.0, removeHandles added at 4.25.

Removes a group of handles owned by the object.

Parameter

groupKey *

optional

A group key or an array or collection of group keys to remove.

Example

obj.removeHandles(); // removes handles from default group

obj.removeHandles("handle-group");
obj.removeHandles("other-handle-group");

reset Method reset()

Resets the state of the ViewModel, clearing all the input stops and results in the widget and in the map.

save Method save(){Promise<PortalItem>} Since: ArcGIS Maps SDK for JavaScript 4.24 DirectionsViewModel since 4.6, save added at 4.24.

Saves the RouteLayer associated with the view model. This method will update the portal-item associated with layer.

Returns

Type	Description
Promise<PortalItem>	When resolved, returns a PortalItem.

See also

saveAs Method saveAs(portalItem, options){Promise<PortalItem>} Since: ArcGIS Maps SDK for JavaScript 4.24 DirectionsViewModel since 4.6, saveAs added at 4.24.

Saves the RouteLayer associated with the view model as a new portal item.

Parameters

portalItem Promise<PortalItem>

The new portal item to which the layer will be saved.

options Object

optional

Save options. Currently, there is only one property that can be set, which is folder.

Specification

folder PortalFolder

optional

The folder in which to save the item.

Returns

Type	Description
Promise<PortalItem>	Saved portal item.

See also

zoomToRoute Method zoomToRoute()

Zoom so that the full route is displayed within the current map extent.