Description

Get your organization's authoritative map data into the hands of your workers with this ArcGIS API for JavaScript app. The application you build can include a custom web map from your ArcGIS Online organization. For example, a web map from the Living Atlas can be used as a starting place for your app. The maps-app also includes examples of place search and routing capabilities using either ArcGIS Online's powerful services or your own services. It also leverages your organizations configured basemaps to allow users to switch between the basemap that make sense for them.

This example application is open source so grab the code at GitHub and either configure the app for your organization, or just learn how to integrate similar capabilities into your own app!

Functionality showcased

  • Switching basemaps
  • Loading web maps from an organization
  • Searching for an address or place (geocoding)
  • Searching for a location on the map (reverse geocoding)
  • Routing and turn by turn directions
  • Authentication with OAuth2

Using Web Maps

You can author your own web maps from ArcGIS Online or ArcGIS Pro and share them in your app via your ArcGIS Online organization. This is the central power of the Web GIS model built into ArcGIS. Building an app which uses a web map allows the cartography and map configuration to be completed in ArcGIS Online rather than in code. This then allows the map to change over time, without any code changes or app updates. Learn more about the benefits of developing with web maps here. Also, learn about authoring web maps in ArcGIS Online and ArcGIS Pro.

Loading web maps in the code is easy; the maps app loads a web map from a portal (which may require the user to log in, see the identity section below) with the following code:

// config.ts
export const webMapItem = {
  portalItem: {
    // shared WebMap
    id: "3ff64504498c4e9581a7a754412b6a9e"
  }
};

// Application.ts
@subclass("app.widgets.Application")
class Application extends declared(Accessor) {
  @property({ readOnly: true })
  webmap = new WebMap(webMapItem);
  ...
}

Accessing Your Organization's Basemaps

As an administrator of an ArcGIS Online organization or Portal you can configure the basemaps that your users can switch between via a group. Applications can leverage this configuration using the Portal API. The Maps App uses the BasemapGallery widget from the ArcGIS API 4 for JavaScript.

All you need to do is instantiate it, then when a user logs in, it will switch to the basemaps configured to the user’s organization.

const basemapGallery = new BasemapGallery({
  container: element(),
  view
});

Identity

The Maps App leverages the ArcGIS identity model to provide access to resources via the named user login pattern.

To access the Directions widget, you must log in via the provided Authenticate widget. Once logged in, the Directions widget is available for use as well as the custom WebMapBrowser widget.

The Directions Widget provides a way to build driving and walking directions using ArcGIS online and custom Network Analysis Route services. By default, it uses the Esri World Route Service.

The WebMapBrowser widget is a custom widget in the Maps App that is used to browse any web maps that are part of your content in your organization. The WebMapBrowser widget allows you to switch the web map used in your application.

All you need to do is provide a valid Client ID in the configuration file, along with a Portal URL if it differs from the default, and it will be used by the Authentication workflow of the application.

// src/app/config.ts
/**
 * Registered application id.
 * This is needed to be able to use premium
 * services such as routing and directions.
 */
export const appId = "<APP-ID>";

/**
 * Users Portal URL.
 */
export const portalUrl = "https://arcgis.com"; // default Portal URL

The Search widget is utilized to let you transform an address or a place name to a specific geographic location. The reverse lets you use a geographic location to find a description of the location, like a postal address or place name. The Search widget performs geocoding and reverse geocoding functions provided by Esri's World Geocoding Service.

You can customize the sources used by the Search widget to use your own custom Geocode Service or a Feature Service as a source.

Suggestions are supported out-of-the-box with the Search widget. You can customize the min and max suggestions returned if not defined by custom sources you provide.

Reverse Geocoding

The Map App uses the "hold" event of the MapView and sends the selected location to the search method of the of the Search widget to reverse geocode the selected location..

// src/app/mapactions/reverseGeocode.ts

@subclass("app.mapactions.ReverseGeocode")
export class ReverseGeocode extends declared(MapAction)<esri.SearchResponse> {
  @property() search: Search;

  constructor(params?: ReverseGeocodeOptions) {
    super(params);
    this.reverseGeocode = this.reverseGeocode.bind(this);
    if (this.view) {
      this.addListeners();
    }
    this.watch("view", () => {
      this.addListeners();
    });
  }

  addListeners() {
    const handler = this.view.on("hold", this.reverseGeocode);
    this.handlers.push(handler);
  }

  async reverseGeocode({ mapPoint }: GeocodeOptions) {
    const response = await this.search.search(mapPoint);
    this.value = response;
  }
}

Route

Getting navigation directions in the maps-app is just as easy in the ArcGIS API for JavaScript as it is on ArcGIS Online. You can customize your navigation services for your organization, add new travel modes that better reflect your organization’s workflows, or remove travel modes that are not suitable for your organization’s workflows.

You can update the default route service URL in the Directions widget to that of your organization.

For more samples on using the ArcGIS API for JavaScript, see the documentation.

Source Code on GitHub
In this topic