Mastering iOS 12 Programming - Third Edition

To display contacts in your table view, you must set up a few more things. First, you are going to need a table-view cell that displays contact information. All code for a custom table view cell should live in a UITableViewCell subclass. The design for your custom cell can be made in Interface Builder. When you make a design in Interface Builder, you can connect your code and the design using @IBOutlet. @IBOutlet is a connection between an object in the visual layout and a variable in your code.

Designing a table-view cell

Open your app's storyboard in Interface Builder and look for UITableViewCell in the Object Library. When you drag it into the table view that you have already added, your new cell is added as a prototype cell. A prototype cell functions as a blueprint for all cells the table view is going to display. That's right; you only need to set up a single cell to display many. You'll see how this works when you implement the code for your table-view cell. First, let's focus on the layout.

After dragging UITableViewCell to the table view, find and drag out UILabel and UIImageView. Both views should be added to the prototype cell. Arrange the label and image as shown in the following screenshot. After doing this, use the reset to suggested constraints feature you have used before to add Auto Layout constraints to the label and image. When you select both views after adding the constraints, you should see the same blue lines that are present in the following screenshot:

The blue lines from the image are a visual representation of the constraints that were added to lay out your label and image. In the image, you can see a constraint that offsets the label from the left side of the cell. Between the label and the image, you can see a constraint that defines the spacing between these two views. The line that runs through the cell horizontally shows that the label and image are centered on the vertical axis.

 

You can use Document Outline on the left side of Interface Builder to explore these constraints. The table-view cell design is now complete, it's time to implement the UITableViewCell subclass and create some @IBOutlets to connect design and code.

Creating the table-view cell subclass

To create a new UITableViewCell subclass, you need to create a new file (File | New | File) and choose a Cocoa Touch file. Name the file ContactTableViewCell and select UITableViewCell as the superclass for your file, as shown in the following screenshot:

When you open the newly-created file, you'll see that two methods were added to the ContactTableViewCell for you. These methods are awakeFromNib() and setSelected(_:animated:). The awakeFromNib() method is called the very first time an instance of your class is created. This method is the perfect place to do some initial setup that should only be performed once for your cell.

The second method in the template is setSelected(_:animated:), you can use this method to perform some customizations for the cell when a user taps on it. You could, for instance, change the text or background color for a cell there. For now, delete both methods from the class and replace its contents with the following code:

@IBOutlet var nameLabel: UILabel!
@IBOutlet var contactImage: UIImageView!

The preceding code should be the entire body for the ContactTableViewCell class. The variables in the class are annotated with @IBOutlet; this means that those variables can be connected with your prototype cell in Interface Builder. To do this, open Main. storyboard, select your prototype cell and look for the Identity Inspector in the sidebar on the right. Set the class property for your cell to ContactTableViewCell, as shown in the following screenshot. Setting this makes sure that your layout and code are correctly connected:

Next, select the table view cell that you added to the table view. Open the Connections Inspector in the right sidebar. Under the Outlets header, you'll find a list of names. Among those names, you can find the nameLabel and contactImage you added to ContactTableViewCell. Drag from the circle next to the nameLabel towards the label inside of your cell. By doing this, you connect the @IBOutlet that was created in code to its counterpart in the layout. Perform the same steps outlined in the preceding paragraph for the image, as shown in the following screenshot:

The last step is to provide a reuse-identifier for your cell. The table view uses the reuse-identifier so it can reuse instances of table-view cells. Cell-reuse is an optimization feature that will be cover in depth later in this chapter.

To set the reuse-identifier, open the Attributes inspector after selecting your cell. In the Attributes inspector, you'll find, and an input field labeled Identifier. Set this field to the ContactTableViewCell value.

With your layout fully set up, we need to take a couple more steps to make the table view show a list of contacts by assigning it a data source and delegate.

