Understanding Core Data

The Core Data framework is designed around the concept of relational data. However, it’s not a relational database but rather a layer of abstraction on top of a storage entity, usually SQLite. With Core Data you can focus on the structure of your data and leave the low-level relational database details for the framework to handle.

Put simply, Core Data, in conjunction with Xcode, allows a developer to perform three main tasks:

1. Create a data model
2. Persist information
3. Access data

First, it is important to understand exactly what a data model is. This term applies essentially to whatever structure any given application’s data is built around. This could be something as simple as an NSString or an NSArray in a simple application, all the way up to a complex, interconnected system of object types, each with their own properties, methods, and pointers to other objects.

Core Data is one of the most powerful frameworks in iOS. Despite this, its API is surprisingly small, consisting of only a handful of classes for you to handle. Here are some brief descriptions of the few main classes that make up Core Data:

• NSManagedObjectModel: This object is how iOS refers to your data model, but you will have little to do with this class yourself. When you create your project for the first recipe, you will see an instance of this type in your application delegate, and you will see it used in some pregenerated methods. Aside from that, you will have no reason to deal with this class programmatically.
• NSPersistentStoreCoordinator: This class, too, is one that you rarely will need to deal with. It works mostly in the background of an application to “coordinate” between your application and the underlying database or “persistent store,” but you will not need to send any actions to it. The most important part of this class that you need to know about is the type of persistent store that is being used. There are four types of persistent stores.
• NSSQLiteStoreType: A database store built on SQLite
• NSBinaryStoreType: A binary store type
• NSInMemoryStoreType: An in-memory store
• NSXMLStoreType: A store type using XML

The default value is NSSQLiteStoreType, specifying that you are using a persistent store built around the SQLite foundation. You will continue to use this type for the purpose of the Core Data recipes in this chapter.

• NSManagedObjectContext: This class, unlike the preceding two, is one you will be dealing with often. In the simplest terms, this class acts as a sort of workspace for your information. Any time you need to retrieve or store information, you will need a pointer to this class to perform the action. For this reason, a common practice in Core Data–based applications is to “pass around” a pointer to this class between each part of the application by giving each view controller an NSManagedObjectContext property.
• NSManagedObject: This class represents an instance of actual data in the data model.
• NSFetchedResultsController: This is the primary class for “fetching” results through the NSManagedObjectContext. It is not only very powerful but also very easy to use, especially in conjunction with UITableView. You will see plenty of examples of using this class in the recipes to come.

Now, let’s start building the word list app.

Setting Up Core Data

The easiest way to set up Core Data for your app is to let Xcode generate the necessary code when you create the project. Create a new project called “Recipe 15-3 Using Core Data” using the Empty Application template, as shown in Figure 15-5.

On the next screen, where you enter the project name, be sure to select the Use Core Data check box (see Figure 15-6).

After clicking Next, click Create on the next dialog box to finish the creation of your project as usual.

Now that you have set up your project to use Core Data, you have a lot of the work involved in using the Core Data framework already done for you, so you can move directly to building your data model.

Designing the Data Model

For this app, you build a simple data model consisting of only vocabularies and words. However, before you proceed to do anything in Xcode, you need to plan exactly how your model will work.

When working with a data model, the first kind of item you have to make is an entity. An entity is essentially the Core Data equivalent of a class, representing a specific object type that will be stored in the model.

In the same way that objects (or NSObjects in Objective-C) have properties, entities have attributes. These are the simpler pieces of data associated with any given entity, such as a name, age, or birthday, that do not require a pointer to any other entity.

Whenever you want one entity to have a pointer to another, you use a relationship. A relationship can be either to-one or to-many, referring to whether an entity has a pointer to one instance of another entity or multiple ones.

When dealing with the to-many relationship, you will notice that the entity has a pointer to a set of multiple other entities. Entities can easily have relationships that point to themselves, which might be the case of a Person entity having a relationship to another Person, in the form of a spouse. You can also set up inverse relationships, which act as paths back and forth between entities. For example, a Teacher entity might have a to-many relationship to a Student entity called “students,” and the Student’s relationship to the Teacher, called “teachers,” will be the inverse of this. Figure 15-7 shows a diagram of this two-way relationship.

So for your data model, you have two entities with their respective attributes and relationships, as defined in >Table 15-1.

Now that you have the data model planned out, you can build this in Xcode. Switch to view your data model file, which is named Recipe_15_3_Using_Core_Data.xcdatamodeld, in your project. Your view should now resemble Figure 15-8.

Now add the two entities of your data model. You can do this either by using the Editor menu or by using the Add Entity button located in the bottom-center area of the Xcode window. When you add an entity, you will need to click the entity, rename it “Vocabulary,” and then click Return. Repeat the process for the Word entity.

After you’ve added the two entities, the list of entities should resemble Figure 15-9.

Start by configuring the Vocabulary entity, so be sure the “Vocabulary” text is selected in the Entities section. By using the + button in the Attributes section, add an attribute called name with the type String selected in the Type drop-down menu, as shown in Figure 15-10.

Now you define the relationship of the Vocabulary entity. Under the Relationships area, add a relationship using the + button in that section. Name the relationship “words.” As the relationship’s destination, assign the Word entity. Until you create the relationship in the other entity, you cannot set up the inverse relationship, so leave it at No Inverse. The relationships set up for the Vocabulary entity should at this point be as in Figure 15-11.

Now you will define this relationship as a to-many relationship. Do that by selecting one of the relationships and check the To-Many relationship option in the Data Model Inspector (which corresponds to the attributes inspector for view elements), as shown in Figure 15-12.

While you most likely will not need to worry about most of the other values in this inspector (at least for the purposes of this recipe), one of the values of higher importance is the Delete Rule drop-down menu. This value specifies exactly how this relationship is handled when an instance of the given entity is deleted from the NSManagedObjectContext. It has four possible values:

