This tutorial covers the following:
The Directions widget calculates directions between two or more locations and makes it easy to add turn-by-turn directions to a page as well as a route to a map. This tutorial describes how to add the Directions widget to a map, customize the page layout to show the Directions widget in a side bar next to the map and optionally specify your own network analysis service instead of the default routing service.
Before starting, you'll need a page with a map in it. If you do not have one or know how to create one, please refer to the Create a Map sample. An ArcGIS.com subscription with World Network Analysis is also required. Alternatively, you can use your own ArcGIS Server Network Analysis service. In addition, be sure you are using the latest ArcGIS API for JavaScript. The Directions widget was first available with version 3.4 and is in all subsequent versions.
Use require()
to load the esri/dijit/Directions
module and alias it as Directions
in the callback function. Also load a couple Dojo layout modules that simplify page layout. More on the layout modules in steps five and six.
require([ "esri/map", "esri/dijit/Directions", "dojo/parser", "dijit/layout/BorderContainer", "dijit/layout/ContentPane" ], function (Map, Directions, parser) { // code goes here });
Add a new <div>
element with an ID of dir
before <div id="map"></div>
to your HTML. This element will contain the user interface for the widget.
<div id="dir"></div>
Add a new Directions widget to the page. In the constructor, several options are available for the widget the first parameter options
. After creating the widget, be sure to call startup().
var directions = new Directions({ map: map }, "dir"); directions.startup();
In the code above, map
specifies which map this widget is associated with. The second parameter, srcNodeRef
, specifies the ID of the DOM element where this widget will be created. Other available options can be found at the class reference page.
The Directions widget uses the World Network Analysis as the default service to calculate driving directions. An ArcGIS Online subscription is required to use this service. By default, a log-is required when using ArcGIS.com for a routing task. If you have an ArcGIS Server Network Analysis service that you want to use to calculate directions, specify the url to the service using the Directions widget routeTaskUrl
constructor parameter. Also refer to the "Use Your own Network Analyst Service" section below.
To use the layout widgets loaded in step two, add some DOM elements with custom attributes. The markup below sets up a border container with two content panes: one for the map and one for the directions widget.
<div data-dojo-type="dijit/layout/BorderContainer" data-dojo-props="design:'headline', gutters:false" style="width:100%;height:100%;"> <div data-dojo-type="dijit/layout/ContentPane" data-dojo-props="region:'right'" style="width:250px;"> <div id="dir"></div> </div> <div id="map" data-dojo-type="dijit/layout/ContentPane" data-dojo-props="region:'center'"> </div> </div>
Once the markup for Dojo layout widgets is in place, they need to be parsed. It's possible to use dojoConfig.parseOnLoad
to do this, but the recommended approach is to load dojo/parser and call parser.parse() explicitly. By using custom data attributes, the dojo parser is able to find, create and properly size page layout components. Refer to Dojo's Dijit layout documentation for more information on what these modules do and how to use them.
require([ "esri/map", "esri/dijit/Directions", "dojo/parser", "dijit/layout/BorderContainer", "dijit/layout/ContentPane" ], function (Map, Directions, parser) { // call the parser parser.parse(); // additional code to create a map and directions widget });
At this point, you have a simple web mapping application with the Directions widget. Enter various locations to see the directions that are calculated and displayed. A live version of this tutorial is avaiable as Directions Widget sample.
If you prefer to use your own network analysis service instead of the default World Routing Service,
you may specify an option routeTaskUrl
with the URL path to your own network analysis service in the constructor. For example:
var directions = new Directions({ map: map, routeTaskUrl: "https://sampleserver6.arcgisonline.com/arcgis/rest/services/NetworkAnalysis/SanDiego/NAServer/Route", }, "dir");