One easily-overlooked fact about the table view is that no matter how simple it might seem to use one in your app, it's one of the more complex components of UIKit. Some of the complexity is exposed when you add a table view to a regular view controller instead of using UITableViewController. For instance, you had to manually set up the layout, so your table view covered the viewport. Then, you had to manually set up a prototype cell to display data in.

The next step toward displaying contacts to your user is providing the table view with information about the contents it should show. To do this, you must implement the data source and delegate for the table view. These properties use advanced concepts that you may have seen before, you probably just weren't aware of them yet. Let's make sure you know exactly what is going on.

Protocols and delegation

Throughout the iOS SDK and the Foundation framework, a design pattern named delegation is used. Delegation allows an object to have another object perform work on its behalf. When implemented correctly, it's a great way to separate concerns and decouple code within your app. The following figure illustrates how UITableView uses delegation for its data source using UITableViewDataSource:

The table view uses the help of two objects to function correctly. One is delegate, and the other is dataSource. Any time you use a table view, you must configure these two objects yourself. When the time comes for the table view to render its contents, it asks dataSource for information about the data to display. delegate comes into play when a user interacts with the items in the table view.

If you look at the documentation for UITableView, you can find the delegate property. The type for delegate is UITableViewDelegate?. This tells you two things about delegate. First of all, UITableViewDelegate is a protocol. This means that any object can act as a delegate for a table view, as long as it implements the UITableViewDelegate protocol. Second, the question mark behind the type name tells you that the delegate is an Optional property. An Optional property either has a value of the specified type, or it is nil. The table view's delegate is Optional because you do not haveto set it to create a functioning table view.

A protocol, such as UITableViewDelegate, defines a set of properties and methods that must be implemented by any type that wants to conform to the protocol. Not all methods must be explicitly implemented by conforming objects. Sometimes, a protocol extension provides a reasonable default implementation. You can read more about this in Chapter 6, Writing Flexible Code With Protocols And Generics.

In addition to delegate, UITableView has a dataSource property. The data source's type is UITableViewDataSource?, and just like UITableViewDelegate, UITableViewDataSource is a protocol. However, UITableViewDelegate only has optional methods, meaning you don't need to implement any methods to conform to UITableViewDelegate. UITableViewDataSource does have required methods. The methods that need to be implemented are used to provide the table view with just enough information to be able to display the correct amount of cells with the right content in them.

If this is the first time you're learning about protocols and delegation, you might feel a little bit lost right now. That's OK; you'll get the hang of it soon. Throughout this book, your understanding of topics such as these will improve bit by bit. You will even learn about a concept called protocol-oriented programming! For now, it's important that you understand that a table view asks a different object for the data it needs to show and that it also uses a different object to handle certain user interactions.

We can break the flow of displaying contents in a table view down into a couple of steps:

1. The table view needs to reload the data
2. The table view checks whether a dataSource is set, and asks it for the number of sections it should render
3. Once the number of sections is passed back to the table view, the dataSource is asked for the number of items for each section
4. With knowledge about the number of sections and items that need to be shown, the table view asks its dataSource for the cells it should display
5. After receiving all of the configured cells, the table view can finally render these cells to the screen

These steps should give you a little bit more insight into how a table view uses another object to figure out the contents it should render. This pattern is compelling because it makes the table view an extremely flexible component. Let's put some of this newfound knowledge to use!

@IBOutlet var tableView: UITableView!

extension ViewController: UITableViewDataSource {
  // extension implementation
}
extension ViewController: UITableViewDelegate {
  // extension implementation
}

class ViewController: UIViewController {

  var contacts = [CNContact]()

  // viewDidLoad
  // retrieveContacts
}

extension ViewController: UITableViewDataSource {
  // 1
  func tableView(_ tableView: UITableView, numberOfRowsInSection section: Int) -> Int {
    return contacts.count
  }