• No Action: This is probably the most dangerous value, as it simply allows related objects to continue to attempt to access the deleted object.
• Nullify: The default value, this specifies that the relationship will be nullified upon deletion and will thus return a nil value.
• Cascade: This value can be slightly dangerous to use, as it specifies that if one object is deleted, all the objects it is related to via this Delete Rule setting will also be deleted, so as to avoid having nil values. If you’re not careful with this, you can delete unexpectedly large amounts of data, though it can also be very good for keeping your data clean. You might use this, for example, in the case of a “folder” with multiple objects. When a folder is deleted, you should delete all the contained objects as well.
• Deny: This prevents the object from being deleted as long as the relationship does not point to nil.

Change the Delete Rule to Cascade for this recipe so that if we delete a vocabulary, the words that pertain to it are deleted as well.

Now the time has come to configure the Word entity. In the same way you did for the Vocabulary entity, select the “Word” text in the Entities section; then move to the Attributes section and add two attributes this time, named word and translation. Use the type “String” for both of these attributes as well.

Also, add a relationship named vocabulary with the Destination set to Vocabulary. You can now also set the inverse relationship to words, as shown in Figure 15-13. This automatically sets up the inverse relationship for the words relationship as well (to vocabulary).

Because the vocabulary relationship is a to-one relationship (a Word can belong only to one Vocabulary), you should not select the to-many option as you did with the words relationship.

As the final step in the process of creating the data model, create Objective-C classes that map to the respective entity. Make sure the Vocabulary entity is selected, go to the Editor menu and choose Create NSManagedObject Subclass. Then select both the Vocabulary entity and the Word entity, click the Next button, and then click the Create button. This adds new classes to the project named Vocabulary and Word, respectively.

This is all you need to do to create your data model. To get a graphic overview of the data model, change Editor Style to Graph in the lower-right corner of the Data Model Editor. The Graph Editor Style uses a UML notation to display the entities, their attributes, and their relationships, where a single arrow represents a to-one relationship and a double arrow represents a to-many relationship. The blocks might initially appear all stacked on top of each other, but if you drag them apart, your display should resemble Figure 15-14.

Now that you have your data model set up, you can start to build the user interface to display its data.

Setting Up the Vocabularies Table View

Next, you will set up a navigation-based app with a main table view displaying a list of vocabularies.

To start implementing this, add a new class to the project. Name the class VocabulariesViewController and make it a subclass of UITableViewController. You do not need a .xib file, so leave that option unchecked.

Now make the changes to the VocabulariesViewController.h file, as shown in Listing 15-17.

Listing 15-17.  Implementing the alertView:clickedButtonAtIndex: Delegate Method

//
//  VocabulariesViewController.h
//  Recipe 15-3 Using Core Data
//

#import <UIKit/UIKit.h>
#import "Vocabulary.h"

@interface VocabulariesViewController : UITableViewController <UIAlertViewDelegate>

@property (strong, nonatomic)NSManagedObjectContext *managedObjectContext;
@property (strong, nonatomic)NSFetchedResultsController *fetchedResultsController;

- (id)initWithManagedObjectContext:(NSManagedObjectContext *)context;

@end

What’s worth mentioning about the code in Listing 15-16 is that the fetchedResultsController property keeps track of the fetched data and the managedObjectContext property allows you to make any necessary requests for data. You might also be wondering why you make the view controller conform to the UIAlertViewDelegate protocol. The reason is that you use an alert view as an input dialog for the vocabulary name later.

Now, switch to the VocabulariesViewController.m file to start implementing the view controller. Begin with the implementation for the custom initializer method. You’ll want to replace the existing initWithStyle method, as shown with the initializer in Listing 15-18.

Listing 15-18.  Implementing the initWithManagedObjectContext: Initializer Method

- (id)initWithManagedObjectContext:(NSManagedObjectContext *)context
{
    self = [super initWithStyle:UITableViewStylePlain];
    if (self)
    {
        self.managedObjectContext = context;
    }
    return self;
}

Next, add the helper method in Listing 15-19, which fetches all vocabularies in the data model and stores them in the fetchedResultsController property.

Listing 15-19.  Implementing the fetchVocabularies Method

-(void)fetchVocabularies
{
    NSFetchRequest *fetchRequest =
        [NSFetchRequest fetchRequestWithEntityName:@"Vocabulary"];
    NSString *cacheName = [@"Vocabulary" stringByAppendingString:@"Cache"];
     
    NSSortDescriptor *sortDescriptor =
        [NSSortDescriptor sortDescriptorWithKey:@"name" ascending:YES];
    [fetchRequest setSortDescriptors:@[sortDescriptor]];
     
    self.fetchedResultsController = [[NSFetchedResultsController alloc]
        initWithFetchRequest:fetchRequest managedObjectContext:self.managedObjectContext
        sectionNameKeyPath:nil cacheName:cacheName];
    NSError *error;
    if (![self.fetchedResultsController performFetch:&error])
    {
        NSLog(@"Fetch failed: %@", error);
    }
}

In detail, the method in Listing 15-19 does the following:

1. The first thing you need for fetching data is an instance of the NSFetchRequest class. Here, you have used a designated initializer to specify an NSEntityDescription, though you can also add it later using the -setEntity: method.
2. While not required, you have set up a “cache name” to be used with your fetch request, with a different cache for each entity. This allows you to slightly improve the speed of your application if you are making frequent fetch requests, as a local cache is first checked to see whether the request has already been performed.
3. Every instance of NSFetchRequest is required to have at least one NSSortDescriptor associated with it. Here, you have specified a simple alphabetic sort of the name property for each of your entities. After all your NSSortDescriptors have been created, they must be attached to the NSFetchRequest using the setSortDescriptors: method.
4. After the NSFetchRequest is fully configured, you can initialize the NSFetchedResultsController using the NSFetchRequest and the NSManagedObjectContext. The last two parameters are both optional, though you have specified a cacheName for optimization. You can set both of these to nil if you want to ignore them.
5. Finally, you must use the performFetch: method to complete the fetch request and retrieve the stored data. With this method, you can pass a pointer to an NSError, as shown previously, to keep track of and log any errors that occur with a fetch.

