Develop your first map app

This topic describes how to display a map in your application. It's assumed that:

  • You've created a project named MyFirstMapApp using Apple's iOS Single View Application Xcode project template
  • You've configured your project as described in Set up (configure your Xcode project) to ensure your project can properly reference ArcGIS Runtime SDK for iOS

The primary way to display geographic information in your application is through a map view. The API provides a user interface (UI) component called a map view (AGSMapView) which lets you display the content of a map. The map is represented by AGSMap object that can use to define the map's basemap and operational layers, or you can open an existing map from ArcGIS Online, or an on-premises portal.

1. Add a map view to the UI

The first step in displaying a map in your application is to add a map view to your application's UI. This map view acts as an empty canvas in which you'll later display map.

The user inteface (UI) of iOS applications is typically contained in one or more storyboard files (.storyboard extension). These files contain various scenes that comprise your application. Each scene defines the styling, positioning, and layout of UI Components as well as the relationship and transitions to other scenes. Each scene is typically associated with a view controller that contains code to respond to user interaction and to optionally perform some setup and teardown tasks. This separation of view and controller objects is based on the Model-View-Controller design pattern.

To make things simple, assume you're only building an iPhone application at this time. You'll add a map view to the UI contained in the Main storyboard.

When you select the storyboard file in the Project Navigator pane on the left, its contents are displayed in the Canvas section on the right where you can compose the UI visually. Between the Project Navigator and the Canvas lies the Dock, which provides a convenient list of all the view controller scenes & UI components currently in the storyboard. At this point, you'll probably have just one view controller scene in your storyboard. We'll be adding a map to this scene.

The right most section in Xcode is the Utility area, which contains the Inspector pane (top) and Library pane (bottom). The Inspector allows you to inspect and change properties of UI components in the storyboard, and the Library allows you to pick UI components, media, code snippets, and so on, to add to your project.

To add a map view, select a generic UIView object from the Library pane and drag and drop it onto the view shown in the Canvas.

This UIView object acts as a place holder for the map that needs to be displayed in the application. For the purpose of this project, resize the UIView, if necessary, so that it totally covers the view beneath. This will ensure that your map is displayed full screen.

Before this UIView can display your map, you need to change it to a map view. You do this by specifying AGSMapView as the class for this object in the Inspector.

Note:

When adding UI components, you typically also need to specify Auto layout constraints for the components so that they can be properly sized and positioned when the layout of your application changes, for example, when the device is rotated. For the sake of simplicity, we will skip setting layout constraints in this tutorial, but you can look at the accompanying tutorial app to see these constraints in action.

2. Connect the map view to the view controller

Now that you've added a map view to the UI, you need to connect it to the view controller so that you can programmatically access it. This will allow you to add content to it and respond to user interaction.

To do this, first you need to enable the Assistant Editor so that the view controller's swift file (ViewController.swift) is displayed along side the Canvas. You can then right-click the map view in the Dock and drag and drop it in the swift file shown in the Assistant Editor.

Upon doing so, Xcode will automatically prompt you for a name so that it can create an outlet connection from the view controller to the map view in the UI. Call this outlet mapView.

If you attempt to build your application at this stage, you'll get compile errors because the view controller contains reference to the AGSMapView class, which hasn't been defined. To fix these errors, you need to import the ArcGIS framework into the view controller's swift file. This will allow you to reference any class in the ArcGIS Runtime SDK for iOS.

import UIKit

//Import the ArcGIS framework
import ArcGIS

class ViewController: UIViewController {

  @IBOutlet weak var mapView: AGSMapView!
  ...
}

3. Add content to the map

Now that you've added a map view to the UI and connected it to the view controller, you need to choose the content to be displayed in the map view. By default, a map view does not display anything, so the next step is to define a map to be displayed. You will specify that the map show worldwide imagery from ArcGIS Online. As it's often more useful for an app to initially display a specific region rather than its entire extent, you'll also set the map to zoom in to a specific center point—showing the Esri campus in Redlands, California.

Select the ViewController.swift file in the Navigator to open it in the source editor. Locate the viewDidLoadmethod. This method is executed when the view controller's UI is displayed, giving the view controller a chance to add some behavior or adjust the display. You'll create a map using Esri's imagery service provided by ArcGIS online and also specify the initial location and scale level to zoom in to.You will also assign this map to the map view.

override func viewDidLoad() {
 super.viewDidLoad()

 //Display a map using the ArcGIS Online imagery basemap service
 self.mapView.map = AGSMap(basemapType: .imageryWithLabelsVector, latitude: 34.057, longitude: -117.196, levelOfDetail: 17)

}

If you run the application now, the map displays contents from the ArcGIS Online map service.