Learning iOS Development: A Hands-on Guide to the Fundamentals of iOS Programming (2014)

Chapter 8. Table Views I: The Basics

In previous chapters, the main screen showed only one car at a time. In iOS, it is more common to show several data items and scroll through them. You can see examples on the main screens of Contacts, Music, Settings, and many other apps that show tables of data items.

Table views are a key part of your toolbox for designing and creating apps for iPhone/iPod touch, where space is at a premium. When combined with a UINavigationController, table views make navigating through hierarchical data easy. A table gives your user quick access to a summary list of objects. Tapping moves the user quickly up and down the hierarchy to the required level of detail.

After you learn the basics of table view controllers, you create a small project to solidify and then refine what you have learned. Then you take the experience of building a table view and transform the add/view screen to gain valuable experience in converting existing projects to use new ways of presenting and navigating information.

Next, you implement a common way of adding objects to tables and enable the user to make new cars. Then you learn about editing tables and use that as another way to delete cars.

Then, you go deeper by changing how car details are viewed and adding a new scene showing car details using grouped cells, much as the Settings app does. Then you use a special way of presenting controllers to show one modally, forcing a user to do or cancel an action. You use modal presentation to build a couple of car attribute editors.

By the time you are finished with this chapter, you will have a good understanding of the basics of table views. You can use them in your own projects for showing lists of data. Combined with navigation controllers, your apps can move through hierarchies of detail. Editing parts of the data shown in the table can be done outside the hierarchy by using modals, enabling the user to make or cancel changes.

Introduction to Table Views

Table views are a workhorse for iOS. Even if an app does not use them for the main scenes, you are still likely to use them for preferences or an About screen. They provide all the infrastructure to show small or large numbers of individual data items that optionally use a hierarchy to view and/or edit detailed information. Yet using them for the simplest case requires only a few key classes and methods.

Figure 8-1 shows the basic parts of a table view. The table contains a number of individual table view cells, for items 2 through 12. It also has support for scrolling through and selecting cells. Other possible functionality includes adding headers and footers, sections, section headers and footers, and an index. You explore most of these in this book.

Figure 8-1 Table view parts

The cells in Figure 8-1 are very simple, showing just text. You can use one of the types of cells the system provides, or you can create fully customized cells.

The code for Figure 8-1 requires three classes and two protocols:

UITableViewController is the main view controller and has very few view properties and only one method. Most of the work is done by two protocols adopted by the controller. You implement methods from those protocols for displaying table cells and, in some cases, reacting to user interaction.

UITableViewDataSource provides details about the data from the object to display in each cell to the number of sections and rows in the table. There are a number of optional methods that enable adding, deleting, and reordering cells.

UITableViewViewDelegate supports the behaviors of a table view. You can do everything from configuring the height of an individual row or header to supporting editing and highlighting.

UITableView implements all the functionality to configure and display the various parts of the table view. It has additional methods and properties for adding, moving, and deleting cells; updating data; manually scrolling content; accessing parts of the view; and configuring the index. As you will see, some of these things are best done in the data source (UITableViewDataSource) or delegate (UITableViewViewDelegate).

UITableViewCell represents an individual item displayed in the table view. There are four system styles with various mixes of a title and subtitle, including the ability to add an image. In addition, you can create your own fully customized cells.

The general behaviors of a table view fall into four categories:

Setup—Specify table view values for headers, footers, sections, section headers and/or footers, and number of cells in any visible sections.

Display—Display the visible cells.

Scrolling—Calculate what cells will become visible and load them. The table view manages creating versus reusing cell objects by keeping a pool of created cells and balancing which ones are reused as new data scrolls into view.

Selection—Update the selection state of any cell or cells based on the table view’s configuration. Call any delegate methods based on selection state.

Behaviors can occur at any time. For example, display occurs after setup and scrolling. Setup occurs any time the data is updated or the table is told to reload.

Project TableTry

The best way to understand table behaviors and the interaction between the five key classes is to create code. Follow these steps to create your own project and let the exploration begin:

1. In Xcode, create a new Empty Application called TableTry. Until now, you have used the Single View application template; this time you will choose Empty Application and only target iPhone. The created project has only one class defined for the app delegate. It has no user interface.

2. In AppDelegate.m, remove all but the last line of the application:didFinishLaunchingWithOptions: method. If you do not remove the code, every time you launch the app, you will see a white screen, no matter what changes you make in the storyboard you create in the next step. The revised method should look like this:

