Learning iCloud Data Management (2014)

Part IV: Using iCloud Documents and Data

14. Working with File Wrappers in iCloud

Part IV of the book gets to the heart of iCloud—the APIs for managing documents and data. You have to go back to the basics and understand how common terms you are familiar with have very specific meanings in iCloud. In particular, you may be among the many people who use “document” and “file” interchangeably. There has always been a distinction between those terms, but it hasn’t mattered too much until iCloud. Now it matters.

This chapter introduces the distinctions between these terms and then explores the APIs you need to use to manage files and file wrappers. The remaining chapters in this part delve into the APIs for managing documents on iOS (Chapter 15) and on OS X (Chapter 16). The Core Data API that was described in Chapter 10 comes into play again in Chapter 17 when it is merged with iCloud and the concept of documents.

The focus in this chapter is on files and file wrappers and how you use them with iCloud. The chapter looks for the iCloud ubiquity container and, if it finds it, uses it. That’s a good start for looking at files and file wrappers, but as you move into chapters 16 and 17, you’ll see how to manage iCloud accounts, availability, and options. Those features are necessary in a shipping app.

As is the case with the other chapters in this part of the book (as well as many chapters in previous parts), this chapter contains an annotated example; you can download it from the author’s website as well as from www.informit.com/title/9780321889119. The project in this chapter is code-named Placid. (The project code names are taken from the names of lakes in northern New York’s Adirondack mountains.) In this chapter, Placid is implemented only for iOS. Chapter 16 explores an OS X version.

Exploring Files, File Wrappers, and Documents

This section explores the distinctions between files and documents and introduces the file wrapper structure. You may be familiar with these topics, and in that case feel free to skim this section or to skip over it entirely. The challenge for both reader and author is that although these and many other iCloud concepts are not particularly new (the NSFileWrapper class goes back to the first release of OS X), you may not have needed to pay attention to them before now.

This is actually a common situation with iCloud. iCloud has been implemented by making changes—often relatively small changes—to existing APIs across the two operating systems. Along the way, many recommendations and best practices have become required. That’s the reason it is necessary to occasionally backtrack to some basics.

Looking at Files

On almost all operating systems, files contain data. They are stored on disks and other storage devices. Users and developers generally access them by name and location—the directory in which they are stored. (Note that folder is the user-facing term for what is technically a directory.)

Files can be of various types; in general, a file of a specific type is linked in some manner to apps that can be used to edit or display it. Typically, this linkage has been accomplished with a file extension that is appended to the file’s name.

As you may have learned (the hard way), this structure is a bit fragile, especially when moving files across platforms. (Is it JPEG or JPG? TEXT or TXT?) Over the last several iterations of Apple’s operating systems and Xcode, a more robust mechanism has been implemented—the Uniform Type Identifier (UTI). It is more robust and flexible, but it also is a little more complicated. Fortunately, much of that complexity has been removed with Xcode 5, as you will see later in this chapter.

As you saw in Chapter 1, “Exploring iCloud and Its User Experience,” iCloud introduces a new file storage structure. No longer are files visibly stored on disks in whatever structure the user wants using folders such as My Projects, Trail Maps, Pictures, Soccer Games, and the like. Instead, as described in Chapter 1, files are stored in areas reserved for individual apps. Within that area, there can be any number of files or directories (subject, of course, to device storage limitations).

In fact, the description in Chapter 1 is the common description presented to users, but it is an oversimplification. The storage area for files is not specific to an app; rather, it is specific to a bundle identifier. In most cases, apps have unique bundle identifiers; however, several apps may share one bundle identifier. Thus, they share a storage area and the files and directories within it.

Exploring File Wrappers

File wrappers (instances of NSWrapper or a subclass thereof) provide a means of working with file-system nodes, which are files, directories, or symbolic links using a common interface. (In the context of iCloud, you typically work only with files and directories.) A file wrapper has a name and a set of file-system attributes (as described in the NSFileManager Class Reference). If a file wrapper wraps a file, the file’s content is available through the regularFileContents method, which returns an NSData object. Thus, file wrappers provide a mechanism that lets you work with files and directories using a common interface for both of them. (In fact, you can argue that this common interface for files and directories is one of the key roles of the Finder on OS X.)

