Learning iCloud Data Management (2014)

Part IV: Using iCloud Documents and Data

13. Adding the iCloud Infrastructure

From here on, you’ll be building various iCloud-enabled implementations of the Reports app that was mentioned previously. The common core of each of these implementations is the shared iCloud data that at various times will be stored on local devices or on iCloud. The implementations may run on OS X or on iOS. And if you think that you need a bit more complexity, the data will be stored using Core Data, or standard Cocoa and Cocoa Touch documents.

What this means is that you will do the same thing over and over in these various contexts and combinations. This chapter helps you set up the software that makes it possible. The software works for an app that is implemented on OS X as well as a corresponding app on iOS. If you want to build only one of those apps, it will also work: you’ll just have an empty folder for the nonsupported operating system. Because it’s almost as easy to build this infrastructure as it is to build a single-OS implementation, it is easier to start out this way so that you keep your deployment options open.

After you set up your Xcode project, you’ll see how to implement an iOS app that uses iCloud to share a very basic document. The app is built around the “Third iOS App: iCloud” document from developer.apple.com. That document shows you how to build an iCloud-enabled iOS app. The app in this chapter borrows the basic document structure, but it reorganizes the project file structure to make it easier to expand the code so that it runs on both iPad and iPhone. In Chapter 16, “Working with OS X Documents,” you’ll see how to expand the code again so that it runs on both iOS devices and Macs.

Also in this chapter, you’ll see how to implement basic iCloud functionality and how to debug iCloud projects using developer.icloud.com. developer.icloud.com is a critical component of your iCloud testing. You can now use the iOS simulator to test your iCloud code. But, as noted previously, to really test iCloud apps, you need to have multiple devices representing each operating system you want to support. That is true for testing of finished apps, but what can you do if you’re just starting out? Do you have to buy lots of new Apple devices?

You can test iCloud with a single iCloud-equipped device. That device can communicate with iCloud, and as a registered developer, you can see your own iCloud container using developer.icloud.com. You can’t test as many combinations and permutations of synchronization with a single device and developer.icloud.com as you can with multiple devices, but you can certainly get a feel for the process and complete some basic testing. This chapter focuses on iOS devices, but if you only have a Mac, you may want to jump ahead to Chapter 16 to implement your app and then use developer.icloud.com as described in this chapter to see what happens.

Exploring the Workspace for the App

By using a workspace, as described in Chapter 11, “Using Xcode Workspaces for Shared Development,” you can set up an iOS target and an OS X target in the same project. There are many ways to do this, but the design described here is the easiest—at least for the author. What you will work toward is a structure of files and folders, as you see in Figure 13.1.

Figure 13.1 Creating a multitarget workspace

There are separate folders for the OS X and iOS projects. A third folder (Shared) contains files that are common to both projects. The workspace itself is placed at the top level of this folder, and the entitlements file, which needs to be part of both targets, is also at the top level of the project folder. (It could also be in the Shared folder.)

That is the structure toward which this chapter is moving. This chapter focuses on what will be the contents of the Shared folder. For simplicity’s sake, it is developed here with a single project—iCloudReports—which is the iOS component.

When you open the workspace in Xcode, the project navigator shows you the files and groups at the left of the workspace window, as always, just as you see in Figure 13.2.

Figure 13.2 Viewing the project in Xcode

Figure 13.2 also shows how you can use the File inspector to check on a file’s path or to modify it. Particularly if you are assembling a workspace like this using projects that have already been created, you may at some time need to update file paths (remember that files shown in red have no files associated with them).

When you add files to a project, you have the choice to copy them into the project if needed. One way to assemble a workspace such as the one shown here is to manually add the files to the appropriate folder (or to create a new project using File, New, Project and set the project location to be the appropriate folder). Once the files are in the right place, add the project to the workspace with the shortcut menu by using Add Files to Project. Just make certain not to use the Copy checkbox. If you do use it, you’ll find that you’ve added a group of the added files in addition to the files themselves within the project. This will not necessarily cause problems, but it will annoy some developers.

Figure 13.3 shows the file and folder structure in the Finder. Compare it to the Xcode view shown in Figure 13.2.

Figure 13.3 Viewing the workspace files in the Finder

A workspace structure like this can help you build both the iOS and OS X apps. The key is knowing what belongs in the Shared folder. Ideally, that code would be used without modifications in both the iOS and OS X versions. Although from time to time you may want to use conditional statements to branch for separate sections for each operating system, many developers feel that the shared code should be “pure” and free of such customizations. You can certainly put the iCloud infrastructure code there. In the case of Core Data, that’s where your data model can be along with the code that will implement the Core Data stack.

Two areas to which you do have to pay attention are document and user interface differences in the two operating systems. They are discussed in the following sections.