- (BOOL)application:(UIApplication *)application
didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
return YES;
}

3. Add an iPhone storyboard file by selecting File > New and then choosing the User Interface category. Save the file into the TableTry folder inside the main project folder.

4. Select the new storyboard file and drag a table view controller onto the storyboard. When you are done, it should look like Figure 8-2. Three entities have been added to your storyboard. First is the table view controller. Second is a table view, with the table view controller set as the data source (the object implementing the UITableViewDataSource protocol) and delegate (the object implementing the UITableViewViewDelegate protocol). Third is a table view cell to use as a prototype for the type of cell shown in the table.

Figure 8-2 Table view controller

5. Open the Project editor and set the Main Interface for the TableTry target to the storyboard you just created.

Try running the app in the simulator, and you get a white screen with lines. The app is not broken; the table view is doing exactly what you tell it to do—in this case, showing placeholders for cells but not creating any.

The simplest thing you can do now is create some predefined cells:

1. Open the main storyboard and select the Attributes inspector for the table view.

2. In the Table View section at the top of the Attributes inspector, set the Content popup to Static Cells, and you see the table view on the storyboard change from the first image in Figure 8-3 to the second. Before you change from dynamic to static cells, the left-hand image in Figure 8-3has a Prototype Cells header with just one prototype cell. After you change to static, the right-hand image has three static cells, all of which look the same.

Figure 8-3 Creating static cells

Run the app again. Although it looks the same as before, each of the top three cells can be selected. Notice that the first cell is underneath the status bar. As you tap each of the top three cells, the one you tap is highlighted in gray. Tap the fourth cell, and nothing happens.

Creating Cells

Sometimes you want predefined cells. But more often, you want to show a list of data items that vary in number. The table view you just created used static cells. The number of cells and their basic look is fixed because you know the content in advance. They act like static views in the table. Sometimes you do not know how many cells you will show or how they will be organized. In such instances, instead of using static cells, you can use dynamic prototypes. Which one you choose depends on what you are trying to do:

Static cells are useful when the table layout is fixed, such as most of the Settings app. You set up the number of cells, their content, and even the organization of the table at design time. You can change what information is shown at runtime by changing the contents of elements in the cell, but the basic organization of the table is fixed.

Dynamic prototypes are handy when you do not know the number of data items you will show at runtime. A prototype is a template for what you want to show. At runtime, you can create as many cells as you need, using the prototypes. Each one has the same basic look but shows different data, such as an individual car. You can also have more than one prototype.

Continue exploring table views by converting your project to use dynamic prototypes. To do so, follow these steps:

1. Change the table view back to using dynamic prototypes.

2. Delete the extra two prototypes. Basically, change things back to the left-hand image in Figure 8-3.

3. Run the app, and you might see a warning that the prototype cell does not have a reuse identifier. This is something the table view controller uses to determine what kind of prototype cell to allocate or reuse.

Open the storyboard and make sure the Attributes inspector is selected for the prototype cell. Set the reuse identifier to MyCell, as shown in Figure 8-4.

Figure 8-4 Cell reuse identifier

Now you need some code to tell the table view how many cells to create, and you need to populate those cells with data. You therefore need a UITableViewDataSource. In this case, you create your own subclass of UITableViewController, which implements the data source and delegate protocols for you. Follow these steps:

1. Choose File > New > File, select the Cocoa Touch category for iOS, and select the Objective-C class.

2. On the next screen, create a subclass of UITableViewController called MyTableViewController and save it in the project, making sure it is part of the TableTry target. (Note that this is the default behavior.)

3. Go back to the storyboard, select the table view controller, and use the Identity inspector to set the class to MyTableViewController.

You see a warning triangle in the navigation bar above the IB canvas. This tells you something is wrong, though the project should still build and run. You can look at all the warnings by clicking on the yellow arrow. In this case, the dropdown shows the warning is inMyTableViewController.m.

One way to find the errors is to open that file and look for the warning flag next to the line. Another is to click an item in the list of issues as you did in Chapter 4, “Auto Layout” (see Figure 4-23). A faster way is to click the black navigation triangles on each side of the yellow warning indicator. This opens the relevant file and takes you straight to the line with the problem. In the case of IB, it selects the UX element with the issue.

Both warnings were created when you created the class. The special #warning marker at the beginning of a line tells Xcode something needs work. Both warnings talk about incomplete implementations and serve as reminders that you have more code to write.

Sections and Rows