If a file wrapper wraps a directory, that directory itself is a file wrapper within the overall directory file wrapper. You can access the items within a directory file wrapper using the fileWrappers method, which returns an NSDictionary. Where the user sees a folder within a folder, the developer sees a dictionary within a dictionary, and, when using file wrappers, the developer sees a file wrapper within a file wrapper.

File wrappers become very important in the iCloud world. As noted previously, synchronizing data is easiest when the data is structured so that it can be disassembled and reassembled on demand. If it is structured in this way, the sync process can be run only for those specific parts of the data that have changed since the last sync. A file wrapper provides an excellent example of this. What appears to be a single file can actually be multiple files and file wrappers, each of which can be synced separately by iCloud if that is desired.

Exploring Documents

On OS X and iOS, document refers to a specific class of object—either UIDocument on iOS or NSDocument on OS X. A document almost always contains data that can be stored in a file wrapper, in a single file, or in a Core Data persistent store that is part of the document. Both document classes implement a robust and complex user experience for the platform. The document is not the file (or file wrapper). They are related but different.

The differences between UIDocument and NSDocument are significant in many areas, which is why they are discussed in separate chapters. For example, NSDocument builds in an Open dialog, which lets users select files to open from any disk or folder to which access is provided. On iOS, it is the responsibility of the app to display the list of documents that can be opened. Fortunately, that is not too difficult to accomplish.

How Users Manage iCloud Files

In Chapter 13, “Adding the iCloud Infrastructure,” and this chapter, you see what you do to manage files. It’s time to switch roles for a moment and see what the users see as they work with your file management code.

With OS X Mavericks (10.9), users have direct access to their iCloud containers just as you do with developer.icloud.com. This access comes through the iCloud System Preferences pane, as shown in Figure 14.1. Click Manage in the lower right to begin the process.

Figure 14.1 Managing iCloud storage

Next, you see the list of apps in your iCloud container just as you do in developer.apple.com, as shown in Figure 14.2.

Figure 14.2 Listing apps in iCloud storage

In developer.icloud.com, you have the ability to download a file from the iCloud container, but the user does not have that feature. There is another difference: users can remove files from their iCloud container, but you can’t do that with developer.icloud.com. (There are Delete and Delete All buttons at the bottom of the pane that shows the containers. You reach it with the Manage button at the bottom of Figure 14.1.) Figure 14.3 shows the developer.icloud.com display.

Figure 14.3 Accessing developer.icloud.com

If you download a document from developer.icloud.com, it appears as a single file on your desktop. If it is a file wrapper, control-click the file and you’ll see a contextual menu containing the Show Package Contents command. (This command never appears in the menu bar.) If you use the command, the file will open, as shown in Figure 14.4, and you can see the files contained within the file wrapper (a .png image, a property list, and a text file).

Figure 14.4 Opening a file wrapper document

In this case, the file wrapper contains three files: an image, a plist, and a text file. It could also contain one or more file wrappers. Thus, in various contexts a file wrapper can appear as a single file (the basic Finder display), a package of embedded files and folders (Show Package Contents), or in other formats that your app may implement.

Starting the Placid Project

Like many other iOS projects, Placid starts from the Xcode built-in Master-Detail Application template. It’s always a good idea to build and run a new project as soon as you have created it. The Master-Detail Application template should run at this point. If it doesn’t, backtrack to check your various installations (operating system, Xcode, and developer program). At this time, you can run it in the simulator.

In order to focus on building an iCloud-enabled file wrapper–based app, the version of Placid used in this chapter omits many of the features that you need in a shipping application, such as error messages, and even the basic user choice of whether or not to use iCloud—iCloud is the only data storage that is implemented. Much of the iCloud infrastructure described in the previous chapter is omitted to focus on the file wrapper code.

Like previous examples, Placid is a simple app that lets people keep track of issues that need attention. For each entry in the app, there will be a description (a text field) and a location (another text field). You can expand this model to include more data, including images. Each entry will wind up as a document whose data is stored in a file wrapper. (It is a simplification that the text document contains only a single field.) In practice, you often have a variety of fields as well as data in the overall file wrapper itself in addition to within the inner file wrappers.