In the viewDidLoad method, you initialize the view controller by setting its title and loading the vocabularies, as shown in Listing 15-20.

Listing 15-20.  Modifying the viewDidLoad Method

- (void)viewDidLoad
{
    [super viewDidLoad];

    self.title = @"Vocabularies";
     
    [self fetchVocabularies];
}

To avoid presenting an empty list the first time the app is run, you’ll preload the data model with a “Spanish” vocabulary, but only if no vocabularies exist. To do this, add the code shown in bold in Listing 15-21 to the viewDidLoad method.

Listing 15-21.  Modifying the viewDidLoad Method to Preload with Vocabulary

- (void)viewDidLoad
{
    [super viewDidLoad];

    self.title = @"Vocabularies";
     
    [self fetchVocabularies];
    // Preload with a "Spanish" Vocabulary if empty
    if (self.fetchedResultsController.fetchedObjects.count == 0)
    {
        NSEntityDescription *vocabularyEntityDescription =
            [NSEntityDescription entityForName:@"Vocabulary"
                inManagedObjectContext:self.managedObjectContext];
        Vocabulary *spanishVocabulary = (Vocabulary *)[[NSManagedObject alloc]
            initWithEntity:vocabularyEntityDescription
            insertIntoManagedObjectContext:self.managedObjectContext];
        spanishVocabulary.name = @"Spanish";
        NSError *error;
        if (![self.managedObjectContext save:& error])
        {
            NSLog(@"Error saving context: %@", error);
        }
        [self fetchVocabularies];
    }
}

Next, you need to implement the required delegate and data source methods for the table view. First, implement the methods to specify the number of sections and rows shown in Listing 15-22.

Listing 15-22.  Implementing the numberOfSectionsInTableView: and tableView:numberOfRowsInSection: Delegate Methods

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

- (NSInteger)tableView:(UITableView *)tableView numberOfRowsInSection:(NSInteger)section
{
    return self.fetchedResultsController.fetchedObjects.count;
}

As shown in Listing 15-22, the NSFetchedResultsController class contains a method fetchedObjects, which returns an NSArray of the objects that were queried for.

Listing 15-23 shows the method to configure the cells of the table view.

Listing 15-23.  Implementing the tableView:cellForRowAtIndexPath: Delegate Method

- (UITableViewCell *)tableView:(UITableView *)tableView cellForRowAtIndexPath:(NSIndexPath *)indexPath
{
    static NSString *CellIdentifier = @"VocabularyCell";
     
    UITableViewCell *cell =
        [tableView dequeueReusableCellWithIdentifier:CellIdentifier];
    if (cell == nil)
    {
        cell = [[UITableViewCell alloc] initWithStyle:UITableViewCellStyleValue1
            reuseIdentifier:CellIdentifier];
        cell.accessoryType = UITableViewCellAccessoryDisclosureIndicator;
    }
     
    Vocabulary *vocabulary = (Vocabulary *)[self.fetchedResultsController
        objectAtIndexPath:indexPath];
    cell.textLabel.text = vocabulary.name;
    cell.detailTextLabel.text =
        [NSString stringWithFormat:@"(%d)", vocabulary.words.count];
  
    return cell;
}

The basic setup of the main view controller is now finished, and the time has come to make it work, so go to the AppDelegate.h file and add the declarations shown in Listing 15-24.

Listing 15-24.  Adding Declarations to the appDelegate

//
//  AppDelegate.h
//  My Vocabularies
//

#import <UIKit/UIKit.h>
#import "VocabulariesViewController.h"

@interface AppDelegate : UIResponder <UIApplicationDelegate>

@property (strong, nonatomic) UIWindow *window;

@property (readonly, strong, nonatomic) NSManagedObjectContext *managedObjectContext;
@property (readonly, strong, nonatomic) NSManagedObjectModel *managedObjectModel;
@property (readonly, strong, nonatomic) NSPersistentStoreCoordinator
    *persistentStoreCoordinator;
@property (strong, nonatomic) UINavigationController *navigationController;
@property (strong, nonatomic) VocabulariesViewController *vocabulariesViewController;

- (void)saveContext;
- (NSURL *)applicationDocumentsDirectory;

@end

As you can see from the code in Listing 15-24, the appDelegate is the place where Core Data has been set up for you. All you need to do is distribute the managed object context to the parts of your app that deal with the data.

In the application:didFinishLaunchingWithOptions: method in AppDelegate.m, add the code in Listing 15-25 to create and display the view controller in a navigation controller.

Listing 15-25.  Creating and Displaying Both the View and Navigation Controllers

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    self.window = [[UIWindow alloc] initWithFrame:[[UIScreen mainScreen] bounds]];
    self.window.backgroundColor = [UIColor whiteColor];

    self.vocabulariesViewController = [[VocabulariesViewController alloc]
        initWithManagedObjectContext:self.managedObjectContext];
    self.navigationController = [[UINavigationController alloc]
        initWithRootViewController:self.vocabulariesViewController];
    self.window.rootViewController = self.navigationController;

    [self.window makeKeyAndVisible];
    return YES;
}

Now is a good time to build and run the app to make sure everything is set up correctly. If things go right, you should see a screen resembling Figure 15-15.

To allow the user to add some data in the form of new vocabularies, put an “Add” button on the Navigation bar. Go back to the viewDidLoad method in VocabulariesViewController.m and add the code shown in Listing 15-26.

Listing 15-26.  Adding an “Add” Button to the Navigation Bar

- (void)viewDidLoad
{
    [super viewDidLoad];

    self.title = @"Vocabularies";
     
    UIBarButtonItem *addButton =
        [[UIBarButtonItem alloc] initWithBarButtonSystemItem:UIBarButtonSystemItemAdd
            target:self action:@selector(add)];
    self.navigationItem.rightBarButtonItem = addButton;

    [self fetchVocabularies];

    // ...
}

