If you've been following along with me, note that I'll be extending what you did in Chapter 6 of Book V. You can find the application up to that point on my Web site http://nealgoldstein.com under Book VI Start Here.

Okay, check out how easy it is to come up with the view controller and nib files:

Now do it all over again for the Sight model class (with the classes folder still selected).

I keep my Sight.m and .h classes in the Model Classes folder.

As I mentioned when you where creating the controller file, you're going to be creating the table view without using a nib file. Although the end-result of what you are doing here is pretty sophisticated, the actual nuts-and-bolts part is really quite easy. You get it all done by using an initialization method, as follows:

#import "SightListController.h"
#import "Trip.h"
#import "Sight.h"
#import "RoadTripAppDelegate.h"
#import "WebViewController.h"

@implementation SightListController

- (id) initWithTrip:(Trip*) theTrip {

  if (self = [super initWithStyle:UITableViewStyleGrouped]) {
    trip = theTrip;
    self.title = @"See the sights";
  }
  return self;
}

@end

#import <UIKit/UIKit.h>
@class Trip;
@class Sight;

@interface SightListController : UITableViewController {

  Trip         *trip;
}

- (id) initWithTrip:(Trip*) theTrip;
- (UIImage *) createThumbNail:(Sight*) aSight;

@end

To get your controllers in place, the first thing you have to do is make it possible to select the Sights entry in the Main view. That means uncommenting out the SightListController selection in the tableView:didSelectRowAtIndexPath: method over in RootViewController.m — the stuff in bold in Listing 1-3.

