ArcGIS API for JavaScript ^3.29

This tutorial covers the following:

1. Introduction to the Directions widget
2. Load the Directions widget
3. Add a DOM element for the widget
4. Create an instance of the Directions widget
5. Create layout widgets with markup
6. Bring the page layout to life
7. Bonus: Use your own network analyst service

1. Introduction to the Directions widget

   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.

2. Load the Directions widget

   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
   });
   

3. Add a DOM element for the widget

   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>
   

4. Create an instance of the Directions widget

   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.

5. Create layout widgets with markup

   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>
   

6. Bring the page layout to life

   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.

7. Bonus: Use your own network analyst service

   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: "http://sampleserver3.arcgisonline.com/ArcGIS/rest/services/Network/USA/NAServer/Route",
   }, "dir");