This section lists the steps you need to go through to set up your new project. Some are specific to all iCloud projects, and others are not. It may seem as if you’re jumping around, but these steps involve settings that are entered out in various places inside your Xcode project and on developer.apple.com. So if you’re chomping at the bit to get started writing code, just hold on for a little bit. You may be able to carry out these steps in a different sequence, but remember that cutting corners by skipping steps will often come back to haunt you. As many developers have found out the hard way, tracking down configuration issues can be very time consuming.

Here are the sections that follow:

Certificates, Identifiers, Devices, and Profiles on developer.apple.com: These settings are configured on developer.apple.com.

Certificates, Identifiers, Devices, and Profiles on Xcode 5: Some of these can be configured directly from Xcode 5.

Adjusting the General Settings: These settings are mostly as they were in Xcode 4, but the interface is drastically different in Xcode 5.

Setting Images: One of the major features of Xcode 5 is its ability to manage images as assets without having to worry about file naming conventions.

Configuring Capabilities: This is where you set up iCloud access and other capabilities for your app.

Setting Document and Universal Type Identifiers: If you are going to be using your own documents and importing or exporting them, this is the section where you do so.

Checking Build Settings: This is a final review before you move on to writing the code.

Certificates, Identifiers, Devices, and Profiles on developer.apple.com

Now is a good time to check your provisioning profiles and to create one for Placid. It may seem as if you’re skipping the basic project setup steps, but you’ll get back to them shortly. The reason for focusing on the certificates, identifiers, devices, and profiles is that they must be set up on your developer account. (Provisioning profiles can be set up either on the developer website or on Xcode 5.) Particularly if you have not done this before or if you have not done it for a while, that process may require a little time (and it might require one of your technical support incidents the first time). So it is a good idea to get these steps out of the way right at the start. If there is a delay in sorting out your developer account, you can move on to configure your app, as described in the next section, while you wait for the resolution.

To recap, following are the documents and certificates you need to create a provisioning profile. You create them on developer.apple.com. For both iOS and OS X, you access them at the right side of the page in the Developer Program section. They are under the link named Certificates, Identifiers & Profiles.

Signing certificates: As a developer, you should have at least one of these. You should not have any duplicates—that is one of the root causes of problems in setting up provisioning profiles. For Placid, you must have at least an iOS Development certificate. You may also have an iOS Distribution certificate (this is for the App Store).

Identifiers: You need to add an App ID for your app. This is another area that has changed recently. If you search the web for information on how to delete an App ID from your account, you will find many references to the fact that you can never delete an App ID. That is not the case today. The rule is that you cannot delete an App ID for any app that has been submitted to the App Store—that is submitted, not necessarily accepted. You can see the reason for this. The App Store software does let you revoke an app or even not resubmit an app that has been rejected. In both cases, the app is not on the App Store after the revocation or rejection. However, to keep the App Store records straight, the App ID must continue to exist for these previously submitted apps. If you are creating an App ID for a test app and have no intention of submitting it to the App Store, you should have no qualms about creating a new App ID and then deleting it. For now, add an App ID for Placid.

Devices: Here is where you add devices to your account for testing. You can have up to 100 devices. You may need to add a device for testing if you don’t already have one in your developer account. (The simulator is a special “device,” so don’t worry about adding it.)

Provisioning profiles: This is where you combine a signing certificate, an App ID, and one or more device IDs. (Don’t worry, you just use checkboxes off your list of up to 100 devices.) Add a provisioning profile for Placid on developer.apple.com, or use the steps in the following section with Xcode 5 on your Mac.

Certificates, Identifiers, Devices, and Profiles on Xcode 5

Once you have everything set up on developer.apple.com, you can use the new Accounts preferences on Xcode 5 to manage that end of things. Choose Xcode, Preferences and select the Accounts tab as shown in Figure 14.5.

Figure 14.5 The Accounts tab of the project

You can add any number of developer accounts to Xcode as long as you have the proper credentials. Select an account and click View Details to see the information shown in Figure 14.6.

Figure 14.6 Viewing details for a selected account