Now implement the add action method, as shown in Listing 15-27. It brings up an alert view for the user to input a name of a new vocabulary.

Listing 15-27.  Implementing the Add Action Method

- (void)add
{
    UIAlertView * inputAlert = [[UIAlertView alloc] initWithTitle:@"New Vocabulary"
        message:@"Enter a name for the new vocabulary" delegate:self
        cancelButtonTitle:@"Cancel" otherButtonTitles:@"OK", nil];
    inputAlert.alertViewStyle = UIAlertViewStylePlainTextInput;
    [inputAlert show];
}

Finally, implement the alertView:clickedButtonAtIndex: delegate method to create the new vocabulary if the user taps the OK button. Listing 15-28 shows this implementation.

Listing 15-28.  Implementing the alertView:clickedButtonAtIndex: Delegate Method

- (void)alertView:(UIAlertView *)alertView clickedButtonAtIndex:(NSInteger)buttonIndex
{
    if (buttonIndex == 1)
    {
        NSEntityDescription *vocabularyEntityDescription =
            [NSEntityDescription entityForName:@"Vocabulary"
                inManagedObjectContext:self.managedObjectContext];
        Vocabulary *newVocabulary = (Vocabulary *)[[NSManagedObject alloc]
            initWithEntity:vocabularyEntityDescription
            insertIntoManagedObjectContext:self.managedObjectContext];
        newVocabulary.name = [alertView textFieldAtIndex:0].text;
        NSError *error;
        if (![self.managedObjectContext save:&error])
        {
            NSLog(@"Error saving context: %@", error);
        }
        [self fetchVocabularies];
        [self.tableView reloadData];
    }
}

If you build and run the app again, you now can add new vocabularies, as shown in Figure 15-16.

As a final feature of the Vocabularies view controller, implement the ability to delete items. Do that by implementing the tableView:commitEditingStyle:forRowAtIndexPath: delegate method, as shown in Listing 15-29.

Listing 15-29.  Implementing the tableView:commitEditingStyle:forRowAtIndexPath: Delegate Method

-(void)tableView:(UITableView *)tableView commitEditingStyle:(UITableViewCellEditingStyle)
editingStyle forRowAtIndexPath:(NSIndexPath *)indexPath
{
    if (editingStyle == UITableViewCellEditingStyleDelete)
    {
        NSManagedObject *deleted =
            [self.fetchedResultsController objectAtIndexPath:indexPath];
        [self.managedObjectContext deleteObject:deleted];
        NSError *error;
        BOOL success = [self.managedObjectContext save:&error];
        if (!success)
        {
            NSLog(@"Error saving context: %@", error);
        }
        [self fetchVocabularies];
        [self.tableView deleteRowsAtIndexPaths:@[indexPath]
            withRowAnimation:UITableViewRowAnimationRight];
    }
}

To test this feature, run the app again and swipe an item in the list. A red button should appear that allows you to delete the item in question. Figure 15-17 shows an example of this.

With the Vocabularies view all set up, it’s time to create the view that handles the words.

Implementing the Words View Controller

When the user selects a cell in the Vocabularies table view, another table view is presented displaying the words of that vocabulary.

Create a new UITableViewController subclass named WordsViewController, again without selecting the With XIB option.

You will initialize the Words view controller with a vocabulary, so you need a property and a custom initializer for that. You also need to import the Vocabulary and Word classes. Go to WordsViewController.h and add the declarations shown in Listing 15-30.

Listing 15-30.  Updating the WordsViewController.h file for Words Implementation

//
//  WordsViewController.h
//  Recipe 15-3 Using Core Data
//

#import <UIKit/UIKit.h>
#import "Vocabulary.h"
#import "Word.h"

@interface WordsViewController : UITableViewController

@property (strong, nonatomic)Vocabulary *vocabulary;

- (id)initWithVocabulary:(Vocabulary *)vocabulary;

@end

Now switch to the WordsViewController.m file. The initializer method simply assigns the vocabulary property and is pretty straightforward. Listing 15-31 show the implementation.

Listing 15-31.  Implementing the initWithVocabulary: Initializer Method

- (id)initWithVocabulary:(Vocabulary *)vocabulary
{
    self = [super initWithStyle:UITableViewStylePlain];
    if (self)
    {
        self.vocabulary = vocabulary;
    }
    return self;
}

The viewDidLoad method is more simple (at this point), setting only the view controller’s title, as shown in Listing 15-32.

Listing 15-32.  Setting the Title in the viewDidLoad Method

- (void)viewDidLoad
{
    [super viewDidLoad];

    self.title = self.vocabulary.name;
}

Listing 15-33 shows the required data source delegate methods.

Listing 15-33.  Implementing Required Delegate Methods for the Number of Rows and Sections in the Table View

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

- (NSInteger)tableView:(UITableView *)tableView numberOfRowsInSection:(NSInteger)section
{
    return self.vocabulary.words.count;
}

Notice in Listing 15-33 how you use the corresponding property of the Vocabulary entity’s words relationship to get the number of words. This is where the power of Core Data starts to show; you can handle the data as normal objects and ignore the fact that it’s actually stored in a database.

Next, you’ll design the table view cells to display both the word and its translation (as a subtitle). Do that by adding the implementation of the tableView:cellForRowAtIndexPath: delegate method shown in Listing 15-34.

Listing 15-34.  Implementing the tableView:cellForRowAtIndexPath: Delegate Method

- (UITableViewCell *)tableView:(UITableView *)tableView cellForRowAtIndexPath:(NSIndexPath *)indexPath
{
    static NSString *CellIdentifier = @"WordCell";
     
    UITableViewCell *cell =
        [tableView dequeueReusableCellWithIdentifier:CellIdentifier];
    if (cell == nil)
    {
        cell = [[UITableViewCell alloc] initWithStyle:UITableViewCellStyleSubtitle
            reuseIdentifier:CellIdentifier];
        cell.accessoryType = UITableViewCellAccessoryDisclosureIndicator;
    }
     
    Word *word = [self.vocabulary.words.allObjects objectAtIndex:indexPath.row];
    cell.textLabel.text = word.word;
    cell.detailTextLabel.text = word.translation;
     
    return cell;
}