Each of the warnings tells you something about how the table view expects data to be organized. It is expecting zero or more sections of data organized into zero or more rows. It sounds strange to start at zero, but it is possible to have either an entirely empty set of data or just an empty section.

A good example is the Contacts app. It can have as many sections as the user has unique first letters for the last names of contacts. Each section has as many contacts as there are people whose last name begins with that letter. (For example, all friends with a last name starting with A.) But what happens if you have no contacts?

As it happens, the simulator version of the Contacts app can show you. Launch the app, tap Groups, and make sure only the Work group is selected. There is a table with the words No Contacts. As soon as you add one contact, such as John Adams, you see the contact, and No Contacts is gone. In this case, you have a table view with one section—contacts with a last name starting with the letter A—and that section has one row, for John Adams.

Your next job is to tell the table view how many sections of data there are and how many rows are in each section. In this case, you have one section with five data items. Follow these steps:

1. In MyTableViewController.m, replace the two methods shown next. The first method tells the table view how many sections of data, and the second tells how many data items for a given section. (Note the first method, numberOfSectionsInTableView: is optional and defaults to 1 if not provided.)

- (NSInteger)numberOfSectionsInTableView:(UITableView *)tableView {
return 1;
}

- (NSInteger)tableView:(UITableView *)tableView
numberOfRowsInSection:(NSInteger)section {
return 5;
}

2. In the method tableView:cellForRowAtIndexPath: below the two methods you just replaced, change the CellIdentifier from @"Cell" to @"MyCell". This tells the table view what prototype to use for creating the new cell.

Run the app again. This time you have five cells you can click, though again, they are not very interesting.

Now it is time to add some data to each cell. In this case, you add a string with the section and row number of the cell.

Generating Cells and Index Paths

Before writing the code in this section, you need to understand what is meant by an index path in a table view. As you have seen, a table view shows data as one or more groups of rows. Each group of rows is called a section. Any cell in the table can be identified by a combination of its section and row. That combination is an index path.

Table views use a specialized version of the more general NSIndexPath object to represent the index path. It is composed of two integers: The first is the section, and the second is the row. Since it is an object, you can send messages or use dot notation to access parts. Table view uses a couple of special assessors, section and row, to make coding easier and more maintainable.

If you have an NSIndexPath called cellIndexPath in a table, you can find the section by using cellIndexPath.section and the row with cellIndexPath.row.

To generate a string in the form Section: <the cell's section> Row: <the cell's row>, you use the following:

NSString *myLabel = [NSString stringWithFormat:@"Section: %d Row: %d",
indexPath.section, indexPath.row];

In fact, this is exactly how you generate unique labels for each of the five cells. Add the following lines in bold to tableView:cellForRowAtIndexPath:

- (UITableViewCell *)tableView:(UITableView *)tableView
cellForRowAtIndexPath:(NSIndexPath *)indexPath {
...

NSString *myLabel = [NSString stringWithFormat:@"Section: %d Row: %d",
indexPath.section, indexPath.row];
cell.textLabel.text = myLabel;

return cell;
}

Run the app and you see five cells, each with a section of 0 and a row of 0 through 4. Note that all index paths are 0-based, not 1-based. This works well with array-based data storage, though it can often be the source of “but I thought I coded it right” bugs.

Adding a Section

The next step is to add a section to the table. Doing so is as simple as changing the number returned from numberOfSectionsInTableView: from 1 to 2. Run the app, and there are two sections of five items each. But there are no section headings.

To add a section heading, you need to add an optional data source protocol method. Insert the following code below the numberOfSectionsInTableView: method:

- (NSString *)tableView:(UITableView *)tableView
titleForHeaderInSection:(NSInteger)section {
return [NSString stringWithFormat:@"Section: %d", section];
}

When you run the app, you see that the code simply uses the section number to create a header. Notice that all you need to do to have the headers appear is add this method and return a non-nil value. That last part is key: You can prevent a header from displaying simply by returning nilfrom this method.

There is a slight issue with the section header being underneath the status bar. That is dealt with later in this chapter.

Experiment with adding more sections and/or more cells per section. Even if the numbers are quite large, the table view still works. Part of the reason is that the table view only keeps around the cells being viewed as well as some others for fast scrolling. If you created a table with thousands of data points, only a few tens would be in memory at a time—if that. A table view creates the cells it needs and recycles the ones no longer onscreen. That is what the reuse identifier you set above is used for.

Phase I: Replacing the Add/View Scene

To learn more about table views, you need cells with data. In this section, you create a car cell along with the code to populate it. You also add a way to create and remove cars. Along the way, you replace the add/view scene with a table view.

