About the Cocoa Document Architecture

Explains how to create document-based applications using the Cocoa document architecture on OS X.

At a Glance

Document-based apps handle multiple documents, each in its own window, and often display more than one document at a time. Although these apps embody many complex behaviors, the document architecture provides many of their capabilities “for free,” requiring little additional effort in design and implementation.

The Model-View-Controller Pattern Is Basic to a Document-Based App

The Cocoa document architecture uses the Model-View-Controller (MVC) design pattern in which model objects encapsulate the app’s data, view objects display the data, and controller objects act as intermediaries between the view and model objects. A document, an instance of an NSDocument subclass, is a controller that manages the app’s data model. Adhering to the MVC design pattern enables your app to fit seamlessly into the document architecture.

Relevant Chapters: Designing a Document-Based App and The Classes That Support Document-Based Apps

Xcode Supports Coding and Configuring Your App

Taking advantage of the support provided by Xcode, including a document-based application template and interfaces for configuring app data, you can create a document-based app without having to write much code. In Xcode you design your app’s user interface in a graphical editor, specify entitlements for resources such as the App Sandbox and iCloud, and configure the app’s property list, which specifies global app keys and other information, such as document types.

Relevant Chapter: App Creation Process Overview

You Must Subclass NSDocument

Document-based apps in Cocoa are built around a subclass of NSDocument that you implement. In particular, you must override one document reading method and one document writing method. You must design and implement your app’s data model, whether it is simply a single text-storage object or a complex object graph containing disparate data types. When your reading method receives a request, it takes data provided by the framework and loads it appropriately into your object model. Conversely, your writing method takes your app’s model data and provides it to the framework’s machinery for writing to a document file, whether it is located only in your local file system or in iCloud.

Relevant Chapters: Creating the Subclass of NSDocument and The Classes That Support Document-Based Apps

NSDocument Provides Core Behavior and Customization Opportunities

The Cocoa document architecture provides your app with many built-in features, such as autosaving, asynchronous document reading and writing, file coordination, and multilevel undo support. In most cases, it is trivial to opt-in to these behaviors. If your app has particular requirements beyond the defaults, the document architecture provides many opportunities for extending and customizing your app’s capabilities through mechanisms such as delegation, subclassing and overriding existing methods with custom implementations, and integration of custom objects.

Relevant Chapters: Core App Behaviors and Alternative Design Considerations

Prerequisites

Before you read this document, you should be familiar with the information presented in Mac App Programming Guide .

About the Cocoa Document Architecture

At a Glance

Prerequisites

See Also