  // 2
  func tableView(_ tableView: UITableView, cellForRowAt indexPath: IndexPath) -> UITableViewCell {
    // 3
    let cell = tableView.dequeueReusableCell(withIdentifier: "ContactTableViewCell") as! ContactTableViewCell
    let contact = contacts[indexPath.row]

    cell.nameLabel.text = "\(contact.givenName) \(contact.familyName)"

    // 4
    if contact.imageDataAvailable == true, let imageData = contact.imageData {
      cell.contactImage.image = UIImage(data: imageData)
    }

    return cell
  }
}

let contacts = try! store.unifiedContacts(matching: predicate, keysToFetch: keysToFetch)
print(contacts)

contacts = try! store.unifiedContacts(matching: predicate, keysToFetch: keysToFetch)
DispatchQueue.main.async { [weak self] in
  self?.tableView.reloadData()
}

tableView.delegate = self
tableView.dataSource = self

In addition to UITableViewDelegate and UITableViewDataSource, a third protocol exists that you can implement to improve your table view's performance. It's called UITableViewDataSourcePrefetching and you can use it to enhance your data source. If your data source performs some complex task, such as retrieving and decoding an image, it could slow down the performance of your table view if this task is performed at the moment the table view wants to retrieve a cell. Performing this operation a little bit sooner than that can positively impact your app in those cases.

Since Hello-Contacts currently decodes contact images for its cells, it makes sense to implement prefetching to make sure the scrolling performance remains smooth at all times. The current implementation performs the decoding in tableView(_:cellForRowAt:). To move this logic to UITableViewDataSourcePrefetching, there is one method that needs to be implemented, it's called tableView(_:prefetchRowsAt:). Add the following extension to ViewController.swift to create a nice starting point for implementing prefetching:

extension ViewController: UITableViewDataSourcePrefetching {
  func tableView(_ tableView: UITableView, prefetchRowsAt indexPaths: [IndexPath]) {
    for indexPath in indexPaths {
      // Prefetching will be implemented here soon
    }
  }
}

Instead of receiving just a single IndexPath, tableView(_:prefetchRowsAt:) receives a list of index path for which you should perform a prefetch. Before implementing the prefetching, take a step back to come up with a good strategy to implement prefetching. For instance, it would be ideal if each image only has to be decoded once to prevent duplicate work from being done. Also, a mechanism is needed to decode images in cases where the image wasn't prefetched. And also in that case, only having to decode once would be great. This can be achieved by creating a class that wraps CNContact and has some helper methods to make prefetching and decoding nice and smooth.

First, create a new file (File | New | File...) and select the Swift file template. Name this file Contact.swift. Add the following code to this file:

import UIKit
import Contacts

class Contact {
  private let contact: CNContact
  var image: UIImage?

  // 1
  var givenName: String {
    return contact.givenName
  }

  var familyName: String {
    return contact.familyName
  }

  init(contact: CNContact) {
    self.contact = contact
  }

  //2
  func fetchImageIfNeeded(completion: @escaping ((UIImage?) -> Void) = {_ in }) {
    guard contact.imageDataAvailable == true, let imageData = contact.imageData else {
      completion?(nil)
      return
    }

    if let image = self.image {
      completion?(image)
      return
    }

    DispatchQueue.global(qos: .userInitiated).async { [weak self] in
      self?.image = UIImage(data: imageData)
      DispatchQueue.main.async {
        completion?(self?.image)
      }
    }
  }
}

The first thing to note about this code is the use of so-called computed variables. These variables act as a proxy for properties from the private CNContact instance that Contact wraps. It's good practice to set up proxies such as these because they prevent exposing too many details to other objects. Imagine having to switch from CNContact to a different type of contact internally. That becomes a lot easier when as few places as possible know about CNContact.

