ArcGIS API for iOS - Viewing a Web Map

A webmap basically describes the contents to be displayed in a map. At its core, a webmap contains information about the layers that need to be displayed in a map, their order, visibility, and rendering details. A webmap can also contain additional information such as bookmarks, notes, slides, tasks, widgets, etc.

You can create and share webmaps interactively on www.ArcGIS.com using applications like ArcGIS Explorer Online or the built-in ArcGIS.com Viewer. You can then view these webmaps using a variety of web and mobile clients, including your custom applications built using the ArcGIS API for iOS.

Learn more about working with maps.

The API only supports a subset of information in the web map, such as the layer information, popup definitions, and bookmarks. All other information in the webmap is ignored. The layer information is used to construct and add layers to a map view. The popup definitions are used to display and edit feature details using AGSPopupsContainerViewController. The bookmarks are made available as AGSEnvelope objects which can be used to zoom the map into specific areas.

Note:

If you're interested in accessing the information stored in the webmap, you can get the raw JSON data of the webmap from the json property on the AGSWebMap object.

To view the contents of a webmap, you need to

Load the webmap
Set the delegate
Open into a map view

1. Load the webmap

To load a webmap you need to instantiate an AGSWebMap object.

If the webmap is hosted on www.ArcGIS.com and publicly accessible, you only need to provide the ID of the webmap when instantiating AGSWebMap. You can find this ID in the URL of the webmap.

Web Map on www.arcgis.com

However, if the webmap is private or shared only with a few people, you will also need to provide valid credentials to access the webmap. Here is an example:

AGSCredential* credential = [[[AGSCredential alloc] initWithUser:@"<user>" password:@"<password>"] autorelease];
credential.authType = AGSAuthenticationTypeToken;
AGSWebMap* webmap = [[AGSWebMap alloc] initWithItemId:@"e229d715f7ca4fa980308549fb288165" credential:credential];

If the webmap is hosted outside www.arcgis.com, for example, on your enterprise ArcGIS Portal, you will also need to provide the URL of the sharing endpoint where the webmap's data can be accessed. Here is an example:

NSURL* endpoint = [NSURL URLWithString:@"http://<my_arcgis_portal>/sharing"];
AGSWebMap* webmap = [[AGSWebMap alloc] initWithItemId:@"e229d715f7ca4fa980308549fb288165" sharingEndPoint:endpoint credential:credential];

When you create the AGSWebMap object, you need to ensure you take ownership of it. Otherwise, its memory might get deallocated before it has a chance to execute. If you instantiate the webmap using alloc as shown above , you automatically have ownership. However, if you instantiate the webmap using a convenience constructor, for instance webMapWithItemId:credential: , you explicitly need to take ownership by either sending it a retain message, or by assigning it to a property that will retain it.

When you are finished using the webmap, you should relinquish ownership so that its memory can be reclaimed. You do this either by sending it a release message or by setting the corresponding property to nil.

Note:

Please refer to Apple's Memory Management Programming Guide for more information on how to manage object memory.

2. Set the delgate

The webmap informs its delegate when operations complete successfully or if errors are encountered.

When loading a webmap, the delegate is informed whether the webmap data is retrieved successfully or not.

When opening a webmap into a map view, the delegate is informed when each layer in the webmap is loaded successfully. If any layer fails to load, the delegate is given an opportunity to skip to the next layer, or re-try loading the current layer with different credentials. If the webmap contains a Bing Maps layer, the delegate is asked to provide a valid Bing Maps App ID to use with that layer.

To respond to such events, you must set one of your classes as the webmap's delegate. You do this by making your class (typically the view controller which uses the webmap) adopt the AGSWebMapDelegate protocol.

@interface MyViewController : UIViewController <AGSWebMapDelegate> {

  ...

}

An instance of your class must then be set as the webmap's delegate. This will allow the webmap to invoke methods on your class in response to operations that the webmap performs.

webmap.delegate = self;

Finally, your class should implement one ore more methods defined in the AGSWebMapDelegate protocol which pertain to the event you want to handle. Here is an example :

@implementation MyViewController {
  
  ...

  - (void) webMapDidLoad:(AGSWebMap*) webMap {
    //webmap data was retrieved successfully
  }
  
  - (void) webMap:(AGSWebMap *)webMap didFailToLoadWithError:(NSError *)error {
    //webmap data was not retrieved
    //alert the user
    NSLog(@"Error while loading webmap: %@",[error localizedDescription]);
  }

  -(void)didOpenWebMap:(AGSWebMap*)webMap intoMapView:(AGSMapView*)mapView{
   	//web map finished opening
  }

  -(void)didLoadLayer:(AGSLayer*)layer{
  	 //layer in web map loaded properly
  }
 
  -(void)didFailToLoadLayer:(NSString*)layerTitle withError:(NSError*)error{
    	NSLog(@"Error while loading layer: %@",[error localizedDescription]);
     //you can skip loading this layer
     //[self.webMap continueOpenAndSkipCurrentLayer];
     //or you can try loading it with proper credentials if the error was security related
     //[self.webMap continueOpenWithCredential:credential];
  }

  -(NSString*)bingAppId{
  	return @"<your_bing_app_id>";
  }


}

3. Open into map view

After setting the delegate, all that is left to do to view the contents of a webmap is to open the webmap into a map view.

[webmap openIntoMapView:self.mapView];

Note, the map will be reset to an unloaded state before opening the webmmap. This means, any preexisting layers will be removed and the extent and spatial reference information of the map will be cleared.

9/14/2011