Open Source Code: BTIConcepts

I've published some code on GitHub that I'm calling BTIConcepts. There is nothing earth-shattering here; I'm certainly not breaking any new ground in computer science. This is just a variety of small things that are individually useful, and become even more so when combined. If you have ever thought "Boy, I sure wish all of my [instances of class] would do [something]", then you might want to peek through the code. Even if you don't use any of these specific classes, surely there is a weak spot somewhere in your repertoire where you can apply the concepts.

 

But first let's talk about coding style.

 

I have written previously about how I use logging. I've even written a little service to make adding these logs easier. This is caveman logging at its finest, and I am not even a little bit ashamed of it. The number of problems I have solved over the years simply by doing this more than outweighs any loss of "l33t" status I may have as a professional developer. I've added to this recently with BTITrackingLog. I'm not the first to make an NSLog macro, and probably won't be the last. But until I did this, I was only using NSLogs. So it was either ALL messages, or no messages. Now I can conditionally enable the tracking logs, but still see "important" NSLogs. I will add a configuration and scheme called Debug + Tracking that allows me to see everything. I've thoughtfully commented them out from the repository in anticipation of people viewing them as annoying, but what can I say, I like them. I sadly have not yet updated my service to use BTITrackingLogs.

 

For categories, method names should be decorated somehow to avoid clashes with primary methods. Most people use a prefix, so btiDoSomething, for example. I saw a recommendation a while back (sorry person, I'd credit you if I remembered who you are) to use postfixes instead. doSomethingBTI. They key argument offered was that with a prefix, you have to know that you mean to use a category method when you start typing in order to get code completion. So it's not merely "This is an array method", it is also "This is an array method that I or someone else have manually created". With a postfix, just start typing like you normally would, and code completion will take care of the rest. For methods that accept multiple parameters, I place the decoration at the end of the first group of text, like so: doSomethingBTI:andSomethingElse:andThisToo: Another benefit (or curse, depending on point of view) of using a postfix is that if the category method is similar to a primary method, then you can easily change your mind while typing by hitting either method in the pop-up. Can't do that with a prefix.

 

The ways that I have organized my view controllers have become less and less important as Objective-C gains new features. I saw a recommendation a long time ago to put dealloc at the top of the file, so that it is right there next to the properties. This way when you add a property, you're less likely to forget to travel all the way to the bottom to clear out the property in dealloc. And since viewDidUnload was often very similar to dealloc, I wanted it placed right after dealloc for the same reasons. Well, with ARC you don't need dealloc (in most cases) anymore. And you don't need to synthesize properties anymore. And viewDidUnload won't be called anymore. So, yeah. But there are still a few of my organization quirks that remain. I like notification responders grouped, and UI response methods (IBActions, etc) grouped, and so on. Delegate methods always go to the bottom, though if multiple delegate protocols are in use, the specific order doesn't matter. The #pragma mark usage in the .m files here are quite typical of how I do things. I don't normally do it in the .h file quite so much, but wanted things to look nice for public consumption. The specific order of anything in these files doesn't really matter, but for sake of consistency, try to follow some kind of pattern.

 

As I said at the beginning, I often want all of [instances of class] to do something. Naturally this points to categories, and there are categories here, but categories don't cover everything. For example, if I always want view controllers to do something in viewWillAppear:, a category isn't going to accomplish that easily, if at all. For far too long, my solution to this has been to use templates. Every time I wanted a table view (I don't like UITableViewController), I'd fire up my template that contains a table view property, and be on my merry way. I even sorta made this work with XIBs in Xcode 4. I always got what I wanted, my code was consistent, and I was doing less work. Yay! The thing about templates is that you are effectively copy-pasting code. If you change your mind about how something should work, then all of the other hundreds of classes that were created by your template have to be changed. Or, most likely, don't get changed. Another issue with templates is that your non-standard templates don't keep up when Apple changes their templates. This is not to suggest that all of Apple's templates are winners, but if they start adding something or removing something, one should at least inquire if that is a noteworthy change. I would still be trucking along adding now-useless dealloc and viewDidUnload methods if I was continuing to use my templates. I've decided that it is useful to start with Apple's templates, quickly observe any changes, and then copy-paste in my style stuff (pragma marks, etc).

 

If templates are out, and categories don't cover everything, that pretty much leaves subclassing. Instead of always subclassing UIViewController and copy-pasting in what I want over and over again, make a new common view controller. I've made BTIViewController. And then all of my view controllers can inherit from it. Don't need viewDidUnload anymore? One class, delete one method, done. Need to update didReceiveMemoryWarning since viewDidUnload isn't called anymore? One class, modify one method, done (Ignoring customization in subclasses, of course). All subclasses then inherit that change. And although this is less relevant with iOS 6, want EVERY view controller in your project to have the same autorotation behavior? One class, one method, done. (Really wish I'd thought of this years ago...). And then differences are handled like any other subclass. Override any behaviors you want to change.

 

So the "meat" of BTIConcepts is really found in 3 classes: BTIObject, BTIViewController, and BTITableViewCell. They don't have to do much at all- BTIObject in particular does not - but by simply using them, downstream activities become much easier if you need to apply changes across the board. Instead of NSObject, inherit from BTIObject. Instead of UIViewController, inherit from BTIViewController. If you don't like what my classes do, then modify them or make your own. But the key concept here is to insert something as high in the class hierarchy as you can, so that you can easily apply mass changes if the need should arise. I would probably even go so far as to argue that you should do this even if your inserted class is totally blank. Prevents having to go change all of your inheritances later.

 

BTIObject - At the moment all it does is provide a custom description method. It automatically logs all properties. Before I came up with this, I had lengthy and quite manual description methods. This is easier.

 

BTITableViewCell - I hate worrying about the cell identifier, particularly with XIB-based cells. Now, (hat tip to Jeff LaMarche) I no longer have to.

 

BTIViewController - Now we're getting into more functionality. First of all, I hate when other classes call initWithNibName: (or initWithStyle: for UITVC). That's bad OOP, IMO. The 'parent' VC has to know too much about this VC when doing this. Is there a nib? What name does it have? And if this VC is used in multiple places across an app, these decisions have to be made every single time. Sloppy, unnecessary work. So right off the bat I override init to pass through to initWithNibName:. Parents simply alloc/init, done.

I always want notification listeners to unsubscribe in dealloc. Done. The number of reasons to have dealloc in a view controller decreases even further.

 

The bulk of the remaining additions deal with BTINotificationHandlers, which I'll describe in a moment. This view controller will automatically register and unregister notifications at appropriate times. No more forgetting to unregister, or unregistering incorrectly.

 

Pre-iOS 6, if I wanted each view controller to have the same autorotation behavior, I'd define that behavior one time in this class. No more forgetting that VC's default to portait if you don't override the proper method. I didn't include it here since the code is aimed at iOS 6, but it would be easy enough to add.

 

BTITableViewController - This can be viewed as an alternative to UITableViewController, but I'm not really trying to recreate that class since I don't like it. I define basic table view stuff like a property and conform to protocols. Additionally, there are some features that get you started for handling things like selection and searching. Not very much code is implemented, it's more of a "here are some tools that should be useful" kind of thing.

 

At the time of writing, I've really only focused on table views, since that's most of what I do. But this concept could easily be expanded. If you do a lot of web views, you could make a BTIWebViewController that doesn't have to do much more than add a web view property and become the delegate. But you could also implement the delegate methods so that the activity spinner triggers at appropriate times, and then never worry about it again. You could make an image view class, perhaps embedded in a scroll view, so that each time you want to show an image you get zooming and panning. The point of all of this is to identify routine activities, and then put them in one place rather than doing them over and over again. Like I've done here:

 

BTIArrayTableViewController.h BTIManagerTableViewController.h BTICoreDataTableViewController.h - These are common flavors of table view controllers that I make. The first is for really basic stuff, nothing fancy. A list of strings, perhaps. The second utilizes another of the models that I'll mention here soon, BTITableContentsManager. The goal here is to define your table information in one place - contents and behaviors - rather than having a ton of if/else statements in each of your delegate methods. And lastly, one that is powered by a NSFetchedResultsController that gets defined in subclasses. Each of these has sufficiently different needs that I felt it made more sense to split them up rather than make a uber-table view controller.

 

That covers the view controllers. On to categories...

 

BTIErrorCategories - Described here.
NSArray - Isn't it annoying that we get a lastObject method that doesn't crash on an empty array, but we don't have a firstObject method?
NSMutableArray - Isn't it annoying that we get a removeLastObject method but we don't have a removeFirstObject method? And isn't it annoying that moving an item to a different index requires removing and reinserting?
NSNotificationCenter - Post notifications on the main thread.
NSManagedObject - Described here.
UITableView - Came from a book. Books are good.
UIDevice - Wrappers around the userInterfaceIdiom for nicer-looking code.

 

Little stuff. They don't have to be complicated. Sure, making complicated stuff simple is nice, but making repetitive stuff less repetitive is nice too.

 

Last but not least are a few models.

 

BTINotificationHelper - I've written about them here. The short version is that these let you define notification handlers in one spot, as opposed to registering in one place, and then unregistering with similar parameters somewhere else. Define all of the usual stuff, along with an extra parameter describing when this notification should be active. Then register/unregister as needed. This class doesn't do much by itself, but BTIViewController has been rigged to automatically handle a couple of common scenarios.

The next few are for table views.

 

BTITableSectionInfo - I came up with this a long time ago, mostly for table headers. The app I was working on had a crazy if/else scheme to determine when to show headers. Finally decided it made more sense to come up with a model to encapsulate what was necessary, defining things at the time I was building the data list. When I later learned of NSFetchedResultsSectionInfo, I rearranged this class a bit to mimic it. So you can use this class to build up your table data, a section at a time. Define headers/footers, add contents, and off you go. Throw a bunch of these in an array, and multi-section table view life gets easier.

 

BTITableRowInfo - This one isn't quite as useful for model-driven tables (ex: list of people, list of addresses, etc). But for table views with a lot of individual behaviors, such as a settings screen that might drill deeper in any number of directions, this can be quite handy. Before coming up with this, I would build arrays of strings to define the overall structure. Then cellForRow and didSelectRow would each have a massive if/else chain that determined what to show in each row, and then where to go in the event of a row tap. I'm not proud; I did it this way for a long time. Once I got my head wrapped around blocks, I realized there was a better way. Using this class, you can pack up this information into a single object, then extract what you need in the various delegate methods. It may not be practical in 100% of cases, but it sure covers 90+% of what I've needed. Any remaining if/else cases are truly for exceptions, rather than for everything.

 

BTITableContentsManager - This class took me longer to create than it should have. Ever since learning Core Data, I've really enjoyed the objectAtIndexPath: method that NSFRC provides. I've wanted to be able to do that in non-Core Data situations, too. After creating the previous two classes, it finally seemed like the time was right to pursue it. I wish I had done it sooner. So although it isn't capable-enough at the moment, you can think of this as a non-Core Data version of NSFetchedResultsController. Right now, you have to build up the table structure manually. I'd like to get to a point where I just dump a pool of objects in, and then hand it a sort descriptor and maybe a predicate. I'm not there yet. In the meantime, enjoy simplified table delegate methods while using this class.

 

So there you have it: BTIConcepts. I've tried to put nice overviews into each of the .h files. I also try to make code that is fairly self-explanatory. Hopefully this code helps you out, or at least inspires you to simplify your own coding life somehow. Enjoy.

A Model (Object) Is A Beautiful Thing

In object-oriented programming, a common pattern is MVC: Model-View-Controller.  For some reason, the Model typically seems to be the slowest concept to grasp for new developers.  Views are easy to understand, probably because they are visual.  Controllers are maybe not 100% understood, but at least there are plenty of examples so people plod through.  Generally speaking, however, the model is often the most important component of an app, and the number of ways to handle the model badly are considerable.  This is odd, because the good ways really are not that hard.

 

Of Thee I String

 

Most developers begin their programming lives with strings.  Strings are easy and readable.  And then for more complicated structures, they move onto arrays.  Arrays are still relatively easy to understand, and aren't too hard to visualize.  They are also easy to teach, which is why books and tutorials tend to begin here.  And that's fine, we all need to start somewhere.  Let's look at a simple list of colors:

 

NSArray *colorList = [NSArray arrayWithObjects:@"Blue", @"Green", @"Red", nil];

 

Straightforward, easy to read, a good starting point.  If we were discussing table views, then it would be simple to take this array and use it to drive a table view.  That's more than sufficient for static display, and helps to establish concepts.  Another example:

 

NSArray *actors = [NSArray arrayWithObjects:@"Brad Pitt", @"William H. Macy", @"Jennifer Aniston", nil];

 

Still just strings, still quite easy to read.  But now we've started to complicate things a bit, and certain downstream tasks get harder.  Let's say I wanted to sort this list by last name.  That's going to be a challenge, since each full name is a single string.  I would need a way to identify the last name within the string.  I could potentially carve each string into pieces, and take the second piece.  But that would give me "H." for Mr. Macy.  Ok, so I need to take the last piece instead.  That should work as long as I haven't inadvertently entered "Pitt, Brad" somewhere. 

 

Ideally we need to split this data up in a known fashion, probably at the time of creation.  Relying on algorithms to extract information can be risky if the algorithm is wrong, so it is better to simply define things from the get go.  In this case, that means keeping the first name separate from the last name.  The question then becomes how to do that.

 

Don't Be A Dictionary

 

Level 2 in the programming learning curve leads to dictionaries.  At first glance, dictionaries are great.  They can contain anything, there is no hard structure, and in basic cases they can save data directly to plists without much trouble.  I'll use a mutable dictionary here since the code is easier to understand, but a sample actor represented in a dictionary might look like this:

 

NSMutableDictionary *actor = [NSMutableDictionary dictionary];
[actor setObject:@"Brad" forKey:@"firstName"];
[actor setObject:@"" forKey:@"middleName"];
[actor setObject:@"Pitt" forKey:@"lastName"];

 

The string has been broken up into pieces, and can now be located via an identifier, the key.  Retrieving a value is relatively simple:

 

NSString *actorFirstName = [actor objectForKey:@"firstName"];

 

Now instead of putting strings into an array, add dictionaries instead:

 

NSArray *actors = [NSArray arrayWithObjects:actor1, actor2, actor3, nil];

 

There are ways of sorting arrays using these keys, so it would seem that we've solved our problem.  For now, at any rate.

 

The problems with using dictionaries take a while to reveal themselves.  Let's say that you set aside this project for a couple of months to work on something else, and then come back to it in order to make changes.  You find yourself looking at this line of code:

 

NSDictionary *actor = [actors objectAtIndex:2];

 

Ok, so you're referencing a single dictionary in an array, and you're calling it an actor.  Great.  Now then, what should "actor" have in it?  Hrm, well, I sort of remember caring about the names, so probably names.  Maybe their birthdays.  Oh, it would be nice if there was a list of their movies too.  I probably thought that was a good idea when I made this, so I'll just assume this data is there.  Wonder what I called it.  Probably "birthday".  Great, let's see what happens:

 

NSString *birthday = [actor objectForKey:@"birthday"];
NSLog(@"birthday is: %@", birthday);
…
Log output: birthday is: (null)

 

Uh oh.  It's not there.  I must have called it something else.  And come to think of it, would it really be an NSString?  It's a date, and we have NSDate objects.  Might have been one of those.  How can I find out?  Well, I could log the entire dictionary:

 

NSLog(@"actor is: %@", [actor description])

 

Hrm, no birthday.  Is that because I didn't have information for this actor, or is that because none of the actors have birthdays?  Not sure.  And there isn't a handy way to find out, either.  All I can do is figure out where I first created these dictionaries, and see what is there.

 

The point that I'm making here in a roundabout way is that dictionaries do not document themselves.  Every NSDictionary looks the same from the outside.  It is the contents that matter, and short of manual interrogation, there is no easy way to find out what the contents of a given dictionary are or should be.  If you wanted to be diligent, you could put something in the comments somewhere like this:

 

// I hereby define an "actor" dictionary as containing the following data:
// First name shall be an NSString stored with the key "firstName"
// Middle name shall be an NSString stored with the key "middleName"
// Last name shall be an NSString stored with the key "lastName"

 

You could, but no one takes the time to do this.  And because dictionaries are so handy and flexible, you can add and remove keys all day long, and totally forget to update this list, at which point the list just becomes another point of confusion, rather than an aid.  Without this list, you do not have an easy way to figure out what this dictionary should contain.  You will have to waste time researching your own code and doing logging just to figure out what this should be.

 

But wait, there's more.  Let's say a common activity in our actor program is to display the full name of the actor.  That might look like this:

 

NSString *firstName = [actor objectForKey:@"firstName"];
NSString *lastName = [actor objectForKey:@"lastName"];
NSString *fullName = [NSString stringWithFormat:@"%@ %@", firstName, lastName];

 

Blech.  That's a lot of code, copy-pasted all over the place.  And I forgot the middle initial.  And sometimes it outputs "Bob (null)".  So I need to make it more complicated, add some error handling, and then re-copy-paste it all over the place.  Ah ha! I know a little about OOP, I'll just make a helper method somewhere.  The only thing I know how to grab from anywhere is the app delegate, so I'll put it there!

 

- (NSString *)fullNameFromActor:(NSDictionary *)actor;

 

Brilliant!  Well, not so much.  I mean, this will of course work.  But look how far separated it is from your data.  All of these actors are defined way over in some view controller (or better yet, a data controller) somewhere, but this method is here in the app delegate.  Any time that you have one of these dictionaries in your hand, you have to go all the way over to the app delegate to get this method.  More advanced programmers might be tempted to move this code into a Category, and that's certainly an option, but a bit beyond the scope of this article and not a good solution for a case like this anyway.

 

The ideal solution to this problem would include some handy form of documentation that can be easily referenced later, and would also provide a convenient place to store helper methods.  And that ideal solution really isn't that hard to do.

 

Subclassy

 

Creating a custom model subclass is straightforward.  Create a new file, starting with Objective-C class, then choose to subclass NSObject.  By convention, class names should begin with a capital letter, so "Actor", not "actor".  For bonus points in avoiding name clashes, use some kind of prefix.  I use BTI, so I would name it BTIActor.  Do NOT use NS.  Do NOT use UI.  These are Apple's territories.  So NSActor and UIActor are wrong.  Period.  Wrong.  Don't do it.  No exceptions.

 

So we have a new class now:

// BTIActor.h

@interface BTIActor : NSObject
{

}

@end

 

…what do we do with it.  Well, with the dictionary, we were thinking in terms of keys.  Here in a model class, you think in terms of properties instead.  This is no different than defining a label property in a view controller.  Let's begin:

 

// BTIActor.h

@interface BTIActor : NSObject
{
}

@property (nonatomic, copy) NSString *firstName;
@property (nonatomic, copy) NSString *middleName;
@property (nonatomic, copy) NSString *lastName;
@property (nonatomic, copy) NSDate *birthday; 

@end

 

Immediately we have a much, much better situation than we had with the dictionaries.  First of all, there is a list of each element in this model.  3 strings and a date.  No keys to remember or mistype, it's all right here.  And also notice that we know what everything is.  Ah, the birthday is a date object.  Nothing to remember, nothing to get wrong.  With dictionaries, it is always objectForKey:.  What kind of object?  I don't remember.  Have to go look it up, uh, somewhere.  With this class, all I have to do is click on the .h file anytime I want to know something.  It's easy for me to find today, and it's easy for me to find in 3 months.  It is inherently self-documenting.

 

And I'm not even done yet.  How about that helper method?  Put it here, too:

 

// BTIActor.h

@interface BTIActor : NSObject
{
}

@property (nonatomic, copy) NSString *firstName;
@property (nonatomic, copy) NSString *middleName;
@property (nonatomic, copy) NSString *lastName;
@property (nonatomic, copy) NSDate *birthday;

- (NSString *)fullName;

@end

 

The data remains broken up so that you can still get to individual elements (last name) if you need to, but you can make as many handy methods as you need all right here on the object that can use them.  Want to do last name, first name?

- (NSString *)reversedFullName;

 

How old is this actor right now?

- (NSInteger)currentAge;

 

On and on and on.  If you have a need, make a method for it here, then you can use it wherever you use this model.  Granted, the implementations of these methods may not necessarily be any simpler this way, but at least you have everything you need right here.

 

The .m file wouldn't be all that different from an average view controller.  Synthesize your properties and implement your methods:

 

// BTIActor.m

#import "BTIActor.h"

@implementation BTIActor

@synthesize firstName = ivFirstName;
@synthesize lastName = ivLastName;
...
- (NSString *)fullName
{
   return [NSString stringWithFormat:@"%@ %@", [self firstName], [self lastName]];
} 
... 

@end

 

There are a variety of other things to do here.  There should be a dealloc method (unless using ARC).  Might want an init method, too.  But chances are, this is all stuff you've done elsewhere before, most likely in a view controller.  Same idea here.

 

Model objects are easy to create, so there isn't much of a reason to hesitate to use them.  Describing a car?

// BTICar.h

@interface BTICar : NSObject
{
}

@property (nonatomic, copy) NSString *make;
@property (nonatomic, copy) NSString *model;
@property (nonatomic, assign) NSInteger *year;
@property (nonatomic, assign) NSInteger *numberOfDoors;
@property (nonatomic, assign) CGFloat engineDisplacement;

@end

 

Describing a shirt?

// BTIShirt.h

@interface BTIShirt : NSObject
{
}

@property (nonatomic, copy) NSString *size;  // S, M, L, XL
@property (nonatomic, retain) UIColor *color;
@property (nonatomic, assign) BOOL isLongSleeve;
@property (nonatomic, assign) BOOL hasPoppedCollar;

@end

 

If you can figure out how to put this stuff into a dictionary, then you can do the same thing even better with a model class.  There really is nothing to be afraid of here.  So kick a dictionary to the curb today!

 

Work Your Model

 

How do you use a model class?  Well, the first thing you need to do is add this to the .m file wherever you want to use them:

#import "MySuperAwesomeModel.h"

 

Now you can use it.  Let's revisit the dictionary version:

NSMutableDictionary *actor = [NSMutableDictionary dictionary];
[actor setObject:@"Brad" forKey:@"firstName"];
[actor setObject:@"" forKey:@"middleName"];
[actor setObject:@"Pitt" forKey:@"lastName"];

 

Doing this same thing with the model object:

BTIActor *actor = [[BTIActor alloc] init];
[actor setFirstName:@"Brad"];
[actor setMiddleName:@""];
[actor setLastName:@"Pitt"]; 

 

It's cleaner, easier to read, and as a double-bonus, Xcode will help you type this stuff.  Xcode does not help at all when typing @"strings".  So you are much more likely to make a typo.  If you make a typo with dictionary keys, you won't figure it out until much letter.  Xcode will not warn you.  The key will simply not be what you expect it to be.  That's hard to troubleshoot.

 

Use them in arrays just like you did with dictionaries:

[actors addObject:actor];
...
BTIActor *someActor = [actors objectAtIndex:1];

 

Oh yeah, and don't forget the helper method:

NSString *fullName = [someActor fullName];
[[self nameLabel] setText:fullName]; 

That's more or less all there is to it.

 

There are a couple of other aspects to model objects that I will address with a future post, particularly related to saving and loading these objects.  If you are in a hurry to do so, do some Googling for "NSCoding".

UITableView How-To: Part 6 - Inserting, Deleting, and Reordering Cells

Part 1 | Part 2 | Part 3 | Part 4 | Part 5

 

It seems to be time for my annual table view tutorial post.  In this long-overdue episode, we'll take a look at what is involved with making a table view support dynamic content.  If you want to allow the user to add, remove, or rearrange cells, then these are the basics that you need to understand.

 

One of the first changes to make is to use a proper data container.  If you've been using an NSArray up to this point, then you need to switch to NSMutableArray, or and/or switch NSDictionary to NSMutableDictionary.  You can add and remove items to/from the mutable versions, but cannot from non-mutable versions.

 

Create a new project using whatever template you want.  I'm using the Single View one for simplicity sake.  Place a table view on it, and get it wired up with a property.  In addition to that, place 2 buttons on the screen, one called Edit, and the other called Insert.  It doesn't need to be fancy, just something like this:

 

 

Declare IBActions for each button, and wire them up.

 

- (IBAction)insertButtonPressed:(UIButton *)button;
- (IBAction)editButtonPressed:(UIButton *)button;

 

Our initial data is just going to be a handful of strings.  Declare a property, synthesize it, then customize a getter:

 

@property (nonatomic, retain) NSMutableArray *contents;
...

@synthesize contents = ivContents;
...

- (NSMutableArray *)contents
{
   if (ivContents == nil)
   {
      ivContents = [[NSMutableArray alloc] initWithObjects:@"A", @"B", @"C", @"D", @"E", nil];
   }
   return ivContents;
}

 

And let's quickly set up the table view delegate and data source methods.

 

- (NSInteger)tableView:(UITableView *)tableView
numberOfRowsInSection:(NSInteger)section
{
   NSInteger rows = [[self contents] count];
   return rows;
}

 

The number of rows is the count of the array.  Easy enough.

 

- (UITableViewCell *)tableView:(UITableView *)tableView
cellForRowAtIndexPath:(NSIndexPath *)indexPath
{
   static NSString *cellIdentifier = @"cellIdentifier";

   UITableViewCell *cell = [tableView dequeueReusableCellWithIdentifier:cellIdentifier];
   if (cell == nil)
   {
      cell = [[[UITableViewCell alloc] initWithStyle:UITableViewCellStyleDefault reuseIdentifier:cellIdentifier] autorelease];
   }

   NSString *rowContent = [[self contents] objectAtIndex:[indexPath row]];

   [[cell textLabel] setText:rowContent];

   return cell;
}

 

And then to populate the cell, we grab the string out of the array, and give it to the cell's label.  Go ahead and run the app to make sure that the table fills in correctly.  Beware that if you press either button, it will crash right now since we haven't implemented those methods yet.

 

 

Insert Row

 

Let's start with inserting rows.  The UITableView method for inserting rows is insertRowsAtIndexPaths:withRowAnimation:.  First thing to note is that this has an animation property.  You can slide rows in from above, below, either side, or simply fade in.  The other thing to note is the plural - rowS - meaning that you can insert more than 1 row with this method if you want to.

 

Let's continue by implementing our insert method.  The method above deals with index paths, so the first thing we're going to do is build one.  We're making the executive decision right now that any new rows will appear at the top of the table, and this is row 0.  A handy construction method is indexPathForRow:inSection:.  Note that it has a section parameter.  We are only using a single section at the moment, so that would be section 0.  Let's begin:

 

- (IBAction)insertButtonPressed:(UIButton *)button
{
   NSInteger section = 0;
   NSInteger row = 0;
   NSIndexPath *indexPath = [NSIndexPath indexPathForRow:row inSection:section];

   NSArray *indexPathsToInsert = [NSArray arrayWithObject:indexPath];

   [[self mainTableView] insertRowsAtIndexPaths:indexPathsToInsert withRowAnimation:UITableViewRowAnimationRight];
}

 

We create an index path, then create an array to hold it, and finally pass that array along to the table view via the insert method.  If you run the app now, and hit the Insert button, you will again crash.  But this time there is an actual problem we need to solve.  Look in the console, and you'll find one of the most helpful error messages in all of iOS development:

 

Terminating app due to uncaught exception 'NSInternalInconsistencyException', reason: 'Invalid update: invalid number of rows in section 0.  The number of rows contained in an existing section after the update (5) must be equal to the number of rows contained in that section before the update (5), plus or minus the number of rows inserted or deleted from that section (1 inserted, 0 deleted) and plus or minus the number of rows moved into or out of that section (0 moved in, 0 moved out).'

 

This crash message tells you exactly what went wrong, but it does take a little bit of getting to used in order to understand what it is saying.  Basically, the table is saying "Hey! I knew from before that you had 5 rows, and then you just told me to add 1, so I did that, but after I did that, there were still only 5 rows!"  Well clearly you are stupid, Mr. Table View, because you obviously should have 6 rows now, since I told you to add one.

 

Or should it?  How does the table view know how many rows should be there?  Oh, right, from this:

 

- (NSInteger)tableView:(UITableView *)tableView
numberOfRowsInSection:(NSInteger)section
{
   NSInteger rows = [[self contents] count];
   return rows;
}

 

The array still only has 5 objects.  Even though we inserted a row, the array still has just 5 objects.  The table view will ping this method again as a part of the insert process.  If 5 (old) + 1 (inserted) does not equal 6 (new total), then it will complain.  We only have a total of 5, so that's a problem.

 

This is a very important concept to understand, and it is equally important when we delete and rearrange rows in a few minutes.  Inserting a row is a view operation.  Remember the old, trusty MVC concept, Model-View-Controller?  What we did so far is make a change to V, the view.  So what still needs to happen is to make a change to M, the model.  If you insert a row in a table, you must also add something to the array.  If you remove a row from a table, you must also remove something from the array.

 

So let's revisit the insert method, and add something to the array.  Just to be quick, let's add a string that is simply a count of the number of items in the array at the time.

 

- (IBAction)insertButtonPressed:(UIButton *)button
{
   NSInteger section = 0;
   NSInteger row = 0;
   NSIndexPath *indexPath = [NSIndexPath indexPathForRow:row inSection:section];

   NSString *extraContent = [NSString stringWithFormat:@"%d", [[self contents] count]];
   [[self contents] insertObject:extraContent atIndex:row];

   NSArray *indexPathsToInsert = [NSArray arrayWithObject:indexPath];

   [[self mainTableView] insertRowsAtIndexPaths:indexPathsToInsert withRowAnimation:UITableViewRowAnimationRight];
}

 

Run the app again, and you should be able to hit the insert button as many times as you want.  Each time, a new row will appear at the top of the list, sliding in from the right.

 

 

Some additional exercises for you to perform on your own:

• Use different animation options to see how each one works.
• Use a different row value to insert at different points in the table.  Beware that you should not use an index larger than the array.  You will need much smarter code than this is to protect against that.

 

Delete Row

 

There are 2 basic UI's for deleting rows.  There is swipe-to-delete, and then there is putting the table view into edit mode, where all of the red circles appear.  If you try to swipe on your rows right now, nothing will happen.  Swiping is not enabled by default, you have to implement a datasource method to get it.  That method is:

 

- (void)tableView:(UITableView *)tableView
commitEditingStyle:(UITableViewCellEditingStyle)editingStyle
forRowAtIndexPath:(NSIndexPath *)indexPath
{
}

 

The mere presence of this method enables the swipe-to-delete UI.  It doesn't do anything yet, but you can go ahead and run your app, swipe on a row, and you will see the delete button.  Now we need to add the guts to this method.

 

The first item to note is the editingStyle parameter.  A quick trip to the documentation reveals that the value could be none, insert, or delete.  I don't believe I have ever used this parameter for anything other than delete.  Still, better safe than sorry:

 

if (editingStyle == UITableViewCellEditingStyleDelete)

 

For inserting a row, we had to build an index path.  In this case, we are given an index path parameter already.  The table view delete row method is deleteRowsAtIndexPaths:withRowAnimation:.  Basically, the exact opposite of the insert method.  Instead of flying in from the right, the row will fly out to the right, and so on.

 

Remember from inserting a row that we must also make a change to the array.  This is no different.  We will remove a row, therefore we must remove something from the array at the same time.

 

- (void)tableView:(UITableView *)tableView
commitEditingStyle:(UITableViewCellEditingStyle)editingStyle
forRowAtIndexPath:(NSIndexPath *)indexPath
{
   if (editingStyle == UITableViewCellEditingStyleDelete)
   {
      [[self contents] removeObjectAtIndex:[indexPath row]];

      NSArray *indexPathsToRemove = [NSArray arrayWithObject:indexPath];

      [tableView deleteRowsAtIndexPaths:indexPathsToRemove withRowAnimation:UITableViewRowAnimationRight];}
   }
}

 

We remove an item from the array, then delete the corresponding row.  Run the app now, and you will be able to swipe-to-delete anything you want.  If you delete everything, just hit the insert button to put more stuff back in and then go delete it again.

 

Swipe-to-delete is nice, but sometimes it is better to show all of the delete circles to let the user see that deleting can be done.  This is done by turning on the edit mode for the table view.  By default, edit mode is off, so we will need to turn it on.  This is where our other IBAction method comes in:

 

- (IBAction)editButtonPressed:(UIButton *)button
{
   [[self mainTableView] setEditing:![[self mainTableView] isEditing] animated:YES];
}

 

We look at whether or not the table view is currently in edit mode, and then set it to the opposite.  If you run the app now, you can hit the Edit button multiple times to turn on and off edit mode.  You can also go ahead and delete rows while you're there.

 

You've probably seen apps where the button says Edit sometimes, and Done sometimes.  Let's make that happen:

 

- (IBAction)editButtonPressed:(UIButton *)button
{
   [[self mainTableView] setEditing:![[self mainTableView] isEditing] animated:YES];

   NSString *buttonTitle = ([[self mainTableView] isEditing]) ? @"Done" : @"Edit";

   [button setTitle:buttonTitle forState:UIControlStateNormal];
}

 

For additional research that I'm not going to go into here, if you are using a navigation bar or a toolbar, you can use UIViewController's built-in editButtonItem.  As noted in the documentation, you will need to implement setEditing:animated:, and then do basically the same thing I've done here (except for the button title part).

 

Insert And Delete Rows

 

For more complicated tables, a single insert command or a single delete command may not be sufficient.  Perhaps you will need to add AND remove some rows.  Or maybe you will add rows AND add sections (there is a different method for that, see the documentation).  If you will be performing multiple actions, then you need to group those activities inside of a table animation block.

 

Drag another button onto the view, and call it "Silly".  Then implement this method:

 

- (IBAction)sillyButtonPressed:(UIButton *)button
{
   NSIndexPath *indexPath = [NSIndexPath indexPathForRow:0 inSection:0];
   NSArray *indexPaths = [NSArray arrayWithObject:indexPath];

   [[self mainTableView] beginUpdates];

   [[self mainTableView] insertRowsAtIndexPaths:indexPaths withRowAnimation:UITableViewRowAnimationRight];
   [[self mainTableView] deleteRowsAtIndexPaths:indexPaths withRowAnimation:UITableViewRowAnimationRight];

   [[self mainTableView] endUpdates];
}

 

These are the same commands we did previously, just now we are doing them at the same time.  We begin by telling the table view that we are about to give it multiple commands, via the beginUpdates method.  Then we perform whatever actions we need, and tell the table view we are done via the endUpdates method.  The table view will analyze all of these changes and come up with an animation that looks nice, performing the adds and deletes at the same time.

 

If you run the app right now, each time you hit the Silly button, the first row will slide to the right and then back to the left.

 

The 2 animations do not have to be the same.  Change one to Left, and then see what happens.

 

You may have noticed that we did not change the array.  In this (really silly) case, we didn't need to.  We add 1 row, and remove 1 row.  That means a net change of 0, so the number of items in the array is still correct.  BUT, for more complicated situations, you absolutely would need to change the array.  If you add 5 rows and delete 2 others, then your array needs to become 3 items longer.

 

Reorder Rows

 

Changing the order of items in the table is a common need.  You may have noticed that we have not yet seen the drag widgets on the right side of the table.  Just like the delete buttons, we need to implement a method in order to see them.  Also, they only show up in Edit mode, so our Edit button will be involved.  The necessary method is:

 

- (void)tableView:(UITableView *)tableView
moveRowAtIndexPath:(NSIndexPath *)fromIndexPath
toIndexPath:(NSIndexPath *)toIndexPath
{
}

 

Just like before, the mere presence of this method is enough to show the widgets.  Run the app, hit the Edit button, and you will see them.  If you try to reorder rows, it will LOOK like it works, but it really doesn't.  In order to prove that, I need to implement a different method:

 

- (void)tableView:(UITableView *)tableView
didSelectRowAtIndexPath:(NSIndexPath *)indexPath
{
   NSString *rowContent = [[self contents] objectAtIndex:[indexPath row]];
   NSLog(@"tapped row is: %@", rowContent);
}

 

Run the app, tap on a row, and then you will see this in the console.  Make sure that when you tap A, you see A in the console.  Then edit the table, drag the last row to the top, and hit the Done button.  Now tap on rows and see what happens.  When you tap on E, you should see A in the console.  Tap on A, you'll see B, and so on.

 

Why is that?  Well, it's the same reason as before.  The table view is doing the visual stuff, but the underlying data - the array - was never changed.  We need to handle that ourselves:

 

- (void)tableView:(UITableView *)tableView
moveRowAtIndexPath:(NSIndexPath *)fromIndexPath
toIndexPath:(NSIndexPath *)toIndexPath
{
   NSString *contentsToMove = [[[self contents] objectAtIndex:[fromIndexPath row]] retain];

   [[self contents] removeObjectAtIndex:[fromIndexPath row]];
   [[self contents] insertObject:contentsToMove atIndex:[toIndexPath row]];

   [contentsToMove release];
}

 

We select the item, and retain it because we don't want it to die when we pull it out of the array.  Then we remove it, and insert it back in at the new location.  Then we release it to balance the retain.

 

Final Thoughts

 

If you read back through this tutorial, you will see that "reloadData" does not appear anywhere here.  reloadData is sort of the nuclear option, and generally speaking it is cheating.  Reloading the table also defeats any animations that might otherwise happen.  In this app right now, if you insert an item, you'll get a nice animation showing the new row.  If you delete an item, you'll get a nice animation removing the row.  The remaining rows are shifted up or down in a nice animated fashion.

 

You could go to the above code, replace each insert/delete line with a reload line, and the end result will still be a table showing the correct contents.  So it does actually "work" to do the reload.  But if you watch carefully, there will be a difference.  The new row just pops into existence.  Deleted rows just instantly disappear.  The animations are gone.  Reloading a table doesn't do any animations.  The user experience is not as good, and frankly using reloadData in these situations is Amateur Hour.  It isn't required, as obviously evidenced by the code above.  So go the extra mile, and don't use table reloading as a replacement for actually understanding how these things work.

 

UITableViewDataSource and UITableViewDelegate define a number of methods to further refine these behaviors.  Have a row that you don't want to be deleted?  There's a method for that.  Have a row that you don't want to be moved?  There's a method for that.  Want to limit where a row can be dragged?  There's a method for that, too.  All I have shown here is the bare minimum necessary to enable these features.  For more complicated behaviors, you will need to employ some or all of these other methods.  See the documentation for a full list of what is available.

 

Here is the sample project for this tutorial:

 

BTITableViewModification.zip

UITableView How-To: Part 5 - More About XIB-Based Cells

Part 1 | Part 2 | Part 3 | Part 4 | Part 6

 

(This is really the second half of Part 4, so we'll just continue with the same project)

 

I've got one more key topic to address, then we'll take a look at some alternate techniques.

 

By the end of Part 4, we created a custom view layout using IB, so we've got the visual part down. That really just leaves one more basic characteristic to talk about: actions. In addition to customizing the look of your cell, you can customize the behavior of your cell, and this is most easily done by adding controls such as buttons, switches, and so on. We're just going to do a quick button, but the concept applies to any of the other controls you may wish to use.

 

So, open up CustomTableCell.xib and drop a button smack in the middle:

 

 

With a typical view controller, we'd connect this button to an IBAction. That's what we want to do here as well, but the question is: where is the IBAction? There are 2 basic options, in the cell class or in the view controller class. Where you should put it will depend on the goal you are trying to accomplish. If you put it in the cell class, then it really isn't any different than wiring it up as you would in a view controller. Depending on your goal, this approach can either simplify or complicate your ultimate outcome. But for our purposes here, we're going to put the IBAction in the view controller. So add this declaration to BasicViewController.h:

 

- (IBAction)buttonPressed:(UIButton *)button;

 

(you are probably accustomed to seeing (id)sender for these things. Go ahead and do that if you prefer. I like the type to be correct, and rarely have a need to mix these methods with multiple types of controls)

 

Now we just need to wire it up. You're going to drag from the button to File's Owner like you normally would. The only difference is that this is happening in the cell class instead of the view controller class.

 

 

All that's left is to make the method do something. You can do a simple stub for now to make sure that this works:

- (IBAction)buttonPressed:(UIButton *)button
{
   NSLog(@"It worked!");
}

 

Go ahead and run the app, and you should see this message in the console when you hit any button. And now we reach the fun part. As you can see, this method fires when you hit any button. So, how do you know which button?

 

There are a couple of ways to answer this question and, like so many programming challenges, which way to go will depend on your situation. You could use the tag property of the button. This is a common thing to do when you have multiple buttons and would like to distinguish between them. You would need to declare a property in the cell for the button, and then you could assign the tag value in cellForRow like this:

 

[[cell theButton] setTag:[indexPath row]];

 

Then you extract the tag value in the IBAction method:

 

NSLog(@"Pressed button at row: %d", [button tag]);

 

For many tables, this will be an adequate and simple approach. However, if you recall some behaviors from Part 3 regarding multi-section tables, then your spidey sense should be warning you that something may be wrong here. We are using the row parameter to identify the cell, but what happens if there is more than one section? You could have row 0 in the first section, and row 0 in the second section, and row 0 in the third section... Remember that row indexes reset in each section. This is why NSIndexPath provides TWO parameters - section and row - because only one parameter is insufficient to find/describe the location.

 

UIButton doesn't have an NSIndexPath property. If you really wanted to, you could subclass UIButton to add that property. Then the approach above would be the same, except you would provide/extract the indexPath instead of merely the row. I personally tend to view subclassing as a last resort, so I've never bothered doing this. But I suppose I could see some situations where BSTableButton could come in handy. But that isn't why I've brought you here today.

 

No matter what the approach, you have to do some work. Above we've done a little work in cellForRow, and a little work in the IBAction method. (And if you subclassed, you've done a lot of work in even more places) Also think in terms of performance. You are flicking your way through a table, and you want to get in and out of cellForRow as fast as possible. Assigning the tag (or indexPath) is just one more thing that has to be done that is preventing you from leaving the method ASAP. So instead of doing the work for each cell, just do the work when the user actually hits the button. The question is how.

 

In the IBAction, I receive the button itself as a parameter. From there, I would like to wind up with an indexPath. This will allow me to know that the 5th button was pressed, so I can go do something to the 5th item in the array. A quick glance at the UITableView documentation reveals a handful of methods that return an indexPath. For all visible rows. For the selected row (before you get excited, this is only for the blue highlighted row, not for tapping on items in the row). The only one that seems useful in this situation is indexPathForCell:. If I have a cell, the table can tell me where it is located.

 

Ok, so how do I get to the cell from the button. Ah ha! Remember that these are all views, and that they have been arranged into an hierarchy. The button would be a subview of the cell, so since I'm starting with the button, I would need to walk UP the hierarchy. You do that with the superview method.

 

This part can require some learning and trial-and-error, so let's do it the hard way before we skip to the answer. Add this to the IBAction:

 

NSLog(@"superview is: %@", [[button superview] description]);

 

Run it and you should see something like this:

 

superview is: <UITableViewCellContentView: 0x4d31390; frame = (0 0; 320 43); layer = <CALayer: 0x4d313f0>>

 

Hrm, UITableViewCellContentView. We're looking for CustomTableCell, so that's not a match. If you look at the top of the UITableViewCell documentation, you'll find the contentView property mentioned, and then you can go read its description. Basically, what we added the button to was the contentView, not the cell directly. So we need to go higher in the hierarchy:

 

NSLog(@"superview is: %@", [[button superview] description]);
NSLog(@"superview superview is: %@", [[[button superview] superview] description]);

 

Try again:

 

superview is: <UITableViewCellContentView: 0x4d31390; frame = (0 0; 320 43); layer = <CALayer: 0x4d313f0>>
superview superview is: <CustomTableCell: 0x4b3ad70; baseClass = UITableViewCell; frame = (0 264; 320 44); autoresize = W; layer = <CALayer: 0x4b39e20>>

 

Bingo. So, with this particular hierarchy, to go from the button to the cell, we need to go up 2 levels in the view hierarchy. This will depend on your actual view hierarchy, which is why I showed the long steps first. Just keep walking up the hierarchy until you find the cell. (I'm sure you could come up with an algorithm to keep walking, but it's never been worth the effort for me) Now that we know where we're going, our actual line of code is:

 

CustomTableCell *cell = (CustomTableCell *)[[button superview] superview];

 

We have the cell, and can now get the indexPath:

 

NSIndexPath *indexPath = [[self mainTableView] indexPathForCell:cell];
NSLog(@"indexPath is: %@", [indexPath description]);

 

Now you have the exact same location that you would have in cellForRow. So you can access your array the same way, and go manipulate your data or otherwise make something happen as you see fit.

 

Cell Identifiers Suck

 

I mentioned in Part 4 that I don't like the way Apple put the cell identifier into the cell's XIB. About a year ago, I discovered a blog post by Jeff LaMarche that provides a workaround. I won't bother repeating what he has said there, so let's just apply the code with a little twist.

 

Add this to CustomTableCell.h:

 

+ (NSString *)reuseIdentifier;

 

And then add these to CustomTableCell.h:

 

- (NSString *)reuseIdentifier
{
   return [[self class] reuseIdentifier];
}

+ (NSString *)reuseIdentifier
{
   return NSStringFromClass([self class]);
}

 

It's the same thing Jeff shows, I just took out the constant declaration as mentioned in the comments. This allows for easy copy-pasting into any cell class.

 

You can now blank out the identifier setting in IB, or forget to include it altogether.

 

And Now For Something New

 

There are a variety of debates regarding XIB-based cells. First there are the usual arguments with the "I only use code, IB is the debbil" people. Then there is another layer for use in cells, with people arguing that XIBs are slower than code because you have to go do disk to load the cell. There must have been some truth to this, because Apple added a new class for OS 4 to address it. It's too bad it took so long, because if anything we needed it more in slower-hardware days of OS 2 than we do today, but they felt it was important enough to create, so we should at least give it a look.

 

Now presenting: UINib.

 

Read the documentation and you'll find that it is basically a caching and instantiation class for loading XIBs. You can use it for any kind of XIB loading, but you can be pretty confident that it was developed for table cells. It doesn't wind up making a tremendous difference in terms of code - if anything it adds some - but I'll take Apple at their word that this is faster in terms of performance. I like using UINib as a property, so add this to BasicViewController.h:

 

@interface BasicViewController : UIViewController <UITableViewDelegate, UITableViewDataSource>
{
}

@property (nonatomic, retain) IBOutlet UITableView *mainTableView;
@property (nonatomic, retain) IBOutlet CustomTableCell *customTableCell;
@property (nonatomic, retain) UINib *customTableCellNib;

 

And then I implement it with a custom getter in the .m file:

 

@@synthesize customTableCellNib = ivCustomTableCellNib;
...

// dealloc
[self setCustomTableCellNib:nil];
...

- (UINib *)customTableCellNib
{
   if (ivCustomTableCellNib == nil)
   {
      ivCustomTableCellNib = [[UINib nibWithNibName:NSStringFromClass([CustomTableCell class]) bundle:nil] retain];
   }
   return ivCustomTableCellNib;
}

 

I customize the getter so that I don't have to care who creates it or when. The first time it is needed, it will get created.

 

So we've added a property, and we've added a method. What's the payoff? Well, not much really. Here is what we had before:

 

if (cell == nil)
{
   [[NSBundle mainBundle] loadNibNamed:@"CustomTableCell" owner:self options:nil];
   cell = [self customTableCell];
   [self setCustomTableCell:nil];
}

 

This now becomes:

 

if (cell == nil)
{
   [[self customTableCellNib] instantiateWithOwner:self options:nil];
   cell = [self customTableCell];
   [self setCustomTableCell:nil];
}

 

Wow. We changed one line of code. Yay. Well, this is more about performance than it is about code reduction.

 

A Couple Of Tweaks

 

Speaking of performance, there is one thing you want to be careful of in cell design, whether it is in code or via XIB: avoid transparency. With our fancy iPhone 4's and iPad 2's, this is becoming less and less of an issue, but the basic premise remains the same: the device likes opacity a whole lot more than it does transparency.

 

What this specifically means as far as the view items go is to turn on the Opaque toggle, and supply a background color. The Opaque toggle is here:

 

 

When you first turn it on, the items will often default to black. Simply apply a different color:

 

 

Naturally this won't work if your background is not consistent, like a gradient or an image. In those cases, you're pretty much stuck with the transparency.

 

The next thing to be aware of isn't performance related, but it is very visual so you'll want to make sure to catch it. For labels (and some others like image views) you will want to specify a highlight color:

 

 

This is the color that the text will be when the user highlights a row. Generally speaking you will want it to be white, but that's a design decision for you. At some point in the last couple releases of Xcode, and I'm not sure when this started, the default automatically became white. So hopefully you shouldn't have to mess with this too much. But if you're on a slightly older version of Xcode, be aware that the default used to be black. Regardless, if you tap a cell, and don't see nice white text, this is where you need to go to fix it.

 

Holy Crap, This Is Long

 

Now you know why I split this into 2 parts. Head back to the cell's XIB, and we're going to make a slight change. Make the cell taller. You can add more stuff if you want, but for immediate purposes, all I want is something like this:

 

 

Depending on how you set up the label's masks, when you run the app now you should get something like this:

 

 

Well that's no good. What happened here? I made the cell taller, why isn't it displaying that way? Ah, because nobody told the table that the row height should change. So we need to do that.

 

The wrong answer is to use this delegate method:

 

tableView:heightForRowAtIndexPath:

 

This method should ONLY be used if your table will feature more than 1 row height. If you have tall rows and short rows and everything in between, then this method is pretty much your only option. But if your rows are all the same height, then you will slam against this method over and over and over again (seriously, add some logs and watch how much it gets called) just to return the same number each time.

 

Fortunately, there is a better answer: UITableView has a rowHeight property. In fact, we've already utilized it, we just didn't realize it. Open up the BasicViewController.xib, select the table view, then hit Cmd-3. Right there at the top of the inspector: row height of 44.0. So we could simply change this number to match whatever our cell height is, and things will be good.

 

Or will they? Hard-coding numbers is generally something to avoid. And really, we could change the cell design again, and change the height again, and then we just forget to come back and change this setting. Wouldn't it be nice if we could establish a link between our cell height and our row height?

 

We can't quite get there directly, but we sure can take a measurement and use that to define the row height.

 

So first we need a cell. viewDidLoad is a good place to do this, and we are literally going to do the same thing we do in cellForRow to get a cell:

 

[[self customTableCellNib] instantiateWithOwner:self options:nil];

 

From what we learned before, we know that the cell property is now occupied. So we can grab that cell, take a measurement, and drive the table:

 

[[self customTableCellNib] instantiateWithOwner:self options:nil];
[[self mainTableView] setRowHeight:[[self customTableCell] frame].size.height];
[self setCustomTableCell:nil];

 

We get the frame of the cell, then get the height, and give that value to the rowHeight property. Then we clear out the cell property since we're done with it.

 

Try again:

 

 

Muuuuch better. Now you can change the cell's height as much as you want, and the table will always display the correct row height.

 

Thus concludes a couple of lengthy posts on this topic. But don't let that volume scare you away from using XIB-based cells. After you've run through the process a few times, it gets less intimidating. And once you're there, you get to take full advantage of Interface Builder's promise to make view layout easier.

 

TableViewTutorial_Part5.zip

UITableView How-To: Part 4 - XIB-Based Cells

Part 1 | Part 2 | Part 3 | Part 5 | Part 6

 

Up to this point in the series, the focus has been on basic table and data structures. Now let's take a look at customizing the appearance of the table view.

 

I'm not intending to spend much time talking about standard cells, but there actually are a number of ways to customize cells without needing to subclass. UITableViewCell's initWithStyle: method accepts a parameter for which Apple has provided several standard options. You can show text in several places, and you can add images and accessories. Take a quick glance at the Settings app on your phone; those are standard cells. So before you dive into subclassing cells, make sure you are aware of the built-in options. They can save you a lot of time. This post at Cocoa With Love is definitely worth reading.

 

But, let's assume that those standard configurations are inadequate for your awesome table design. Or perhaps you've seen another app that displays lots of crazy things in a table, and you wonder how it was done. Chances are that the answer will be the same either way: custom table cells. Like most visual things in Cocoa, there is a code-based approach and an Interface Builder-based approach. I'm going to focus on using IB, as the layout is significantly easier, although the setup has some nuances. This approach is based on the Apple sample project called TaggedLocations.

 

Overview

Let's take a quick look at the players involved, because the process to set this up is a tad convoluted:

ViewController.h
ViewController.m
ViewController.xib

TableCell.h
TableCell.m
TableCell.xib

 

In the same way that you would reference a button in your view by creating an IBOutlet, the same thing will be done here. So the view controller will have an IBOutlet for the cell:

@property (nonatomic, retain) IBOutlet TableCell *tableCell;

 

In order to do this without causing any build errors, the cell class needs to exist. But this outlet needs to exist in order to to complete the TableCell.xib, so there is something of a chicken-and-egg situation. The basic steps are:

 

1. Create the view controller class
2. Create the cell class
3. Create the IBOutlet in the view controller
4. Design the cell
5. Rewire the table delegate methods to use the cell

 

So there is a fair amount of back-and-forth between the classes, but after you get used to it, it's not so bad. Let's begin…

 

1. Create a view controller. I'm calling this one BasicViewController, but you can use whatever you want. Don't bother getting too hung up with delegate methods for now.

 

2. Add a new file. This will be a UITableViewCell subclass, and it's not immediately clear how to do this. Just choose Objective-C class, and then select UITableViewCell from the pull-down menu:

 

 

Call it CustomTableCell. This will create the .h and .m file, but we want a XIB file, too. So add a new file for that as well. Select User Interface at the side, and then choose a View XIB. iPhone-vs-iPad doesn't really matter, but I tend to go with iPhone.

 

 

Give it the same CustomTableCell name. You should now have .h, .m, and .xib files for CustomTableCell.

 

3. Now create an IBOutlet for the cell in the view controller. You will need @class in the .h file and #import in the .m class. The highlights of what you should wind up with are:

 

// BasicViewController.h
#import <UIKit/UIKit.h>
@class CustomTableCell;

@interface BasicViewController : UIViewController <UITableViewDelegate, UITableViewDataSource>
{
}

@property (nonatomic, retain) IBOutlet UITableView *mainTableView;
@property (nonatomic, retain) IBOutlet CustomTableCell *customTableCell;

 

// BasicViewController.m
#import "CustomTableCell.h"

@implementation BasicViewController

@synthesize mainTableView = ivMainTableView;
@synthesize customTableCell = ivCustomTableCell;

- (void)dealloc
{
   [self setMainTableView:nil];
   [self setCustomTableCell:nil];
   [super dealloc];
}

 

4. Configure the cell. Open up CustomTableCell.xib, as we have some preliminary things to take care of. You should see:

File's Owner
First Responder
View

Select View and delete it. Now go to your Library palette, find the Table View Cell, and drag it to the spot where View was.

 

 

Now we need to change classes. Select File's Owner, and go to the inspector panel for Identity (Cmd-4). Change the class to BasicViewController. Now select the table view cell, and in the inspector change the class to CustomTableCell.

 

 

Now we need to connect the IBOutlet we made earlier. Ctrl-click on File's Owner. Select the customTableCell outlet, and drag that to the CustomTableCell item.

 

 

Hey, wait a second... this isn't my view controller's XIB! You are correct. But the view controller will create this class - it will be the file's owner - so it does make some sense to do this. But don't get carried away. For example, you do see the view outlet, but don't mess with that here as that is being populated in your view controller's XIB. We are doing this for one reason and at this point one reason only: to get access to that cell IBOutlet.

 

There is a lot of customization we could potentially do here, but in the interest of quickly moving along to see this in action, simply drop a couple of a labels onto the cell. We'll come back later to wire everything up.

 

 

5. Configure the table delegate methods. Return to BasicViewController, and for now tell it there are 10 rows. The important change happens in cellForRow:

 

- (UITableViewCell *)tableView:(UITableView *)tableView
cellForRowAtIndexPath:(NSIndexPath *)indexPath
{
   static NSString *CellIdentifier = @"CellIdentifier";

   CustomTableCell *cell = (CustomTableCell *)[tableView dequeueReusableCellWithIdentifier:CellIdentifier];
   if (cell == nil)
   {
      [[NSBundle mainBundle] loadNibNamed:@"CustomTableCell" owner:self options:nil];
      cell = [self customTableCell];
      [self setCustomTableCell:nil];
   }
   return cell;
}

 

For the most part, this is pretty similar to what we've done before. Instead of a UITableViewCell, we're using a CustomTableCell, so we change the class types to reflect that. We're still asking for an available cell, and if one isn't available then we create one. The creation part is different than we've done before, naturally since we aren't just using code this time.

 

The first thing we do is load the XIB file. We indicate which class, and who should own it. The next thing we do is wave our hands and say there is some black magic happening here. Then we assign the cell property to our cell variable. Hrm, what? How did that get there? Well, let's back up and address that black magic.

 

The documentation has this to say about loadNibNamed:owner:options:

During the loading process, this method unarchives each object, initializes it, sets its properties to their configured values, and reestablishes any connections to other objects.

 

For our purposes, the important part is the last bit.

 

Think about what you do with a normal view controller. You place, say, an image view in IB, you create an IBOutlet for it, and then make the connection in IB. So after you instantiate your view controller, what happens? The XIB is loaded, which means an image view is also instantiated, and this image view is then assigned to your IBOutlet/property. When you go to talk to your image view using the property - [[self imageView] setImage:...]; - the image view is there already.

 

What we're doing here is exactly the same, only splitting things up into separate files. Instead of an image view, it's a table cell, and instead of being in the view controller's XIB, it is in a separate XIB. But the act of loading the XIB causes the outlets to be populated, so we end up with the same result. Black magic indeed.

 

So:
1. We load the XIB file
2. The IBOutlet gets populated with the cell
3. We assign that cell to our local cell variable
4. We clear out the property since we don't need to keep it around

 

Go ahead and run the app at this point, and if you've wired everything correctly, you should see:

 

Configure the cell

 

Let's circle back around and finish up the cell. First of all, we skipped a really important step. Recall what the initializer for a standard cell looks like:

 

cell = [[[UITableViewCell alloc] initWithStyle:UITableViewCellStyleDefault reuseIdentifier:CellIdentifier] autorelease];

 

We pass two parameters: a style, AND a reuse identifier. Now compare to how we just created the cell:

 

[[NSBundle mainBundle] loadNibNamed:@"CustomTableCell" owner:self options:nil];

 

Uh oh, no reuse identifier parameter. That's a problem if we want good table scrolling performance (and we do). I wish Apple would have handled this differently, but what they did is imbed the reuse identifier into the XIB file. So open it back up, and select the cell. Then go to the inspector panel again, Cmd-1.

 

 

It will be blank when you first look at it, so you will need to type it in. The important part here, and one unfortunate aspect of Apple's decision to do this, is that whatever you type in here, needs to match what you type in here:

 

static NSString *CellIdentifier = @"CustomCellIdentifier";

 

So you have to make sure the same thing is typed in 2 places, and if you screw up either one then you won't recycle cells. This will hurt scrolling performance. I really wish Apple had gone with more of an initWithNibName:bundle:reuseIdentifier: approach for these cells. Oh well.

 

Let's add some properties to the cell so that we can talk to the labels.

// CustomTableCell.h
@interface CustomTableCell : UITableViewCell
{
}

@property (nonatomic, retain) IBOutlet UILabel *redLabel;
@property (nonatomic, retain) IBOutlet UILabel *greenLabel;

 

// CustomTableCell.m

@implementation CustomTableCell

@synthesize redLabel = ivRedLabel;
@synthesize greenLabel = ivGreenLabel;

....

- (void)dealloc
{
   [self setRedLabel:nil];
   [self setGreenLabel:nil];
   [super dealloc];
}

 

Standard stuff here. Where it gets tricky is actually making the connections in IB. You are probably accustomed to dragging from File's Owner to establish IBOutlet connections. Ah, but remember which class we're dealing with here. File's Owner is the view controller, but we are adding these IBOutlets to the cell. So you can drag from File's Owner all that you want, but you won't be able to create the links. You have to drag from the cell class to the labels:

 

 

Now let's head back to the view controller and put some data in the labels. I'm not going to bother setting up any data; refer to Part 3 for some thoughts on how to arrange your data for this purpose. For now, just drop in something so that you can see different text in each field:

 

   ...

   NSUInteger row = [indexPath row];
   [[cell redLabel] setText:[NSString stringWithFormat:@"Red %d", row]];
   [[cell greenLabel] setText:[NSString stringWithFormat:@"Green %d", row]];
	
   return cell;
}

 

With standard cells, you are talking to [cell textLabel] or [cell detailTextLabel]. Same idea, just using the properties that you've created.

 

Your cell is a blank canvas ready to be customized to your heart's delight. Want 5 labels? Good. Want 10 images? Great. Go nuts.

 

This is turning into a longer post than I thought, and I still have a lot to talk about. So I'm going to split this up into 2 posts. Tune in later for the sequel.

 

TableViewTutorial_Part4.zip