The second segment of code you should pay extra attention to is the image-fetching part that ensures we fetch images as efficiently as possible. First, the code checks whether an image is present on the contact at all. If it is, a check is done to see whether a decoded image already exists. And if it does, the completion closure is called with the decoded image. If no image exists yet, it is decoded on the global dispatch queue. By executing code on the global dispatch queue, it is automatically executed off the main thread. This means that no matter how slow or lengthy the image decoding gets, the table view will never freeze up because of it, since the main thread is not doing the heavy lifting. Because this code is asynchronous, a completion closure is used to call back with the decoded images. Calling back is done on the main thread since that is where the image should be used eventually. Note that the completion closure has a default value in the signature for fetchImageIfNeeded(completion:). Sometimes, the result of prefetching isn't needed so no completion handler will be given. Again, if this dispatch stuff makes you dizzy, don't worry. Or skip ahead to Chapter 25, Offloading Tasks with Operations and GCD, if you can't wait to learn more.

There are only a couple more changes that must be made to ViewController to make it uses the new Contact class and you're good to go. The following code snippet shows all the updates you will need to incorporate:

class ViewController: UIViewController {
  var contacts = [Contact]()

  //...

  func retrieveContacts(from store: CNContactStore) {
    //...

    // 1
    contacts = try! store.unifiedContacts(matching: predicate, keysToFetch: keysToFetch)
      .map { Contact(contact: $0) }

    // ...
  }
}

extension ViewController: UITableViewDataSource {
  func tableView(_ tableView: UITableView, numberOfRowsInSection section: Int) -> Int {
    return contacts.count
  }

  func tableView(_ tableView: UITableView, cellForRowAt indexPath: IndexPath) -> UITableViewCell {
    let cell = tableView.dequeueReusableCell(withIdentifier: "ContactTableViewCell") as! ContactTableViewCell
    let contact = contacts[indexPath.row]

    cell.nameLabel.text = "\(contact.givenName) \(contact.familyName)"

    // 2
    contact.fetchImageIfNeeded { image in
      cell.contactImage.image = image
    }

    return cell
  }
}

extension ViewController: UITableViewDelegate {
  // extension implementation
}

extension ViewController: UITableViewDataSourcePrefetching {
  func tableView(_ tableView: UITableView, prefetchRowsAt indexPaths: [IndexPath]) {
    for indexPath in indexPaths {
      // 3
      let contact = contacts[indexPath.row]
      contact.fetchImageIfNeeded()
    }
  }
}

The first addition is to make use of map to transform the list of CNContact instances to Contact instances. The second update uses the fetchImageIfNeeded(completion:) method to obtain an image. This method can be used because it has been set up to return either the existing decoded image or a freshly-decoded one if the prefetching wasn't able to decode the image in time.

The last change is to prefetch images as needed. Because fetchImageIfNeeded(completion:) has a default implementation for its completion argument, it can be called without a completion closure. The result isn't immediately relevant, so not having to provide a closure is convenient in this case. The prefetching is fully implemented now; you might not immediately notice any improvements when you run the app, but rest assured that proper use of prefetching can greatly benefit your apps.

Cell-selection refers to a user tapping on a cell. In order to respond to cell-selection, the UITableViewDelegate method called tableView(_:didSelectRowAt:) should be implemented. In Hello-Contacts, ViewController already has an extension implemented to make it conform to UITableViewDelegate so all you need to do is implement tableView(_:didSelectRowAt:) in the extension.

Since a table view will call methods on its delegate whenever they are implemented, you don't need to tell the table view that you want to respond to cell-selection. This automatically works if the table view has a delegate, and if the delegate implements tableView(_:cellForRowAt:). The implementation you'll add to Hello-Contacts, for now, is a very simple one. When the user taps a cell, the app displays an alert. In Chapter 3, Creating a Detail Page, you will learn how to perform more meaningful actions such as displaying a detail page. Add the following code to the UITableViewDelegate extension in ViewController.swift:

func tableView(_ tableView: UITableView, didSelectRowAt indexPath: IndexPath) {
  let contact = contacts[indexPath.row]
  let alertController = UIAlertController(title: "Contact tapped",
                                          message: "You tapped \(contact.givenName)",
                                          preferredStyle: .alert)

  let dismissAction = UIAlertAction(title: "Ok", style: .default, handler: { action in
    tableView.deselectRow(at: indexPath, animated: true)
  })

  alertController.addAction(dismissAction)
  present(alertController, animated: true, completion: nil)
}