It is a good idea to compare the account details as shown in Xcode with the details for the same account shown on developer.apple.com. As this system has evolved over the years, many developers have discovered some anomalies that have crept into their account. These are not bugs; rather, they are the result of various misunderstandings some developers have had over time. Now that everything is laid out clearly, get rid of those before you find yourself locked out of the App Store at a crucial moment.

Adjusting the General Settings

Once you have created the project, built it, and run it on your testing device, it’s time to adjust some of the settings in the project. As noted in the Preface, this book is based on Xcode 5, OS X Mavericks (10.9), and iOS 7. Xcode 5 brings some extraordinarily significant improvements to the process of setting up and configuring a project: they are described in this section. If you are using an earlier version of Xcode, your best choice is to update to Xcode 5 (Xcode is free). If you need Xcode 4 to maintain legacy projects, rest assured that you can have both versions installed on a single computer. The only issue you must remember is that opening an Xcode 4 project in Xcode 5 may reformat some storyboard or nib files to the Xcode 5 format. If you want to be doubly safe, create a separate user account on your Mac for your Xcode 5 and Xcode 4 projects and install the appropriate Xcode version in each.

The basic setup for the project is the same process you’re used to. The general information is collected during the process of creating the project as always. In Xcode 5, there are some new features, which are described in this section. In every case, they simplify your work (in some cases, dramatically so). Figure 14.7 shows the General tab of the project settings.

Figure 14.7 The General tab of the project

Setting Images

One of the changes in Xcode 5 is the addition of the xcassets file type for managing assets such as images in asset catalogs. The easiest way to work with assets is to experiment with them yourself. Figure 14.8 shows the editor for the app’s Images.xcassets file. Gone are the days when we relied on dedicated file names to identify what file is what. Furthermore, as you can see in Figure 14.8, critical dimensions for specific files are shown right there on the editor. Note that the dimensions are given in points rather than pixels. Points are and have been measures of length (1/72 of an inch). As you can see in Figure 14.8, you can supply Retina (2x) and non-Retina (1x) versions of your images. Try not to think about how much time you have spent tracking down this information in the past. (And, in all fairness, remember that some of the difficulties in setting up apps before Xcode 5 occurred because the entire app universe is only a few years old now and was evolving as Xcode was evolving.)

Figure 14.8 Using Images.xcassets

Configuring Capabilities

You really have to have gone through the pre-Xcode 5 process of configuring your app’s capabilities to appreciate the new process of configuring the capabilities in Xcode 5. Here are the capability configuration steps in Xcode 5:

1. Verify your certificates, identifiers, devices, and profiles on developer.apple.com as described previously.

2. Verify them on Xcode, Preferences, Account as described previously. (If the versions on developer.apple.com and those on Xcode don’t match, resolve the conflicts and/or create missing certificates, identifiers, and profiles.)

3. Select your project in the Xcode navigator and choose the target you want to configure.

4. In the Capabilities tab, click to turn iCloud on. That’s it—one mouse click (as long as you’ve done the preparatory work).

Xcode adjusts your App ID to add the iCloud entitlement (this used to be a manual process you had to do), and it updates or creates an entitlements file in your project. Figure 14.9 shows the Capabilities tab.

Figure 14.9 Configuring the iCloud capabilities

Note that Capabilities has an extra feature that can come in very handy. If there’s a problem with your credentials, you may have had the experience of tracking down which document is wrong or missing. This is often somewhat a trial-and-error process; more than one developer has managed to cause further difficulties in attempting to rectify the initial problem in this way.

Now, if you have issues such as missing profiles or anything else that prevents compilation or running on a device, your immediate action should be to click Capabilities. If you have already turned on iCloud or any of the other options, you may see a message indicating what is wrong. (This alone can save hours for work.) Even better, you may find a Fix button that you can click to resolve the issue automatically.

Setting Document and Universal Type Identifiers

As described previously, the distinction between files and documents is sometimes not important to users, but it’s critical to developers. In the Info tab of the project’s target(s), you describe the documents with document types. UTIs describe the files your app deals with; you have separate UTIs for imported and exported files—that is, files from other apps that you read and those that you write for other apps to read. UTIs and document types are linked by a common value—type in a document type and identifier in a UTI.