To connect the two view controllers with each other, go back to VocabulariesViewController.h and import the Words view controller header file, as shown in Listing 15-35.

Listing 15-35.  Adding an Import Statement to the VocabulariesViewController.h File

//
//  VocabulariesViewController.h
//  Recipe 15-3 Using Core Data
//

#import <UIKit/UIKit.h>
#import "Vocabulary.h"
#import "WordsViewController.h"

@interface VocabulariesViewController : UITableViewController<UIAlertViewDelegate>

@property (strong, nonatomic)NSManagedObjectContext *managedObjectContext;
@property (strong, nonatomic) NSFetchedResultsController *fetchedResultsController;

- (id)initWithManagedObjectContext:(NSManagedObjectContext *)context;

@end

Finally, in the VocabulariesViewController.m file, add the delegate method shown in Listing 15-36.

Listing 15-36.  Implementing the tableView:didSelectRowAtIndexPath: Delegate Method

- (void)tableView:(UITableView *)tableView didSelectRowAtIndexPath:(NSIndexPath *)indexPath
{
    Vocabulary *vocabulary = (Vocabulary *)[self.fetchedResultsController
        objectAtIndexPath:indexPath];

    WordsViewController *detailViewController =
        [[WordsViewController alloc] initWithVocabulary:vocabulary];
    [self.navigationController pushViewController:detailViewController animated:YES];
}

Now is a good time to build and run to be sure everything is working properly. You can select a vocabulary and see its word list view, although empty at this point, as in Figure 15-18.

The next step is to implement a way for the user to add words to the vocabulary, again in the form of an “Add” button on the navigation bar. But before you add that button, create the view controller that handles the editing of the new Word object.

Adding a Word Edit View

Create a new subclass of UIViewController (not UITableViewController as before) with the name EditWordViewController. You’ll build a user interface for it, so make sure the “With XIB for user interface” option is selected this time.

Open the EditWordViewController.xib file and build a user interface like the one in Figure 15-19. Because we’ll be using a navigation controller, add the opaque navigation bar to the view by selecting it from the top bar drop-down in the attributes inspector with the full view selected.

As usual, create outlets for the text fields. Name them wordTextField and translationTextField, respectively.

With the user interface in place, you can move on to defining the programming interface of this view controller. You use Objective-C blocks to simplify the code on the calling side, which uses the class method shown in Listing 15-37 to present the edit view controller.

Listing 15-37.  Declaring the editWord: Class Method in the EditWordViewController.h File

+ (void)editWord:(Word *)word
    inNavigationController:(UINavigationController *)navigationController
    completion:(EditWordViewControllerCompletionHandler)completionHandler;

The EditWordViewControllerCompletionHandler is a block type with two arguments, sender and canceled, as shown in Listing 15-38.

Listing 15-38.  Creating the Block Type Declaration

typedef void (^EditWordViewControllerCompletionHandler)
    (EditWordViewController *sender, BOOL canceled);

To implement this API, you need a couple of instance variables and a custom initializer method. In all, add the bold code in Listing 15-39 to the EditWordViewController.h file.

Listing 15-39.  The Complete EditWordViewController.h File

//
//  EditWordViewController.h
//  Recipe 15-3 Using Core Data
//

#import <UIKit/UIKit.h>
#import "Word.h"

@class EditWordViewController;

typedef void (^EditWordViewControllerCompletionHandler)(EditWordViewController *sender, BOOL canceled);

@interface EditWordViewController : UIViewController
{
@private
    EditWordViewControllerCompletionHandler _completionHandler;
    Word *_word;
}

@property (weak, nonatomic) IBOutlet UITextField *wordTextField;
@property (weak, nonatomic) IBOutlet UITextField *translationTextField;

- (id)initWithWord:(Word *)word
    completion:(EditWordViewControllerCompletionHandler)completionHandler;

+ (void)editWord:(Word *)word
    inNavigationController:(UINavigationController *)navigationController
    completion:(EditWordViewControllerCompletionHandler)completionHandler;

@end

Now go to EditWordViewController.m and add the implementation in Listing 15-40 of the class method. It simply instantiates the edit view controller and adds it to the navigation controller stack.

Listing 15-40.  Implementing the editWord: Class Method

+ (void)editWord:(Word *)word
    inNavigationController:(UINavigationController *)navigationController
    completion:(EditWordViewControllerCompletionHandler)completionHandler
{
    EditWordViewController *editViewController =
        [[EditWordViewController alloc] initWithWord:word completion:completionHandler];
    [navigationController pushViewController:editViewController animated:YES];
}

The initializer method stores away the word and the completion handler in the respective instance variable. Listing 15-41 shows this implementation.

Listing 15-41.  Implementation of the initWithWord: Initializer Method

- (id)initWithWord:(Word *)word completion:(EditWordViewControllerCompletionHandler)
completionHandler
{
    self = [super initWithNibName:nil bundle:nil];
    if (self)
    {
        _completionHandler = completionHandler;
        _word = word;
    }
    return self;
}

When the edit view controller loads, it updates the two text fields with data from the provided Word object. It also adds two buttons, “Done” and “Cancel,” to the navigation bar. To achieve that, add the code in Listing 15-42 to the viewDidLoad method.

Listing 15-42.  Modifying the viewDidLoad Method to Set Text Fields and Add Buttons

- (void)viewDidLoad
{
    [super viewDidLoad];

     self.title = @"Edit Word";

    self.wordTextField.text = _word.word;
    self.translationTextField.text = _word.translation;
     
    self.navigationItem.rightBarButtonItem =
        [[UIBarButtonItem alloc] initWithBarButtonSystemItem:UIBarButtonSystemItemDone
            target:self action:@selector(done)];
    self.navigationItem.leftBarButtonItem =
        [[UIBarButtonItem alloc] initWithBarButtonSystemItem:UIBarButtonSystemItemCancel
            target:self action:@selector(cancel)];
}

