[Swift MapKit Tutorial Series] How to Display and Manage Different Custom Pin Annotations View Objects on the Map

Update April 2016: Fully updated for iOS 9.3 (Xcode 7.3 and Swift 2.2).

Lot of stuff was demonstrated in the first and second tutorials of this series, you learned how to search any place or POI and how Apple maps API got lot smarter analysing the human query even for uncompleted addresses. You also worked with the great MKMapItem API to discover the place details, and along the way, you did great effort implementing the presentation controller with the pop over context in iOS 8.

In this tutorial, you will work with the world bank API to get useful data about the income level of different countries around the world.

Along the way, I gonna show you how to display and manage multiple and different pin annotations on the map, and how to customise the default pin view with a custom image. The data will be pulled remotely from the world bank API with a HTTP request, so you will work with the neat NSURLSession class to get that right in your app.

By the end of this tutorial, you can have a useful app targeting a specific audience and you can submit it to the Apple Store if you want 🙂

Note: This tutorial is independent from the two previous tutorials, you don’t have to read them to build the app in this one, here you will do everything from scratch.

Let’s do this!

Open up Xcode, select ‘File\New\Project’ from the menu. Choose ‘Single View Application’ from the templates list in the ‘iOS\Application’ tab. Name the project ‘WorldIncomeLevel’ and make sure the language is Swift and that your app will be targeting all devices by selecting ‘Universal’ from the ‘Devices’ menu.

Cool, now we are going to set up the simple UI for the project. Basically, there will be a button, a navigation bar and a map to display all pin annotations for the income level countries. On button click, a pop over list will be shown to select the area in the world you want to show the income level for.

Select Main.storyboard file from the Project navigator, then click on the view controller from the Document Outline area.

Now select ‘Editor\Embed In\Navigation Controller’ from the menu. We need to embed the view scene in a navigation controller to take advantage of the navigation bar in which you gonna put the bar button right away.

From the Object library, drag a UIBarButtonItem and place it to the left of the navigation bar in the view controller scene.

Now switch to the ‘Attributes inspector’ view and change the System Item property of the bar button item to ‘Add’.

Also, select the navigation bar and change its title to ‘Income Level Map’ from the ‘Attributes inspector’ view.

Here is how the navigation bar should look like:

Good, now drag a Map Kit View object from the Object library to the view controller scene, select the ‘Size inspector’ view and set its X to 0, Y to 64, Width to 600 and Height to 536.

Select the Pin menu, make sure the ‘Constrain to margins’ checkbox is UNchecked and activate the top, leading, bottom and trailing spacing constraints as shown in the following screenshot.

Don’t forget to select the ‘Add Constraints’ button in the Pin menu to apply the Auto Layout changes.

Now, let’s hook up the objects to the class in order to manipulate them from within the code. To do so, switch to the ‘Assistant editor’ and follow the steps below:

1/ Ctrl+drag from the bar button item to the view controller (just below the class name), make sure it’s an ‘Outlet’ from the Connection drop down list and name it ‘areaListBtn’.

2/ Ctrl+drag from the map view to the view controller (just below the class name) and select ‘Outlet’ from the Connection drop down list. Name it ‘mapView’ and click the ‘Connect’ button.

3/ Ctrl+drag again from the bar button item to the view controller (just below the class name). This time, make sure it’s an ‘Action’ from the Connection drop down list and name it ‘showAreaList’.

Don’t forget to import the MapKit framework by placing the following line above the class name in the ViewController.swift file:

import MapKit

So far, the class looks like the following:

import UIKit
import MapKit

class ViewController: UIViewController {

    @IBOutlet var mapView: MKMapView!
    @IBOutlet var areaListBtn: UIBarButtonItem!
    @IBAction func showAreaList(sender: AnyObject) {
    }
    //...    

Last thing before you move to coding is to import some images to the project for the custom pins annotations in the map.

We will be dealing with four different income levels, so there will be four custom icons, start by downloading them here.

The best way to import images to Xcode is within the asset catalog. First select ‘Assets.xcassets’ from the ‘Project navigator’, then click the ‘+’ button at the bottom of the window and select ‘New Image Set’ from the list. Name the image set ‘High income’. Now just unzip the folder you downloaded earlier and drag the image ‘HI@2x.png’ to the 2x placeholder in the image set, also drag ‘HI@3x.png’ to the 3x placeholder.

Repeat the same steps to make three more image sets, name them ‘Lower income’, ‘Lower middle income’ and ‘High middle income’, and import the images respectively from the folder to their placeholders.

The final asset catalog should look something like this:

Cool, now time to code and get this app to work 🙂

Select ViewController.swift from the Project navigator view and add the following variable declarations right after the class name:

 var contentController : UITableViewController!
 var areaListTable: UITableView!
 var selectedItemIndex: Int!

 var regionNames = [
                       "Africa",
                       "East Asia and the Pacific",
                       "Central Europe and the Baltics",
                       "Europe and Central Asia",
                       "Latin America and the Caribbean",
                       "Middle East and North Africa",
                       "South Asia",
                       "European Union",
                       "North America",
                       "North Africa",
                       "South Asia"
                   ]
    
var regionCodes = [
                       "AFR",
                       "CEA",
                       "CEB",
                       "CEU",
                       "CLA",
                       "CME",
                       "CSA",
                       "EUU",
                       "NAC",
                       "NAF",
                       "SAS",
                  ]

As you may know, ‘contentController’ will handle the content inside the pop over controller, whereas, ‘areaListTable’ is the table view which will be embedded inside the content controller. All areas will be shown in a table view within a list style, the table data source will be the ‘regionNames’ array, while the ‘selectedItemIndex’ variable will store the selected region area from the table view. The ‘regionCodes’ array contains all region codes, this is useful to construct the url request later on, since the region code is a parameter of the requested API.

Next, locate the viewDidLoad function and add the following code inside (right after the super.viewDidLoad statement):

contentController = UITableViewController()
areaListTable = UITableView()
areaListTable.dataSource = self
areaListTable.delegate = self
contentController.tableView = areaListTable
selectedItemIndex = -1
mapView.delegate = self

Basically, this will initialise the content table view controller and embed the table view object inside it. Setting the ‘selectedItemIndex’ to -1 is important since it happens that the user can select no item, in such case, this variable will be storing a value other than 0 (being 0 is the first index in the table view).

Let’s make the class adopt the table view data source and delegate protocols as well as the map view delegate protocol, update the class name to look like the following:

class ViewController: UIViewController, UITableViewDataSource, UITableViewDelegate, MKMapViewDelegate {

Now, let’s put in the data source protocol code for the table view to load its data, place the following code before the closing bracket of the class:

func tableView(tableView: UITableView,
        cellForRowAtIndexPath indexPath: NSIndexPath) -> UITableViewCell{
            
      var cell:UITableViewCell! = tableView.dequeueReusableCellWithIdentifier("cellIdentifier")
if cell == nil{
      cell = UITableViewCell(style: UITableViewCellStyle.Value1, reuseIdentifier: "cellIdentifier")
      cell.textLabel?.text = regionNames[indexPath.row]
}
        cell.accessoryType = UITableViewCellAccessoryType.None
        return cell
}
func tableView(tableView: UITableView,
       numberOfRowsInSection section: Int) -> Int{
        return regionNames.count
}

This is the required data source implementations, data is being extracted from the ‘regionNames’ array as we talked about earlier.

Next, locate the ‘showAreaList’ function and place the following code inside:

contentController.modalPresentationStyle = UIModalPresentationStyle.Popover
let popOverPC: UIPopoverPresentationController = contentController.popoverPresentationController!
popOverPC.barButtonItem = areaListBtn
popOverPC.permittedArrowDirections = UIPopoverArrowDirection.Any
popOverPC.delegate = self
presentViewController(contentController, animated: true, completion: nil)

This will create and present a pop over controller to show after the click on the bar button. Don’t forget to adopt the class to the UIPopoverPresentationControllerDelegate protocol, to do so, update the class name with the following:

class ViewController: UIViewController, UITableViewDataSource, UITableViewDelegate, MKMapViewDelegate, UIPopoverPresentationControllerDelegate {

So far, if you run the app on iPad, you will notice the pop over is shown correctly since it has enough space to draw the pop over layout on the screen. However, if you run on iPhone screens, the pop over will show up as a modal screen instead. This is cool, but the modal controller is missing a top bar to prevent content from overlapping underneath the status bar, so let’s add that along with a dismiss button.

Before the closing bracket of the class, place the following code:

