What You Must Do to Make a Document-Based Application

To create a document-based application, you should complete the following tasks:

• Create a custom subclass of UIDocument that provides the UIKit framework with a snapshot of document data and that initializes the document’s model objects from the contents of the document file.

  Creating a Custom Document Object describes the required method overrides and, if document data is to be stored as a file package, explains how to go about using NSFileWrapper objects for document data.

• Allow users to create new documents and select and open existing ones. You should also implement the complementary tasks of closing documents and deleting selected documents.

  Note that the follow-on task to creating or opening a document is displaying the document’s content in a view.

  Creating a New Document, Opening and Closing a Document, and Deleting a Document describe the requirements and procedures for these tasks. These discussions also include examples of managing the display of document data.

• Implement undo management or change tracking to enable the automatic saving of document data (saveless model).

  See Change Tracking and Undo Operations for details.

• Put documents—typically those selected by users—into iCloud storage. Also remove documents from iCloud storage when users request this.

  Moving Documents to and from iCloud Storage discusses these procedures.

• Observe notifications of changes in document state and, if an error occurs, respond appropriately.

  Monitoring Document-State Changes and Handling Errors describes the general procedure for doing this.

• If conflicts between different versions of a document occur, notify the user and offer ways to resolve the conflicts.

  Resolving Document Version Conflicts describes how to notify users of version conflicts and discusses strategies for resolving these conflicts.

You can also add extra features to your document-based application, such as the capability for printing the document, spell-checking it, or emailing it to others.

If your application has advanced requirements—for example, incremental reading and writing of large document files or dealing with document-data formats other than the supported ones—see UIDocument Class Reference. All of these advanced tasks involve overriding UIDocument methods.

Creating and Configuring the Project

When you create the Xcode project for your document-based application, choose a suitable template. (Note that there is no template specifically for document-based applications.) Generally, you want the first view of the application to be one in which users can choose existing documents and create new ones. Because the Master-Detail Xcode template is suitable for this purpose, it is used in the code examples throughout this document. This template gives you an initial table view for the iPhone and a split view for the iPad. Your project should use a storyboard, so be sure to select this option.

Based on the design for your application (see Designing a Document-Based Application), create the view-controller subclasses that your application requires. All you need are minimally declared header and source files at this point. Then, create the user interface of your application in the project storyboard (or storyboards, if yours is a universal application); associate your custom view controllers with the view-controller placeholders in the storyboard.

Next, you need to configure the project for documents by specifying, in the Xcode target settings, the type or types of the documents that the application knows about.

How iOS Identifies Your Application’s Documents

The most important attribute of a document object in iOS is its file URL (fileURL). The file URL is important, among other reasons, because it tells iOS which applications understand the document’s format. The file URL ends with an extension (for example, html) and this extension is matched with a Uniform Type Identifier (for example, public.html). The Uniform Type Identifier (UTI) is the principal identifier of document type. Using the extension, UIDocument looks up the document-type UTI (as shown in Figure 2-1) and assigns it to the fileType property. Unlike document-based applications in OSX, those in iOS don’t need to associate the UIDocument subclass with the document type.

A document-type UTI can be defined by the system; see System-Declared Uniform Type Identifiers in Uniform Type Identifiers Reference for a list of these common identifiers. A document-based application can also define its own proprietary UTI for its documents (and often does). If it does declare a custom UTI, it must also export that UTI to make the operating system aware of it.

Declare a Document Type

To declare a document type in Xcode, start by clicking the Add button in the target’s Info settings and choose Add Document Type from the pop-up menu. Click the triangle next to Untitled to disclose the property fields and add the properties in Table 2-1.

Table 2-1  Properties for defining a document type (CFBundleDocumentTypes)

Key	Xcode field	Value and comments
LSItemContentTypes	Types	An array of UTI strings. Only one is typically specified per document type.
CFBundleTypeName	Name	An optional name for the document type.
CFBundleTypeIconFiles	Icon	An array of paths to icon image files in the application bundle.
CFBundleTypeExtensions	In “Additional document type properties” table.	An array of filename extensions paired with the document UTI.
LSHandlerRank	In “Additional document type properties” table.	Owner, Alternate, None. (Typically Owner).
LSTypeIsPackage	In “Additional document type properties” table.	If document data is stored in a file package, set this property to YES. Otherwise omit.

For more information about these keys, see CFBundleDocumentTypes in Information Property List Key Reference.

When you have finished entering the properties for a document type, The Document Types area of Xcode should look similar to the example in Figure 2-2.

An application could have multiple types of documents—for example, a word-processing application could have a type for regular (blank) documents and another type for pre-formatted documents. For each type, you need to go through the procedure given above .

Exporting the Document UTI

If you define a custom UTI for your documents, you must also export it. To export a document type in Xcode, start by clicking the Add button in the target’s Info settings and choose Add Exported UTI from the pop-up menu. Click the triangle next to Untitled to disclose the property fields and add the properties in Table 2-2.

Table 2-2  Properties for exporting a document UTI (UTExportedTypeDeclarations)

Key	Xcode field	Value and comments
UITypeIdentifier	Identifier	The custom document UTI, a string.
UTTypeConformsTo	Conforms to	The UTI that the custom document UTI conforms to. If the data representation is a file package, specify com.apple.package.
UTTypeDescription	Description	Description of the exported type (optional).
UTTypeTagSpecification	In “Additional exported UTI properties” table.	Create an array named public.filename-extension. Then add as items all extensions of the document file.

For more information about these keys, see CFBundleDocumentTypes in Information Property List Key Reference.

When you have finished entering the properties for a document type, The Exported UTIs area of Xcode should look similar to the example in Figure 2-3.