The tableView(_:cellForRowAt:) method receives two arguments, the first is the table view that called this delegate method. The second argument is the index path at which the selection occurred. The implementation you wrote for this method uses the index path to retrieve the contact that corresponds with the tapped cell so the contact name can be shown in an alert. You could also retrieve the contact's name from the tapped cell. However, this is not considered good practice because your cells and the underlying data should be as loosely-coupled as possible. When the user taps the Ok button in the alert, the table view is told to deselect the selected row. If you don't deselect the selected row, the last tapped cell will always remain highlighted. Note that the alert is displayed by calling present(_:animated:completion:) on the view controller. Any time you want to make a view controller display another view controller, such as an alert controller, you use this method.

Even though this setup is not extremely complex, there is some interesting stuff going on. The delegation pattern is a very powerful one when implemented correctly. Especially in the case of a table view, you can add a lot of functionality simply by implementing the delegate methods that correspond to the desired behavior. Because the table view's delegate could be any object that conforms to UITableViewDelegate, you could split up ViewController and UITableViewDelegate entirely. Doing so would enable you to reuse your delegate implementation across multiple table views. For now, I'll leave it as an exercise for you to do this. Attempting such a refactor will certainly help you to increase your understanding of delegation and its powers.

Now that you know how to respond to cell-selection, let's have a look at a slightly more advanced topic – cell-deletion. Deleting data from a table view is a feature that many apps implement. If you have ever used the mail app on iOS, you might have noticed that several actions appear when a user swipes either right or left on a table-view cell. These swipe actions are a great feature to implement for Hello-Contacts so users can swipe over contacts and easily delete them. Of course, we won't be actually deleting contacts from a user's address book, but it would be possible to implement this if you truly wanted to.

In this example, you'll learn how to delete contacts from the array of contacts that is used to populate the table view. To implement support for cell-deletion, you need to implement another method from UITableViewDelegate. The method you need to implement is tableView(_:trailingSwipeActionsConfigurationForRowAt:). This delegate method is called when a user swipes over a table view cell and returns the actions should be shown when the cell moves sidewards. A good example of this is found in the mail app on iOS.

Add the following implementation of tableView(_:trailingSwipeActionsConfigurationForRowAt:) to the UITableViewDelegate extension for ViewController:

func tableView(_ tableView: UITableView,
               trailingSwipeActionsConfigurationForRowAt indexPath: IndexPath) -> UISwipeActionsConfiguration? {

  // 1
  let deleteHandler: UIContextualActionHandler = { [weak self] action, view, callback in
    self?.contacts.remove(at: indexPath.row)`
    callback(true)
  }

  // 2
  let deleteAction = UIContextualAction(style: .destructive,
                                        title: "Delete", handler: deleteHandler)

  // 3
  return UISwipeActionsConfiguration(actions: [deleteAction])
}

If you run the app now and swipe from right to left over a table view cell, a delete button will appear from underneath the cell. In the code snippet, the first step is to set up a delete-handler that takes care of the actual deletion of the contact. This handler is a closure that is passed to the UIContextualAction instance that is created in step two. You have seen closures passed directly to method calls already, for instance as completion-handlers. However, you can also store a closure in a variable. This allows you to reuse your closure in several places and can make your code more readable. The third and last step is to create an instance on UISwipeActionsConfiguration and pass it the actions that you want to display. Since you can pass an array of actions, it is possible to show multiple actions when the user swipes over a cell. In this case, only a single action is added – the delete action.

Currently, tapping the delete button doesn't do much. While the contact is removed from the underlying data source, the table view itself doesn't update. Table views don't automatically stay in sync with their data sources. Add the following deleteHandler implementation to make sure the table view updates when the user taps the delete button:

let deleteHandler: UIContextualActionHandler = { [weak self] action, view, callback in
  self?.contacts.remove(at: indexPath.row)
  self?.tableView.beginUpdates()
  self?.tableView.deleteRows(at: [indexPath], with: .fade)
  self?.tableView.endUpdates()
  callback(true)
}

This new version of deleteHandler ensures that the table view updates itself by removing the row that the user has decided to remove. Note that the contacts array is updated before updating the table view. When you update the table view like this, it will verify that it is in sync with the data source, which is the contacts array in this case. If the data source does not contain the expected amount of sections or rows, your app will crash. So whenever you update a table view, make sure to update the data source first. Also, note the calls to beginUpdates and endUpdates. These methods make sure that the table view doesn't reload in the middle of being manipulated. This is especially useful if you're performing a lot of complex updates, such as moving cells, inserting new ones, and removing old ones all at the same time.

With cell-deletion out of the way, let's have a look at reordering cells.

In some applications, it makes sense for users to be able to reorder cells that are shown in a table view, such as in a to-do list application or a grocery list. Implementing cell-reordering takes a couple of steps. First, a table view needs to be put in editing mode. When a table view is in editing mode, the user can begin sorting cells visually. Typically, a button in the top right or left corner of the screen is used to enter and exit the editing mode. The easiest way to make space for a button is by wrapping your ViewController in a UINavigationController. Doing this makes a navigation bar appear at the top of the screen that has space for a title, back button, and also for custom buttons such as the Edit/Done button we need to make the table view enter and exit the editing mode.

Placing the table view in editing mode is actually really simple if you know how. Every UIViewController instance has a setEditing(_:animated:) method. If you override this method, you can use it as an entry point to call setEditing(_:animated:) on the table view so it enters edit mode. Once this is implemented, you need to implement tableView(_:moveRowAt:to:) from UITableViewDelegate to commit the reordered cells to your data source by updating the contacts array.

First, open Main.storyboard so you can wrap the view controller in a navigation controller. When you have selected the view controller in your storyboard, click Editor | Embed In | Navigation Controller in the menu bar at the top of the screen. This will automatically embed the view controller in a navigation controller and configure everything as needed. To add the Edit/Done button, open ViewController.swift and add the following code to viewDidLoad:

navigationItem.rightBarButtonItem = editButtonItem

This line adds a UIBarButtonItem that automatically toggles itself and calls setEditing(_:animated:) on the view controller. Since it's set as rightBarButtonItem, it will appear on the right side of the navigation bar. If you go ahead and build the app now, you'll see that you have a button that toggles between a label that says Edit and Done. To put the table view in edit mode, you must override the setEditing(_:animated:) method in ViewController.swift, as follows:

override func setEditing(_ editing: Bool, animated: Bool) {
  super.setEditing(editing, animated: animated)

  tableView.setEditing(editing, animated: animated)
}

What this method does should be self-explanatory. Go ahead and run the app now. If you tap the Edit button, every cell suddenly displays a red circle – while this is interesting, it's not quite what's needed. Cells don't show reorder controls when in edit mode by default. Open Main.storyboard again and select your prototype cell. In the Attributes inspector, you'll find a checkbox named Shows Re-order controls. You want to make sure this checkbox is checked so you can reorder cells.

The final step to implementing this feature is adding tableView(_:moveRowAt:to:) in the UITableViewDelegate extension in ViewController.swift. This method will make sure that the contacts array is updated in the same way the cells are, ensuring that the table view and data source remain nicely in sync. Add the following code to the UITableViewDelegate extension in ViewController.swift:

func tableView(_ tableView: UITableView, moveRowAt sourceIndexPath: IndexPath, to destinationIndexPath: IndexPath) {
  let contact = contacts.remove(at: sourceIndexPath.row)
  contacts.insert(contact, at: destinationIndexPath.row)
}

Even though it's only two lines, this code updates the data source by moving a contact from its old position in the array to its new position. You now have everything in place to correctly reorder cells in a table view. Go ahead and try it out!