As you can see from the code, two action methods have been hooked up to the buttons. Now you will need to implement them.

The first, done, updates the Word object with the data from the two text fields and then notifies the caller by invoking the completion handler block, sending “NO” for the cancel argument, as shown in Listing 15-43.

Listing 15-43.  Implementing the Done Action Method

- (void)done
{
    _word.word = self.wordTextField.text;
    _word.translation = self.translationTextField.text;
    _completionHandler(self, NO);
}

The cancel action method is even simpler. It will notify the caller only if the user has canceled the edit, as shown in Listing 15-44.

Listing 15-44.  Implementing the Cancel Action Method

- (void)cancel
{
    _completionHandler(self, YES);
}

You’re now done with the edit view controller, so implement the code to display it. First, import the edit view controller in the WordsViewController.h file, as shown in Listing 15-45.

Listing 15-45.  Importing the EditWordViewController.h File into the WordsViewController.h File

//
//  WordsViewController.h
//  Recipe 15-3 Using Core Data
//

#import <UIKit/UIKit.h>
#import "Vocabulary.h"
#import "Word.h"
#import "EditWordViewController.h"

@interface WordsViewController : UITableViewController

@property (strong, nonatomic)Vocabulary *vocabulary;

- (id)initWithVocabulary:(Vocabulary *)vocabulary;

@end

Next, add an “Add” button to the navigation bar of the words view controller class. Switch to the WordsViewController.m file and modify the viewDidLoad method, as shown in bold in Listing 15-46.

Listing 15-46.  Creating an “Add” Button the WordsViewController Navigation Bar

- (void)viewDidLoad
{
    [super viewDidLoad];
     
    UIBarButtonItem *addButton =
        [[UIBarButtonItem alloc] initWithBarButtonSystemItem:UIBarButtonSystemItemAdd
            target:self action:@selector(add)];
    self.navigationItem.rightBarButtonItem = addButton;

    self.title = self.vocabulary.name;
}

Next, start implementing the action method of this button, as shown in Listing 15-47. It creates a new Word object, which it provides as an argument to the edit view controller.

Listing 15-47.  The Starting Implementation of the Add Action Method

- (void)add
{
    NSEntityDescription *wordEntityDescription =
        [NSEntityDescription entityForName:@"Word"
            inManagedObjectContext:self.vocabulary.managedObjectContext];
    Word *newWord = (Word *)[[NSManagedObject alloc]
        initWithEntity:wordEntityDescription
        insertIntoManagedObjectContext:self.vocabulary.managedObjectContext];

    [EditWordViewController editWord:newWord
     inNavigationController:self.navigationController completion:
     ^(EditWordViewController *sender, BOOL canceled)
     {
         // TODO: Handle edit finished
     }];
}

When the edit view controller finishes, you either delete the new Word object if the user canceled or add it to the vocabulary and save it to the database. Either way, the edit view controller should be popped from the navigation controller. The complete implementation of the add action method should look like Listing 15-48.

Listing 15-48.  The Complete Add Action Method Implementation

- (void)add
{
    NSEntityDescription *wordEntityDescription =
        [NSEntityDescription entityForName:@"Word"
            inManagedObjectContext:self.vocabulary.managedObjectContext];
    Word *newWord = (Word *)[[NSManagedObject alloc]
        initWithEntity:wordEntityDescription
        insertIntoManagedObjectContext:self.vocabulary.managedObjectContext];
    [EditWordViewController editWord:newWord
     inNavigationController:self.navigationController completion:
     ^(EditWordViewController *sender, BOOL canceled)
     {
         if (canceled)
         {
             [self.vocabulary.managedObjectContext deleteObject:newWord];
         }
         else
         {
             [self.vocabulary addWordsObject:newWord];
              
             NSError *error;
             if (![self.vocabulary.managedObjectContext save:& error])
             {
                 NSLog(@"Error saving context: %@", error);
             }
             [self.tableView reloadData];
         }
          
         [self.navigationController popViewControllerAnimated:YES];
     }];
}

If you build and run now, you can add words to your vocabularies using the “Add” button in the respective Words view. Figure 15-20 shows an example of this.

The user should of course be able to edit an existing word. You’ll implement it so that when a user selects a cell, the edit view for that word is displayed. To do that, add the implementation shown in Listing 15-49 of the WordsViewController.m file to the tableView:didSelectRowAtIndexPath: delegate method.

Listing 15-49.  Implementing the tableView:didSelectRowAtIndexPath: Method

- (void)tableView:(UITableView *)tableView didSelectRowAtIndexPath:(NSIndexPath *)indexPath
{
    Word *word = [self.vocabulary.words.allObjects objectAtIndex:indexPath.row];
    [EditWordViewController editWord:word
     inNavigationController:self.navigationController completion:
     ^(EditWordViewController *sender, BOOL canceled)
     {
         NSError *error;
         if (![self.vocabulary.managedObjectContext save:& error])
         {
             NSLog(@"Error saving context: %@", error);
         }
          
         [self.tableView reloadData];
         [self.navigationController popViewControllerAnimated:YES];
     }];
}

To allow the user to delete Words, add the tableView:commitEditingStyle:forRowAtIndexPath: delegate method, as shown in Listing 15-50.

Listing 15-50.  Implementing the tableView:commitEditingstyle:forRowAtIndexPath: Delegate Method

-(void)tableView:(UITableView *)tableView
    commitEditingStyle:(UITableViewCellEditingStyle)editingStyle
    forRowAtIndexPath:(NSIndexPath *)indexPath
{
    if (editingStyle == UITableViewCellEditingStyleDelete)
    {
        Word *deleted = [self.vocabulary.words.allObjects objectAtIndex:indexPath.row];
        [self.vocabulary.managedObjectContext deleteObject:deleted];
        NSError *error;
        BOOL success = [self.vocabulary.managedObjectContext save:&error];
        if (!success)
        {
            NSLog(@"Error saving context: %@", error);
        }
        [self.tableView deleteRowsAtIndexPaths:@[indexPath]
            withRowAnimation:UITableViewRowAnimationRight];
    }
}

