Directions widget

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. Modify the page layout
  6. Create layout widgets with markup
  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 trivial 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 module that creates the Directions widget.

    require([
      "esri/map",
      "esri/dijit/Directions",
      "esri/layout",
      "dojo/domReady!"
    ], function (Map, Directions, Layout) {
        // 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 esri.dijit.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. Modify the page layout

    Load Dojo's layout widgets using the esri/layout module.

    require(["esri/dijit/Directions", "esri/layout", ... ],
      function(Directions, Layout, ... ) {
      // ...
    });
    

  6. Create layout widgets with markup

    Modify the page's markup so that the map and Directions widget are in their own content panes inside of a BorderContainer.

    <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>
    

    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 complete code sample can be found in the Simple Directions Widget sample page.

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