Document-Based Application Preflight

For most developers, making a document-based application doesn’t require much more effort than making an application that isn’t document based. The basic difference is that you must create a custom subclass of UIDocument and then manage a document through the phases of its runtime life, including its integration with iCloud storage. This chapter outlines those document-specific tasks performed by most applications and describes the general steps for creating and configuring a document-based application project in iOS.

What You Must Do to Make a Document-Based Application

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

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.

Figure 2-1  iOS looking up a document UTI from the extension of its file URL

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.

Figure 2-2  Specification of a document type in Xcode

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.

Figure 2-3  Exporting a custom document UTI in Xcode