First you replace the add/view scene with a table view controller-based scene by following these steps:

1. Open the CarValet project. You can use an existing one or use the one provided in the CH08 CarValet Starter project.

2. Open the Storyboard editor, drag in a table view controller, and move the new view controller just above the existing edit/view scene.

3. Add two new Objective-C classes to your project just below Car.m: Base CarTableViewController on UITableViewController and CarTableViewCell on UITableViewCell. Make sure the classes are added to the CarValet target.

4. In the Storyboard editor, set the class of the table view controller to CarTableViewController, and set the class of the prototype table view cell to CarTableViewCell. While the prototype cell is selected, choose attributes and set the reuse identifier to CarCell.

5. Add a property for a Car object to a car cell. This is used for displaying data in the cell and, eventually, determining what car to view and edit. Open CarTableViewCell.h and add the code shown in bold:

#import <UIKit/UIKit.h>

@class Car;

@interface CarTableViewCell : UITableViewCell

@property (strong, nonatomic) Car *myCar;

6. Import Car.h into CarTableViewCell.m.

7. Open CarTableViewController.m and add the code shown in bold. In addition to importing the car model and car table view cell, you are declaring a data array for the cars, just as you did in ViewController.m:

#import "CarTableViewController.h"

#import "Car.h"
#import "CarTableViewCell.h"

@implementation CarTableViewController {
NSMutableArray *arrayOfCars;
}

8. Copy the newCar: method from ViewController.m to the bottom of CarTableViewController.m, just above the @end statement. Then remove the call to updateLabel:withBaseString:andCount: from the pasted method.

9. In CarTableViewController.m, replace viewDidLoad with the following code from near the end of ViewController.m to allocate the car data array and add an initial car:

- (void)viewDidLoad {
[super viewDidLoad];

arrayOfCars = [NSMutableArray new];

[self newCar:nil];
}

10. Change the number of sections to 1 and the number of rows to be the size of arrayOfCars:

- (NSInteger)numberOfSectionsInTableView:(UITableView *)tableView {
return 1;
}

- (NSInteger)tableView:(UITableView *)tableView numberOfRowsInSection:(NSInteger)section {
return [arrayOfCars count];
}

11. In tableView:cellForRowAtIndexPath:, make sure the static CellIdentifier is set correctly. The line of code should look like this:

static NSString *CellIdentifier = @"CarCell";

12. Switch to the storyboard and change where the navigation controller points by Ctrl-dragging from the body of the navigation controller in the Visual editor to the new car table view controller, as shown in the left part of Figure 8-5. In the popup that appears, choose the root view controller Relationship Segue. The navigation controller root view segue now connects to the car table view controller, as shown in the right half of Figure 8-5.

Figure 8-5 Setting a new root view controller

Run the app. The table view controller is now the add/view scene, and there is one car cell, though the only way you can tell is by selecting it. Before going on, change the title in the navigation bar to CarValet. You can do this directly or by copying the localization code fromViewController.m.

Adding a Car View Cell

You have the data for one car and a cell to represent it, but you don’t have any view elements to display the data. The next step is to modify the prototype cell to show car data. Follow these steps:

1. Add the property dateCreated of type NSDate to the Car object. Set it to [NSDate date] in the base class initializer.

2. In the storyboard, open the Attributes inspector for the car table view cell and set it to the style Right Detail. The cell changes to show Title in black on the left and Detail in light gray on the right. Change the font size of Detail to 12 points.

You change the font size by double-clicking the detail label, showing the Attributes inspector, and then using the Font area to change the size.

3. Add a publicly facing method called configureCell to CarTableViewCell, using the code in Listing 8-1. To make it public, you need to declare the method in the .h file.

4. Add code to tableView:cellForRowAtIndexPath: in CarTableViewController.m to set the car data for the cell. Then tell the cell to update itself. The changes are shown below in bold. Note that you have to change the class of cell you are creating so it knows about the myCar property and configureCell method:

- (UITableViewCell *)tableView:(UITableView *)tableView
cellForRowAtIndexPath:(NSIndexPath *)indexPath {
static NSString *CellIdentifier = @"CarCell";
CarTableViewCell *cell = [tableView
dequeueReusableCellWithIdentifier:CellIdentifier
forIndexPath:indexPath];

cell.myCar = arrayOfCars[indexPath.row];
[cell configureCell];

return cell;
}

Listing 8-1 configureCell in CarTableViewCell.m