Viewing a Web Map

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

You can create and share web maps interactively on www.ArcGIS.com using applications like ArcGIS Explorer Online or the built-in ArcGIS.com Viewer. You can then view these web maps 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.

Opening a Web Map

At the time of writing this document, ArcGIS API for iOS only supports reading the layer information in a web map. All other information in the web map is ignored. When you open a web map using the API, the layer information in the web map is used to construct and add layers to a map view.

To open a web map, you need to first instantiate an AGSWebMap object.

If the web map is hosted on www.arcgis.com, you only need to provide the ID of the web map to open. You can find this ID in the URL of the web map.

Web Map on www.arcgis.com

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

AGSCredential* credential = [[[AGSCredential alloc] initWithUser:@"<user>" password:@"<password>"] autorelease];
credential.authType = AGSAuthenticationTypeToken;
NSError* error = nil;
AGSWebMap* wm = [AGSWebMap webMapWithItemId:@"e229d715f7ca4fa980308549fb288165" credential:credential error:&error];

If the web map is hosted outside www.arcgis.com, for example, on an ArcGIS Server Mobile Content Server, you will also need to provide the URL of the endpoint where the web map's data can be accessed. Here is an example:

NSURL* endpoint = [NSURL URLWithString:@"http://<server>/arcgis/mobile"];
AGSWebMap* wm = [AGSWebMap webMapWithItemId:@"e229d715f7ca4fa980308549fb288165" sharingEndPoint:endpoint credential:credential error:&error];

Note, instantiating a AGSWebMap object is a synchronous operation. You shouldn't perform it on the main application thread as it may prevent your application from responding to user input while the web map information is being retrieved from the server. Following is an example of how to open a web map on a background thread when a view controller is loaded:

- (void)viewDidLoad {
  [super viewDidLoad];
  ...
  //Open the web map on a background thread
  [self performSelectorInBackground:@selector(loadWebMap) withObject:nil];
}

//this method is called on a background thread
- (void) loadWebMap {
  //create a new autorelease pool so we don't leak any memory on this thread
  NSAutoreleasePool* pool = [[NSAutoreleasePool alloc] init];
  
  //Initialize a web map
  NSError* error = nil;
  self.webMap = [AGSWebMap webMapWithItemId:@"e229d715f7ca4fa980308549fb288165" credential:nil error:&error];
  if(error!=nil){
   	NSLog(@"Error opening web map: %@",[error localizedDescription]);
   	return;
  }

  //designate a delegate to be notified as web map is opened
  self.webMap.delegate = self;

  //open web map 
  [self.webMap openIntoMapView:self.mapView];

  //drain the pool
  [pool release];
}

During the opening process, the web map's delegate is informed when each layer in the web map is loaded successfully. If any layers fail to load, the delegate is given an opportunity to skip to the next layer, or re-try loading the current layer with proper credentials if the layer was using a secured service. If the web map contains a Bing Maps layer, the delegate is asked to provide a valid Bing Maps app ID to use with that layer. Here is an example of an class that adopts the AGSWebMapDelegate protocol and can serve as a web map's delegate:

@interface MyViewController : UIViewController <AGSWebMapDelegate> {

  ...

  -(void)didOpenWebMap:(AGSWebMap*)webMap intoMapView:(AGSMapView*)mapView ;
  -(void)didFailToLoadLayer:(NSString*)layerTitle withError:(NSError*)error ;
  -(void)didLoadLayer:(AGSLayer*)layer ;
  -(NSString*)bingAppId ;
}

@implementation MyViewController {
  
  ...

  -(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(@"err:%@",error);
     //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>";
  }


}