- (void)tableView:(UITableView *)tableView
        didSelectRowAtIndexPath:(NSIndexPath *)indexPath {

  RoadTripAppDelegate *appDelegate =
              (RoadTripAppDelegate *)
             [[UIApplication sharedApplication] delegate];
  [appDelegate.lastView replaceObjectAtIndex:0 withObject:
          [NSNumber numberWithInteger:indexPath.section]];
  [appDelegate.lastView replaceObjectAtIndex:1 withObject:
          [NSNumber numberWithInteger:indexPath.row]];

  [tableView deselectRowAtIndexPath:indexPath
                                            animated:YES];

  int menuOffset =
             [self menuOffsetForRowAtIndexPath:indexPath];
  UIViewController *targetController =
             [[menuList objectAtIndex:menuOffset]
                             objectForKey:kControllerKey];

  if (targetController == nil) {
    BOOL realtime = !appDelegate.useStoredData;

    switch (menuOffset) {
      case 0:
        if (realtime) targetController =
                [[MapController alloc] initWithTrip:trip];
        else [self displayOfflineAlert:
                [[menuList objectAtIndex:menuOffset]
                                objectForKey:kSelectKey]];
        break;
      case 1:
        targetController =
          [[SightListController alloc] initWithTrip:trip];
        break;
      case 2:
  //    targetController =
              [[HotelController alloc] initWithTrip:trip];
        break;

case 3:
          if  (realtime) targetController = [[WebViewController
     alloc] initWithTrip:trip tripSelector:@
     selector(returnWeather:)
             webControl:YES title:NSLocalizedString(@"Weather",
                                               @"Weather")];
          else [self displayOfflineAlert:
               [[menuList objectAtIndex:menuOffset]
                                  objectForKey:kSelectKey]];
          break;
        case 4:
          targetController = [[WebViewController alloc]
     initWithTrip:trip tripSelector:@selector(returnCarServicin
     gInformation:)
                              webControl:NO
     title:NSLocalizedString (@"Car Servicing", @"Car
     Servicing")];
          break;
        case 5:
          targetController = [[WebViewController alloc]
             initWithTrip:trip
             tripSelector:@selector(returnCarInformation:)
             webControl:NO
             title:NSLocalizedString (@"The Car", @"Car
                                             Information")];
          break;
     }
          if (targetController) {
        [[menuList  objectAtIndex:menuOffset]
     setObject:targetController forKey:kControllerKey];
      }
    }
    if (targetController) {
      [[self navigationController]
          pushViewController:targetController animated:YES];
      [targetController release];
    }
}

The following code allocates a SightListController (a view controller) and then sends it the initWithTrip:: message. (I explain this at the very end of Book V, Chapter 2; you might want to review that if it has been a while since you looked at it.).

targetController =
          [[SightListController alloc] initWithTrip:trip];

You also need to import the SightListController and add it to the RootViewController.m file.

#import "SightListController.h"

That's all you need to do in the RootViewController class.

If you were to build the project as it stands now, it would compile (with a few errors you can ignore), and you'd get a table view of Sights with nothing in your list. Now that you've gotten the foundation built, it's time to go to work.

Book II has an explanation of property lists, but it never hurts to go through it again in a new context.

Property lists are perfect for storing small amounts of data that consist primarily of strings and numbers. What adds to their appeal is the ability to easily read them into your program, use the data, and (although you won't be doing it in the RoadTrip application) modify the data and then write them back out again. That's because Cocoa provides a small set of objects that have that behavior built right in.

The technical term for these kinds of objects is serializable. A serializable object can convert itself into a stream of bytes so that it can be stored in a file and can then reconstitute itself into the object it once was when it is read back in — yes "beam me up, Scotty" does exist, at least on your computer.

These objects, called property list objects, that you have to work with are as follows:

As shown in the plist in Figure 1-3, the root is an array and the data for each one of the Sights is held in a dictionary. If you are a little hazy on arrays and dictionaries I will be explaining them in detail.

You'll notice a division in the preceding list. That is because there are two kinds of property list objects.

One thing that differentiates property list object containers (NSArray, NSDictionary), besides their ability to hold other objects, is that they both have methods called writeToFile::, which write the property list to a file, and a corresponding initWithContentsOfFile:, which initializes the object with the contents of a file. So, if I create an array or dictionary and fill it chock full of objects of the property list type, all I have to do to save it to a file is tell it to go save itself — or create an array or dictionary and then tell it to initialize itself from a file.

You have already worked with arrays in Book V when you saved the current state of the object, and I'll expand on them as well as dictionaries in later sections. These containers can contain other containers as well as the primitive types. Thus, you might have an array of dictionaries (and you do), and each dictionary might contain other arrays and dictionaries, as well as the primitive types.

NSData and NSMutableData are wrappers (an object that is there mostly to turn something into an object) in which you can dump any kind of data and then have that data act as an object. You've used NSData before when you downloaded the car servicing information in Book V as well as when you used the geocoder. You haven't seen NSDate yet, and I won't be using it in the book, but for your information, it is a Cocoa class for date and time handling.

Just as you added the CarSpecs.html file in Book V, Chapter 4, you do the same thing with the images you need for the Sights objects.

The content for the Sight objects are in the files (as you could tell from the plist) as GGBPhoto.jpg Alcatraz.jpg and CoitTower.jpg. (while png is the preferred format for iPhone icons, jpg or jpeg is used for photos.) To make the content available to the application, you need to include it in the application bundle itself, although you could have downloaded it the first time the application ran.

The files are included in the final code for this chapter, so first you have to download NNN from http://nealgoldstein.com.

Now, you can add the files to your bundle one of two ways:

- (void)applicationDidFinishLaunching:(UIApplication *)applica-
   tion {
...
 NSArray *paths = NSSearchPathForDirectoriesInDomains
                       (NSDocumentDirectory, NSUserDomainMask,
   YES);
  NSString *documentsDirectory = [paths objectAtIndex:0];
  NSString *filePath = [documentsDirectory
                             stringByAppendingPathComponent:kSt
   ate];
  lastView =[[NSMutableArray alloc]
                                   initWithContentsOfFile:fileP
   ath];
  if (lastView == nil) {
    lastView = [[NSMutableArray arrayWithObjects:
                   [NSNumber numberWithInteger:−1],
                   [NSNumber numberWithInteger:−1],
                   nil] retain];
  }
...
- (void)tableView:(UITableView *)tableView
                  didSelectRowAtIndexPath:(NSIndexPath *)index-
   Path {


  RoadTripAppDelegate *appDelegate = (RoadTripAppDelegate *)
                       [[UIApplication sharedApplication] del-
   egate];
  [appDelegate.lastView replaceObjectAtIndex:0 withObject:
                   [NSNumber numberWithInteger:indexPath.sec-
   tion]];
  [appDelegate.lastView replaceObjectAtIndex:1 withObject:
                       [NSNumber numberWithInteger:indexPath.
   row]];
...
}

- (void)applicationWillTerminate:(UIApplication *)application {

  NSArray *paths = NSSearchPathForDirectoriesInDomains
                       (NSDocumentDirectory, NSUserDomainMask,
   YES);
  NSString *documentsDirectory = [paths objectAtIndex:0];
  NSString *filePath = [documentsDirectory
                             stringByAppendingPathComponent:kSt
   ate];
  [lastView writeToFile:filePath atomically:YES];
}

Figure 1-15. Adding the .jpg files.

At this point, you have two of the necessary components for dealing with the sights in your application: You have the data for each Sight in the plist you just created, and you have a Sight object that has an instance variable defined to hold the data.

So how do you create each Sight and get the data into it? That's another job for Trip.

One of the features of the dynamic runtime dispatch mechanism employed by Objective-C is that you can add methods to existing classes without sub-classing. The Objective-C term for these new methods is categories. A category allows you to add methods to an existing class — even to one to which you do not have the source. This powerful feature allows you to extend the functionality of existing classes.

This looks a lot like class interface declaration — except the category name is listed within parentheses after the class name, and there is no superclass (or colon for that matter). Categories (unlike protocols, which I address in the next chapter) do have access to all the instance variables and methods of a class. And I do mean all, even ones declared @private, but you'll need to import the interface file for the class it extends. You can also add as many categories as you want.

You can add methods to a class by declaring them in an interface file under a category name and defining them in an implementation file under the same name. What you can't do is add more instance variables.

The methods the category adds become honestly and truly part of the class type; they aren't treated as "step methods." The methods you would add to Trip using a category become part of the Trip class and are inherited by all the class's subclasses, just like other methods. The category methods can do anything that methods defined in the class proper can do. At runtime, there's no difference.

You use a category like this to add more functionality to an existing class. For example, UITableView.h contains an extension to NSIndexPath to make it easier to represent a section and row, something you've taken advantage of every time you reference an indexPath.row, for example:

@interface NSIndexPath (UITableView)
+ (NSIndexPath *)indexPathForRow:(NSUInteger)row
   inSection:(NSUInteger)section;
@property(nonatomic,readonly) NSUInteger section;
@property(nonatomic,readonly) NSUInteger row;
@end

What you're doing here, however, is a bit more specialized. You're creating a class extension.

Class extensions are like anonymous (unnamed) categories, except that the methods they declare must be implemented in the main @implementation block for the corresponding class.

Doing it this way allows you to have a publicly declared set of methods and to then have additional methods declared privately for use solely by the class.

Class extensions allow you to declare additional methods for a class in a location other than the class @interface. This declaration is what you did when you added the following code above @implementation Trip:

@interface Trip ()
- (void) loadSights;
@end

Keep the following facts about this little snippet of code in mind:

If the developer doesn't have the source code or doesn't include the .m file, he or she will have no idea that the methods in an extension exist. Of course, this being Objective-C, the developer could always invoke the method if they knew about it.

But at least it makes the point — don't look behind the curtain.

To do some sight loading, add the code in bold in Listing 1-6 to the already existing initWithName: method in Trip.m. This addition invokes the method you declared in the previous section, which loads the list of sights from a property list and turns them into Sight objects — this code is starting to get exciting.

- (id) initWithName:(NSString*) theTrip {

    if ((self = [super init])) {
      tripName = theTrip;

[tripName retain];
    carInformation = [[CarInformation alloc]
                                          initWithTrip:self];
    car Servicing = [[CarServicing alloc] initWithTrip:self];
    weather = [[Weather alloc] init];
    [self loadSights];
  }
  return self;
}

Now you see how to actually use all that data you created in the plist.

Add the code in Listing 1-7 to Trip.m.

- (void) loadSights {

  NSString *sightsDataPath = [[NSBundle mainBundle]
   pathForResource:@"Sight" ofType:@"plist"];
  NSArray * sightsList = [[NSArray alloc]
                  initWithContentsOfFile:sightsDataPath];
  sights = [[NSMutableArray alloc]
                    initWithCapacity:[sightsList count]];

  for (NSMutableDictionary* sightData in sightsList) {
    Sight* newSight = [[Sight alloc] initWithTrip:self
                                    sightData:sightData];
    [sights addObject:newSight];
  }
}

This method starts by locating the Sights.plist you just created in your application bundle:

NSString *sightsDataPath = [[NSBundle mainBundle]
   pathForResource:@"Sights" ofType:@"plist"];

"What bundle?" you say? Well, when you build your iPhone application, Xcode packages it as a bundle — one containing the following:

Next it loads that file into the sightsList array:

NSArray * sightsList = [[NSArray alloc]initWithContentsOfFile
   :sightsDataPath];

initWithContentsOfFile:, as I mention earlier, is a method in the array and dictionary classes:

Next you allocate an array, sights (the array that you made a property earlier), to hold the Sight objects:

sights = [[NSMutableArray alloc]
                     initWithCapacity:[sightsList count]];

Then you take each entry in the sightsList array and use it to create a Sight object and load each into the sights array (the one you just created — this is why you made it mutable):

for (NSMutableDictionary* sightData in sightsList) {
  Sight* newSight = [[Sight alloc] initWithTrip self
                                    sightData:sightData];
  [sights addObject:newSight];
}

You allocate a new Sight and initialize it with the dictionary in the plist you created for each sight and that was reconstituted when you loaded the plist into the sightsList. After that, you add the new Sight object to the sights array. If you aren't familiar with the for method, I explain it — as well as more about arrays — in the next section.

Two kinds of arrays are available to you in Cocoa. The first is an NSMutableArray, which allows you to add objects to the area as needed — that is, the amount of memory allocated to the class is dynamically adjusted as you add more objects.

The second kind of array is an NSArray, which allows you to store a fixed number of objects, which are specified when you initialize the array. Because in this case you need the dynamic aspect of an NSMutableArray, I start my explanation there. As you remember, you used an array to save the last view in Book V, Chapter 3.

NSMutableArray arrays (I just call them arrays from now on when what I have to say applies to both NSArray and NSMutableArray) are ordered collections that can contain any sort of object. The collection doesn't have to be made up of the same objects. So you can have a number of Budget objects, for example, or Xyz objects mixed in — all that's fine, as long as they're all objects.

As I've said, arrays can hold only objects. But sometimes you may, for example, want to put a placeholder in a mutable array and later replace it with the "real" object. You can use an NSNull object for this placeholder role.

This is how you allocate and initialize the mutable array.

sights = [[NSMutableArray alloc]
                     initWithCapacity:[sightsList count]];

When you create a mutable array, you have to estimate the maximum size, which helps optimization. This is just a formality, and whatever you put here does not limit the eventual size. Here I use [sightsList count] — this is the number of dictionaries you created —, each of which will provide the data for a corresponding Sight object.

After I create a mutable array, I can start to add objects to it.

[sights addObject:newSight];

When you add an object to an Objective-C array, the object isn't copied, but rather receives a retain message before it's added to the array. When an array is deallocated, each element is sent a release message.

Technically (computer science-wise) what makes a collection an array is that you access its elements using an index, and that index can be determined at runtime. You get an individual element from an array by sending the array the objectAtIndex: message, which returns the array element you requested.

Depending on what you are doing with the array or how you're using it (arrays are very useful), objectAtIndex: will be one of the main array methods that you use.

Another method you'll use (and actually did use already) is count, which gives you the number of elements in the array — I showed you that when I explained about initializing the arrays, where it looked like this:

sights = [[NSMutableArray alloc]
                     initWithCapacity:[sightsList count]];

Objective-C 2.0 provides a language feature that allows you to enumerate over the contents of a collection. This is called fast enumeration, and it became available in Mac OS X 10.5 (Leopard) with version 2.0 of Objective-C. As I've mentioned, this book is based on Mac OS 10.6 — and OS 3.0 on the iPhone. (If you need to program for OS X 10.4, you need to use an NSEnumerator, which I don't cover in this book.) Enumeration uses the for in feature, which is a variation on a for loop.

What enumeration effectively does is sequentially march though an array, starting at the first element and returning each element for you to do "something with." The "something with" you will want to do in this case is use that element as an argument in the initWithTrip:: message.

For example, this code marches through the array and sends the initWithTrip:: message using each element in the array (an NSDictionary).

for (NSMutableDictionary* sightData in sightsList) {
  Sight* newSight = [[Sight alloc] initWithTrip: self
                                    sightData: sightData];
  [sights addObject:newSight];
}

Here's how this works:

The identifier sightData can be any name you choose. NSDictionary is the type of the object in the array (or it can be id, although I won't get into that here).

To be more formal, the construct you just used is called for in, and it looks like

for ( Type aVariable in expression ) { statements }

or

Type aVariable;
for ( aVariable in expression ) {statements }

where you fill in what is italicized. There is one catch, however: You aren't permitted to change any of the elements during the iteration, which means you can go through the array more than once without worry.

The following section takes a more detailed look at dictionaries.

Dictionaries are the citified versions of arrays. They both pretty much do the same things, but dictionaries add a new level of sophistication.

I love dictionaries, now. But I have to admit that when I started programming with Objective-C and Cocoa, trying to get my head around the idea of dictionaries was a real challenge — not because dictionaries are hard, because they really aren't. The problem was because of what you can do with them. Not only will you use them to hold property list objects, but you can also use them to hold application objects — just as you did with the array that holds Sight objects.

self.sightName = [sightData valueForKey: @"sight name"];

Now you can enter the code for the Sight. Add the code in bold in Listing 1-8 to Sight.m.

#import "RoadTripAppDelegate.h"
#import "Sight.h"
#import "Trip.h"

@implementation Sight
@synthesize coordinate;
@synthesize sightName, image, imageType;

- (id) initWithTrip: (Trip*) theTrip sightData:
   (NSDictionary*) sightData {

  if ((self = [super init])) {

    trip = theTrip;
    [trip retain];
    self.sightName =
                   [sightData valueForKey: @"sight name"];
    title = [sightData valueForKey: @"title"];
    [title retain];
    subtitle = [sightData valueForKey: @"subtitle"];
    [subtitle retain];
    resource = [sightData valueForKey: @"resource"];
    [resource retain];
    resourceType =
                [sightData valueForKey: @"resource type"];
    [resourceType retain];
    if ([sightData valueForKey: @"image"]) {
      self.image = [sightData valueForKey: @"image"];
      self.imageType =
                   [sightData valueForKey: @"image type"];
    }
    else {
      image = nil;
      imageType = nil;
    }

coordinate.latitude =
       [[sightData valueForKey: @"latitude"] doubleValue];
    coordinate.longitude =
      [[sightData valueForKey: @"longitude"] doubleValue];
  }
  return self;
}

@end

Although in general this is just another run-of-the-mill initialization method, I want to point out a few things.

First off, coordinate is a property here. You do this because in Chapter 3 of this minibook you'll be making Sight an annotation and, as I mention in Book V, Chapter 5, having a coordinate property is one of the requirements for an annotation. I'll have you implement the rest of what you need to do in Chapter 3 when I show you how to display Sights (and later Hotels) as annotations on the map.

You use the valueForKey: method I explain in the previous section to get the information from the dictionary and assign it to the Sight instance variable.

At this point, you only have a few more things left to do before you'll be able to see the results of your efforts so far — the SightListController with a list of sights and thumbnail pictures of each.

The implementation of the generic WebViewController was predicated on Trip being able to identify the content object that owned the content that needed to be displayed. In the case of the content in Book V, this worked well because for any given choice of content (car information, car servicing information, or the weather) there was indeed only one possible object that was associated with a user choice. For example, if the user chose Car Information, there was only one CarInformation object for Trip to get the NSURLRequest from. But in the case of Sight, that isn't true. How, then, does Trip know which Sight object to send a message to?

What I'd like to do is include that information as a selector argument —, but the performSelectorOnMainThread::: method does have its limitations — the selector you want performed can't return a value and can only take either a single argument of type id or no arguments at all. Unfortunately, you are already using your single argument allowance to send a reference to the WebViewController that is used to send that very same WebViewController the loadWebView: message.

Fortunately, as you'll see in the next chapter, there's a good solution: making the model objects WebViewController delegates.