If you use documents in your app, you declare a document type in the Info tab of your project’s target, as shown in Figure 14.10.

Figure 14.10 Setting up a UTI

Setting Up Document Types

Here are the steps to follow to create a document type:

1. Create a new document type with + in the document types section.

2. Provide a name for the document type. This is a name for you to use in Xcode.

3. Provide a type using reverse-domain name notation. You can provide several types, but you commonly only provide one.

4. Add icons for the document.

5. Open additional document type properties and add three of them, as shown in Figure 14.10:

LSTypeIsPackage: For file wrappers or packages (as described in this chapter), add this string and set its value to YES.

CFBundleTypeExtensions: Add an array with the file extensions used for this document type. As you see in Figure 14.10, the extensions are strings; it doesn’t matter what their names are.

LSHandlerRank: This string’s value is usually either Editor or Owner depending on how your app will be using the document.

Setting Up UTIs

The UTIs provide information about files you read and write. Here are the steps to follow to set up a UTI either for importing or exporting:

1. Set the description. This is a user- and developer-oriented description. It is not used internally.

2. Provide a unique identifier. Follow the practice of using your reverse-domain name and appending a final term that makes sense to you. This should match a type in a document type.

3. Provide the name of the UTI to which your new UTI conforms. For a file wrapper–based document, you want com.apple.package. The UTI structure is a hierarchical one in which you can specify your own object or inherit from a higher-level one such ascom.apple.package.

4. Add icons for a production version of your app. Use the Images.xcassets file to store them and then select them in defining the UTI.

5. Add a new UTI property called UTTTypeSpecification as a dictionary. Within the dictionary, create an array called public.filename-extension. Within that array, create at least one string, which will be the file extension (it doesn’t matter what the name of it is).

Checking Build Settings

As you can see in Figure 14.11, if you have followed the steps for setting up a UTI, your code signing settings have been set up for you by Xcode. If you need to adjust them, the Build Settings tab is where you do it.

Figure 14.11 Code signing set up automatically

If you have resolved an issue using the Fix button in Capabilities, you may need to revisit your build settings for them to match your new capability settings.

Writing the Code

Now it’s time to move on to the code. As you have seen before, much of the code that you write is a small snippet here and perhaps a tweak to the template code there. Often, the biggest single chuck of “writing” the code is designing the user interface and functionality with Interface Builder in Xcode, as shown in Figure 14.12.

Figure 14.12 The basic app interface

In general these are the sections of code that you will customize or create:

AppDelegate: This is part of the template. You need to add some minor iCloud housekeeping code.

MasterViewController: The master view controller will display the list of documents from iCloud. As is always the case in Master-Detail Application apps, it will allow you to add new documents to the list, so it must have the supporting code to create them, read them, and write them.

DetailViewController: As always, this displays the detail information for a selected item in the master view.

WrappedDocument: This is the document that contains the file wrapper that stores the data for each document created by the app. All of this code is new.

Note that in the examples, the file prefix has been set to JF in setting up the project. You can use your own initials if you want to keep your files separate. You may also want to compare the code in this chapter with the code in Chapter 13. Although both start from the same template, they have different approaches to the overall structure of the app.

There are two projects on developer.apple.com that you can explore to see other approaches to using file wrappers and iCloud:

Your Third iOS App: iCloud (this is under documentation)

Document Package with iCloud (this is an OS X project under sample code)

Placid and these two projects accomplish basically the same goal, but there are some implementation differences. The code annotations in this chapter point out the most important ones. These differences are a matter of style and preference. The only reason for pointing them out is to help you follow the parallel implementations in which different names are used for the same logical elements.

AppDelegate

There are just two changes to AppDelegate.m. There are no changes to AppDelegate.h. Listing 14.1 shows AppDelegate.m. As always, some spacing in the code has been adjusted to the book layout. Most of this file consists of comments in the template reminding you of features you can use and enhance. They are retained here to remind you of what is missing: the focus in this book is on iCloud, so if you move this code to production, check the comments in the template for additional code you might write. Also note that this code is the bare-bones implementation of iCloud access: you will need to monitor account changes, Airplane mode, and the like as shown in the shared iCloud controller in Chapter 13.

Listing 14.1 AppDelegate.m