If you build and run now, you can delete words by sweeping your finger (or mouse pointer if you run in the iOS simulator), as shown in Figure 15-21.

You’re almost finished with this simple word list app, but there is one small issue that we’d like you to fix before we close this recipe. You’ve probably noticed that if you add words to a vocabulary and return to the main view, the item count for the vocabulary doesn’t update. The easiest way to fix this is to reload the data whenever the view appears. To do that, add the method to the VocabulariesViewController.m file shown in Listing 15-51.

Listing 15-51.  Implementing the viewWillAppear Override to Reload the Table

- (void)viewWillAppear:(BOOL)animated
{
    [self fetchVocabularies];
    [self.tableView reloadData];
}

Now if you try again, you’ll see that the number within the parentheses updates to reflect the new number of items in the vocabulary (see Figure 15-22).

In this recipe, we have covered the basics of Core Data, one of the most integral parts of iOS development. You have seen a glimpse of its power and simplicity of use when it comes to data modeling, persistence, and access. However, we have by no means detailed every facet in the Core Data framework or even touched on many of the general subjects related to it. You can easily find entire books devoted to the subject of Core Data, and you probably should consult those sources to get a more complete view of exactly how much ability you have in controlling how your data is stored. The overview here has demonstrated a basic use of the framework and explained the key concepts needed to get started working with Core Data so that you can implement simple persistence in your applications without worrying about the more esoteric complexities. If you want to know more about this great framework, we recommend you start with Apple’s documentation on this topic.

Persisting Data on iCloud

iCloud is Apple’s data storage service for iOS and Mac devices. If iCloud is set up, iOS uses the service for tasks such as backups and synchronizing images between the user’s different devices. iCloud comes with an extensive API so that your apps, too, can take advantage of its features, including persisting data and sharing state and files between all the user’s devices. The other benefit is you can easily share information such as calendars between iOS and Mac devices. With the new Xcode 5 capabilities feature, which allows you to easily add capabilities such as iCloud and Game Center, it is now much less of a headache to set up iCloud services than with previous versions of Xcode.

Basically, iCloud comes with three kinds of storage:

• Key-value storage, which can be used to store preferences, settings, and other small-sized data
• Document storage, for file-based information such as images, text documents, files containing information about your app’s state, and so on
• Core Data storage, which actually uses document storage to persist and synchronize your app’s Core Data

In Recipe 15-4, we show you how you can implement key-value storage in your apps. Recipe 15-5 shows how you can create and store custom documents in iCloud. If you’re interested in Core Data storage on iCloud, we recommend Apple’s documentation.

Setting Up iCloud for an App

To set up iCloud, you must configure entitlements, which are special keys that allow you to use iCloud storage. Entitlements will be necessary to allow for iCloud and its key-value store. Navigate to the project’s target settings and scroll and select the Capabilities tab. Select the switch to turn on iCloud and check Use Key-Value Store, as shown in Figure 15-25. Xcode then automatically generates an entitlements file with the correct settings.

That is all that is needed to set up iCloud in iOS 7. Before iOS 7 and Xcode 5, setting up iCloud involved logging into the member center of the developer site and carrying out a few different steps. This was an annoying process to say the least. Now Xcode does everything for you behind the scenes.

Persisting Data in an iCloud Key-Value Store

You’ll now move on to implement the storing of the text size preference in the iCloud key-value store. First, you’ll need a property to store a reference to the key-value store. Go to ViewController.h and add the declaration shown in Listing 15-53.

Listing 15-53.  Adding an NSUbiquitousKeyValueStore to the ViewController.h File

//
//  ViewController.h
//  Recipe 15-4 Storing Key-Value Data in iCloud
//

#import <UIKit/UIKit.h>

@interface ViewController : UIViewController

@property (weak, nonatomic) IBOutlet UISegmentedControl *fontSizeSegmentedControl;
@property (weak, nonatomic) IBOutlet UITextView *documentTextView;
@property (strong, nonatomic) NSUbiquitousKeyValueStore *iCloudKeyValueStore;

- (IBAction)updateTextSize:(id)sender;

@end

Now switch to ViewController.m and add the code in Listing 15-54 to the viewDidLoad method.

Listing 15-54.  Setting Up iCloud in the viewDidLoad Method

- (void)viewDidLoad
{
    [super viewDidLoad];
    self.iCloudKeyValueStore = [NSUbiquitousKeyValueStore defaultStore];
     
    [[NSNotificationCenter defaultCenter] addObserver:self
        selector:@selector(handleStoreChange:)
        name:NSUbiquitousKeyValueStoreDidChangeExternallyNotification
        object:self.iCloudKeyValueStore];
     
    [self.iCloudKeyValueStore synchronize];
    [self updateUserInterfaceWithPreferences];
}

The code in Listing 15-54 does the following:

1. Gets a reference to the key-value store
2. Signs up for notifications when the data in the key-value store is changed by an external source (NSUbiquitousKeyValueStoreDidChangeExternallyNotification)
3. Makes sure the key-value store cache is up-to-date by calling synchronize
4. Updates the user interface with the values from the key-value store

Next, implement the notification handler for when the iCloud data is changed by an external source, such as another device. For the sake of this recipe, you’ll simply update the user interface with the new values shown in Listing 15-55.

Listing 15-55.  Implementing the handleStoreChange: Method

- (void)handleStoreChange:(NSNotification *)notification
{
    [self updateUserInterfaceWithPreferences];
}

The updateUserInterfaceWithPreference helper method extracts the text size value from the key-value store and sets the selected index of the segmented control. This implementation is shown in Listing 15-56.

Listing 15-56.  Implementing the updateUserInterfaceWithPreferences Method