 func adaptivePresentationStyleForPresentationController(controller: UIPresentationController) -> UIModalPresentationStyle{
        return .FullScreen
    }
    func presentationController(controller: UIPresentationController,
        viewControllerForAdaptivePresentationStyle style: UIModalPresentationStyle) -> UIViewController?{
            let navController:UINavigationController = UINavigationController(rootViewController: controller.presentedViewController)
            controller.presentedViewController.navigationItem.rightBarButtonItem = UIBarButtonItem(barButtonSystemItem: UIBarButtonSystemItem.Done, target: self, action:#selector(done))
            areaListTable.reloadData()
            selectedItemIndex = -1
            return navController
    }

This will ask the delegate to display the presented content on full screen mode for all compact width screens (like iPhone portrait). It will also embed the presented content into a navigation controller and add a right bar button to dismiss the modal controller manually.

Before you run the app, let’s quickly add the ‘done’ function code which will be called after you click on the bar button, to dismiss the modal controller.

Place the following code somewhere in the class:

func done (){
        presentedViewController?.dismissViewControllerAnimated(true, completion: nil)
}

Run the app and make sure the content is displayed, and correctly dismissible on all devices and orientations.

Let’s add some UITableViewDelegate protocol methods to show the user selection on the list. Place the following code somewhere in the class before the closing bracket:

func tableView(tableView: UITableView,
        didSelectRowAtIndexPath indexPath: NSIndexPath){
    let selectedCell:UITableViewCell = tableView.cellForRowAtIndexPath(indexPath)!
    selectedCell.accessoryType = UITableViewCellAccessoryType.Checkmark
    selectedItemIndex = indexPath.row
}
func tableView(tableView: UITableView,
    didDeselectRowAtIndexPath indexPath: NSIndexPath){
    let deselectedCell:UITableViewCell = tableView.cellForRowAtIndexPath(indexPath)!
    deselectedCell.accessoryType = UITableViewCellAccessoryType.None
}

This will add a nice checkmark to the selected item in the table view. Also, the didDeselectRowAtIndexPath method will ensure that there will be only one checkmark at a time in the list, since the API will handle one area search at a time.

Run the app on iPad simulator and try to select an item from the table view, dismiss the pop over and then load it again, you may notice the previous selection is not cleared. This is because the table view in the pop over context is not refreshed implicitly, so you have to reload it manually to clear the previous selection. To do so, place the following code before the closing bracket of the class:

func prepareForPopoverPresentation(popoverPresentationController: UIPopoverPresentationController){
    areaListTable.reloadData()
    selectedItemIndex = -1
}

So far so good, the content is presented correctly, but it needs to be interactive with the user selection. The normal behaviour is to get the selected row in the presented list and, based on it, the app will search “local income” data for that area in the world.

The starting point of all the mapping work will be after the user dismissing the presented content, at that time, the app will start a networking process and map displaying of pins.

Locate the ‘done’ function you implemented earlier and add the following statement before its closing bracket:

mapSearch()

Note: Unlike on compact width screens, the presented pop over controller content doesn’t have a button to dismiss when you run the app on iPad screen (regular width). So in this case, you have to detect the dismiss event of the pop over controller and react accordingly. To do so, just add the following code inside the class:

func popoverPresentationControllerDidDismissPopover(popoverPresentationController: UIPopoverPresentationController){
    mapSearch()
}

Now time to implement the mapSearch function, go ahead and place the following code before the closing bracket of the view controller class:

 func mapSearch(){
        if selectedItemIndex == -1{
            return
        }
        //Map search for Level Income in the selected region area
        let url:NSURL = NSURL(string: "http://api.worldbank.org/country?per_page=100&region=\(regionCodes[selectedItemIndex])&format=json")!
        let task = NSURLSession.sharedSession().dataTaskWithURL(url) { (data:NSData?, response: NSURLResponse?, error:NSError?) -> Void in
            
            do {
                let json = try NSJSONSerialization.JSONObjectWithData(data!, options: NSJSONReadingOptions.MutableContainers) as! NSArray
                let dataArray = json.objectAtIndex(1) as! NSArray
                dispatch_async(dispatch_get_main_queue(), {
                     self.displayRegionIncomeLevel(dataArray as [AnyObject])
                })
            }catch{
                print("Some error occured")
            }
            
        }
        // Call the resume() method to start the NSURLSession task
        task.resume()
    }

This will check whether the user has actually selected an item from the list, then it will construct a url with the chosen area and request data via the NSURLSession dataTaskWithURL API. The rest of the code is just a JSON converting stuff since we cannot deal with pure Foundation object, hence you converted it to JSON with the NSJSONSerialization.JSONObjectWithData API. Finally, you called another function to display the income level regions in the map.

We are almost done, let’s implement the displayRegionIncomeLevel method which will put together all map pins for the income level area. Place the following code inside the class body:

func displayRegionIncomeLevel(data:[AnyObject]){
        if data.count == 0{
            return
        }
        //1
        // Change the Map Region to the first lon/lat in the array of dictionaries
        let regionLongitude = data[1]["longitude"]
        let regionLatitude = data[1]["latitude"]
        let center:CLLocationCoordinate2D = CLLocationCoordinate2D(latitude: (regionLatitude as! NSString).doubleValue , longitude: (regionLongitude as! NSString).doubleValue)
        let region: MKCoordinateRegion = MKCoordinateRegion(center: center, span: MKCoordinateSpan(latitudeDelta: 10, longitudeDelta: 10))
        self.mapView.setRegion(region, animated: true)
        // Loop through all items and display them on the map
        var lon:Double!
        var lat:Double!
        var annotationView:MKPinAnnotationView!
        var pointAnnoation:CustomPointAnnotation!
        //2
        for item in data{
            
            let obj = item as! Dictionary< String,AnyObject >
            lon = obj["longitude"]!.doubleValue
            lat = obj["latitude"]!.doubleValue
            
            pointAnnoation = CustomPointAnnotation()
            let incomeLevel:Dictionary< String, AnyObject > = obj["incomeLevel"] as! Dictionary
            let incomeLevelValue = (incomeLevel["value"] as! String)
            if incomeLevelValue == "High income: OECD" || incomeLevelValue == "High income: nonOECD"{
                pointAnnoation.pinCustomImageName = "High income"
            }else{
                pointAnnoation.pinCustomImageName = (incomeLevel["value"] as! String)
            }
            //3
            pointAnnoation.coordinate = CLLocationCoordinate2D(latitude: lat, longitude: lon)
            pointAnnoation.title = obj["name"] as? String
            pointAnnoation.subtitle = obj["capitalCity"] as? String
            annotationView = MKPinAnnotationView(annotation: pointAnnoation, reuseIdentifier: "pin")
            self.mapView.addAnnotation(annotationView.annotation!)
        }
    }

Let’s break down the code above:

//1: The data were fetched and stored in an array, the map will set its center based on the first region element longitude/latitude in the array.

//2: You are looping through the array items, creating a point annotation object for each one and assigning a custom image name with the CustomPointAnnotation class (you will implement this class right away). We have to differentiate between pins, to know which one will get which custom pin view, that’s why subclassing the MKPointAnnotation class was very important to set some sort of image title and assign it on the delegate protocol method ‘viewForAnnotation’ which you will implement later.

//3: Finally, adding each annotation view to the map after setting the coordinate of the point annotation with a title and a subtitle to show to the user after he clicks on the pin.

Before you implement the CustomPointAnnotation class, let’s finish up with this controller by implementing one last method, ‘viewForAnnotation’ is an MKMapViewDelegate protocol method which gets called for each pin to display on the map. It’s kind like cellForRowAtIndexPath for the table view context. We need to implement the viewForAnnotation protocol method because it’s the best place to customise the pin view and assign a custom image to it.

Go ahead and place the following code before the closing bracket of the class:

    func mapView(mapView: MKMapView,
        viewForAnnotation annotation: MKAnnotation) -> MKAnnotationView?{
            
            let reuseIdentifier = "pin"
            
            var v = mapView.dequeueReusableAnnotationViewWithIdentifier(reuseIdentifier)
            if v == nil {
                v = MKAnnotationView(annotation: annotation, reuseIdentifier: reuseIdentifier)
                v!.canShowCallout = true
            }
            else {
                v!.annotation = annotation
            }
            
            let customPointAnnotation = annotation as! CustomPointAnnotation
            v!.image = UIImage(named:customPointAnnotation.pinCustomImageName)
            
            return v
    }

This will dequeue and return a reusable annotation for the given identifier, and if it’s nil, then a new annotation view is created and assigned the image from the custom point annotation object discussed earlier. As you may guess, we are casting the annotation to the CustomPointAnnotation class in order to access the image name of the pin.

Let’s finish up the work and create the CustomPointAnnotation class, select ‘File\New\File’ from the menu. Select ‘Cocoa Touch Class’ from the templates list and name it ‘CustomPointAnnotation’, also make sure it’s a subclass of ‘MKPointAnnotation’

Select it from the Project navigator view and change its content to look like the following:

import UIKit
import MapKit

class CustomPointAnnotation: MKPointAnnotation {
    var pinCustomImageName:String!
}

That’s it, run the app, zoom in and out the map to better see the annotations for some areas, and enjoy your work 🙂

Important: As of iOS 9, App Transport Security is blocking some communications between the app and web services, so you need to disable ATS for our app here to be able to communicate with the World Bank API. To do this, select Info.plist file from the Project navigator, add a new NSAppTransportSecurity Dictionary item to the root dictionary, then add an NSAllowsArbitraryLoads key and set its value to YES, as shown below:

As usual, you can download the final project here. Feel free to leave a comment. I would love to hear your thoughts!