Exploring iOS and OS X Document Architecture Differences

There are very different architectures for documents on the two operating systems. This means that you have to take care when sharing documents through iCloud. When you use non-document-based storage architectures such as key-value coding (KVC), Core Data, or property lists, you don’t have to worry about the differences between iOS and OS X except for the fact that certain features (telephony and removable storage, to name two) aren’t available on both platforms.

Perhaps the most significant user interface difference is that documents are not visible to users through the iOS operating system in the way that users can see and manipulate documents in the Finder on OS X. As noted in Chapter 1, “Exploring iCloud and Its User Experience,” iCloud uses apps to organize documents. From the user’s point of view, it may mean reversing the steps to open a document. When you’re in the iCloud world, you open an app, and then you open or create a document for that app. On OS X, you can go to the Finder to locate the document that you want to open. You select the document and choose Open from the File menu or double-click the icon, and the app will open. (Note that this is a simplification because you can use a shortcut menu to choose among various apps that could open a given document. This is only an overview of the process.)

What is significant is that on OS X the management of opening a document or of saving it is done using standard Cocoa tools. The Finder takes care of showing you the documents that could be opened.

On iOS, because you start by launching the app you want to use, each app is responsible for displaying the files it can open. Thus, managing an app’s documents is the app’s job rather than the job of the operating system.

Dealing with UI Differences

Although Cocoa and Cocoa Touch have common roots, there are important differences. Also, Cocoa Touch was developed years after Cocoa, so some changes that were difficult to implement on an incremental basis in Cocoa were added from the start in Cocoa Touch (sandboxing is one of these). Among the most important differences are those that stem from document management, as described in the previous section, as well as those that are related to the absence of a menu bar on iOS.

Even when the logic of the interface is the same on both iOS and OS X versions of an app, the mechanics often differ (posing an alert is a good example). Trying to make OS X and iOS versions of an app similar can make life easier for users than having to learn two different interfaces; however, in practice, users seem to prefer interfaces that look “right” for the device over those that look “wrong” on both types of devices.

Designing the Shared App Folder Structure

The challenge for a developer is to create an app structure that allows as much common code as possible but also provides easy implementation of device-specific code. That is the strategy used here. As you have seen, there are two separate projects in the workspace—one for iOS and one for OS X. On disk, each project’s files are in a separate Finder folder. A Shared folder contains the files that are shared: these files are added to both of the projects in a Shared group for each of the projects. Although groups in Xcode use folders as icons, remember that they are not Finder folders. As long as you keep in mind that the shared files exist in a single place on disk (the Shared folder) while they appear in two places in the workspace (the Shared groups in both projects), all will be well. Because these are shared files, editing them from either project edits them in the other.

One prime candidate for the Shared folder will be everything that has to do with iCloud itself. You will share a ubiquity container between the OS X app and the iOS app, so it makes sense to share the code that manipulates it. Unfortunately, that is easier said than done. Apple has an excellent tutorial, “Your Third iOS App: iCloud,” that introduces you to iCloud. That app is a great starting point, but it runs only on iPhone. The app shown in this chapter runs on both iPhone and iPad. Furthermore, it is factored so that the common iCloud code can be placed in the Shared folder, while the OS-specific code (mostly UI interactions) is placed in the relevant projects. In addition, the structure of the Shared folder is set up with an eye to expanding the app to OS X, which you’ll do in Chapter 16.

Checking Out the End Result

The app in this chapter is built on the Master-Detail Application template for iOS. By the end of the chapter, you’ll be able to create documents on an iPhone, as shown in Figure 13.4.

Figure 13.4 Creating and selecting documents on iPhone

You’ll also be able to run the same app on an iPad, as shown in Figure 13.5.

Figure 13.5 Running the app on iPad

One of the biggest differences has to do with the split view controller on iPad: there is no comparable feature on iPhone. Thus, as you see in Figure 13.5, you can see the list of documents as well as the content of the selected document at the same time. On iPhone, a navigation interface lets you move from the list (the master view controller) to a detail controller, as you see in Figure 13.6.

Figure 13.6 The iPhone version uses a navigation interface

Scoping the Project

This chapter’s app is not complete: it is designed to get you started with an app that uses iCloud across multiple iOS devices. You’ll add OS X functionality in Chapter 16.

Furthermore, it uses the same simplification that is used in “Your Third iOS App: iCloud.” It writes the document data directly to iCloud. For a real project, you would probably write to a local directory and then move that local data to iCloud using one of the techniques described in the following chapters. That strategy allows for sharing (through iCloud) as well as continued operation if iCloud is not available.