- (void)updateUserInterfaceWithPreferences
{
    NSInteger selectedSize = [self.iCloudKeyValueStore doubleForKey:@"TextSize"];
    self.fontSizeSegmentedControl.selectedSegmentIndex = selectedSize;
    [self updateTextSize:self];
}

Finally, when the user changes the text size using the segmented control, you should write the new value to the key-value store for persistency in iCloud. Add the code to the updateTextSize: action method, as shown in Listing 15-57.

Listing 15-57.  Updating the updateTextSize: Method to Write to the Key-Value Store

- (IBAction)updateTextSize:(id)sender
{
    CGFloat newFontSize;
    switch (self.fontSizeSegmentedControl.selectedSegmentIndex)
    {
        case 1:
            newFontSize = 19;
            break;
        case 2:
            newFontSize = 24;
            break;
             
        default:
            newFontSize = 14;
            break;
    }
    self.documentTextView.font = [UIFont systemFontOfSize:newFontSize];
     
    // Update Preferences
    NSInteger selectedSize = self.fontSizeSegmentedControl.selectedSegmentIndex;
    [self.iCloudKeyValueStore setDouble:selectedSize forKey:@"TextSize"];
}

That’s all you need to do to store the preference value in iCloud. But before you can test your application, you must make sure your test device is properly configured to work with iCloud. In the Settings app on your device, navigate to the iCloud section. For this application to store data, your iCloud account must be properly configured and verified. This requires you to have verified your e-mail address and registered it as your Apple ID. The Documents & Data item should also be set to ON, as in Figure 15-26. You can, of course, easily configure this once your account is verified.

With iCloud set up on your device, you can build and run the app to test its new persistency feature. You should now be able to do the following:

• Set the text size preference to Medium or Large, terminate the app, and restart it; it should now automatically set the preference to the value you chose.
• Set the text size preference to Medium or Large, uninstall the app from the device, and then reinstall it; in a second or two, it should automatically set the preference to the value it had before uninstalling.
• Run the app on two different devices, change the preference on one device, and see it automatically reflected in the other (it might take some time before the change takes place).

This is all well and good; however, there is a problem with this implementation. It will not work if iCloud is turned off or unavailable. You can easily test this by running the app in the iOS simulator (which doesn’t have support for iCloud). You’ll see that the persistency doesn’t work and the app is reset to the Small text size on every launch.

For these reasons, it’s recommended that, in addition to the iCloud key-value store, you save the values in a local NSUserDefaults cache as well. This makes your app more robust and resilient to problems stemming from iCloud access problems. Fortunately, this is an easy fix, as the next section shows.

Caching iCloud Data Locally Using NSUserDefaults

Start by adding an NSUserDefaults property in the ViewController.h file, as shown in Listing 15-58.

Listing 15-58.  Adding an NSUserDefaults Property to the ViewController.h File

//
//  ViewController.h
//  Recipe 15-4 Storing Key-Value Data in iCloud
//

#import <UIKit/UIKit.h>

@interface ViewController : UIViewController

@property (weak, nonatomic) IBOutlet UISegmentedControl *fontSizeSegmentedControl;
@property (weak, nonatomic) IBOutlet UITextView *documentTextView;
@property (strong, nonatomic) NSUbiquitousKeyValueStore *iCloudKeyValueStore;
@property (strong, nonatomic) NSUserDefaults *userDefaults;

- (IBAction)updateTextSize:(id)sender;

@end

There are only a few changes needed for setting up the local cache. First, in viewDidLoad you’ll initialize the property, as shown in Listing 15-59.

Listing 15-59.  Initializing the userDefaults Property from the viewDidLoad Method

- (void)viewDidLoad
{
    [super viewDidLoad];
    self.iCloudKeyValueStore = [NSUbiquitousKeyValueStore defaultStore];
    self.userDefaults = [NSUserDefaults standardUserDefaults];
     
    // ...
}

Next, when the preference value is written to iCloud, you’ll write the same value to the NSUserDefaults. To do this, add the bold lines in Listing 15-60 to the updateTextSize: method.

Listing 15-60.  Updating the updateTextSize Method Add Value to NSUserDefaults

- (IBAction)updateTextSize:(id)sender
{
    // ...

    // Update Preferences
    NSInteger selectedSize = self.sizeSegmentedControl.selectedSegmentIndex;
    [self.userDefaults setDouble:selectedSize forKey:@"TextSize"];
    [self.userDefaults synchronize];
    [self.iCloudKeyValueStore setDouble:selectedSize forKey:@"TextSize"];
}

Finally, when updating the user interface with the preferences, instead of just blindly taking the value from the iCloud key-value store, you’ll first check and see whether it exists. If it doesn’t, you’ll use the value from the local cache instead. Listing 15-61 shows the new implementation of the updateUserInterfaceWithPreferences method.

Listing 15-61.  The New Implementation of the updateUserInterfaceWithPreferences Method

- (void)updateUserInterfaceWithPreferences
{
    NSInteger selectedSize;
     
    if ([self.iCloudKeyValueStore objectForKey:@"TextSize"] != nil)
    {
        // iCloud value exists
        selectedSize = [self.iCloudKeyValueStore doubleForKey:@"TextSize"];
        // Make sure local cache is synced
        [self.userDefaults setDouble:selectedSize forKey:@"TextSize"];
        [self.userDefaults synchronize];
    }
    else
    {
        // iCloud unavailable, use value from local cache
        selectedSize = [self.userDefaults doubleForKey:@"TextSize"];
    }

    self. fontSizeSegmentedControl.selectedSegmentIndex = selectedSize;
    [self updateTextSize:self];
}

Now the app should work and persist its size text preference, both with iCloud and without it.

As you can see, working with iCloud key-value store is extremely simple. There’s but one problem: you cannot store big chunks of data. There is a limit of 1 MB per application, and you can use no more than 1,024 keys to store the data. This makes it a poor candidate for application data model storage. For that, you can use the document store, which is what the next recipe is about.