Managing local and iCloud copies of data is an important part of iCloud development, but it does add a complicating factor, which you don’t need at this point. You will see how to help users manage conflicts in versions of their data, but that is one of the areas where the differing document structures in OS X and iOS come into play. That is why that discussion is deferred to Chapters 15 and 16.

Behind the scenes in this project, the document data is stored in a UIDocument in the most minimal form possible—a text string.

Debugging iCloud Apps with developer.icloud.com

When you talk about debugging an app on a Mac or an iOS device, you usually talk about running it to make certain it does what you want it to do (and doesn’t do what you don’t want it to do.) That’s very simple, but when you’re working with iCloud, you have some additional challenges. Specifically, how do you see what the app is doing when what it is doing is happening in iCloud?

You can examine your iCloud storage using developer.icloud.com if you are a registered developer. Log in with your developer ID, and you’ll see your iCloud storage with its Documents folder, as shown in Figure 13.7. There may be some additional folders, but for now Documents is what you are interested in.

Figure 13.7 Viewing your iCloud storage

Open the Documents folder shown in Figure 13.7, and, as you see in Figure 13.8, each of the apps that you use in iCloud has its own folder.

Figure 13.8 Each app has its own iCloud folder

Within the folder for the app that will be developed in this chapter, you can see all of its documents. Compare Figure 13.8 with Figures 13.4 and 13.5 shown previously.

Just as in the Finder, you can select a document and see its size and modification date. Also note that you can use the button at the right of Figure 13.9 or the down-pointing arrow at the top to download a file from iCloud. This lets you open the file on your Mac to check its contents.

Figure 13.9 Viewing your iCloud documents

Note that these are debugging tools only accessible by a registered developer. Users can’t see their iCloud data in this way.

As you can see in Figure 13.10, files outside of the Documents folder may or may not be visible to users (it’s your choice). You can use the Home button, as shown in Figure 13.10, to move outside the Documents folder to see files and folders you have created inside the app’s ubiquity container.

Figure 13.10 Moving outside the iCloud Documents folder

If you already have an iCloud-enabled app that works with documents, you can open developer.icloud.com to see those documents. One of the most important things to learn about iCloud is that it is an asynchronous process. If you have one of the iWork apps, here is an important experiment to conduct:

1. Open developer.icloud.com for your developer ID.

2. Go to the apps list, as shown in Figure 13.8.

3. Run an iWork app and create a new document.

4. Save it to iCloud, as shown in Figure 13.11.

Figure 13.11 Saving an iWork app to iCloud

5. Watch to see the document appear in iCloud.

If this is the first document you’ve saved in iCloud from this app, the app will be added to the list of apps shown previously in Figure 13.8. Repeat this process periodically to see how the time varies for iCloud updates. Because there is a local copy of your iWork document, it doesn’t matter that the upload isn’t simultaneous because you can continue working.

Building the App

Before you start to build the app, go to developer.apple.com and create an App ID for iCloud Reports for development on iOS. (Yes, you can build the App ID before you start coding the app.)

Now it’s time to build the app. Here are some steps to get started. Because of the shared folder, you may have to do a bit of rearranging, but once it’s done, things will be easier to work with.

1. Create a new workspace (see Chapter 11, “Using Xcode Workspaces for Shared Development”).

2. Create a new project based on the Master-Detail Application template called iCloud Reports.

3. If you want to use the Shared folder structure described previously, create that folder inside the project folder. (Remember, you’re creating the Shared folder using the Finder.)

4. Make certain that it has a universal interface and that it does not use Core Data.

5. Turn on iCloud in Capabilities for the project. An entitlements file will be created for you and added to the project, as shown in Figure 13.12.

Figure 13.12 Using an entitlements file

6. Depending on your project, you may also want to use iCloud and Key-Value Store.

7. Accept the default ubiquity container.

If you want to look inside the entitlements file, you’ll see what Xcode has done for you, as shown in Figure 13.12. There is nothing for you to do, but you might want to see what has been set up.

You will be adding and modifying code in the template classes. The changes are discussed in the following sections.

Creating the Shared Folder

The Shared folder is a good place to start coding with Xcode because it is not dependent on any of the other classes, although other classes are dependent on it. (Notifications make this possible.) There will be two classes in the Shared folder:

Constants is a convenience class.

SharediCloudController is just what its name says: it provides iCloud support for both of your projects.

Constants.h

Constants.h is a class containing constants for the project. There are many ways to provide constants across the project. The simplest is an ordinary #define. Creating a class is a little more work (but not much), and it can provide some improvements in turnaround time when developing a large project. Once you have declared a constant in the .h file, if you change its value in the .m file, that may require fewer other classes to be recompiled.

You can see the structure of the header in Listing 13.1.

Listing 13.1 Constants.h