---

Document Packages

If your document file formats are getting too complex to manage because of several different types of data, you might consider adopting a package format for your documents. Document packages give the illusion of a single document to users but provide you with more flexibility in how you store the document data internally. Especially if you use several different types of standard data formats, such as JPEG, GIF, or XML, document packages make accessing that data much easier.

Contents:

Defining Your Document Directory Structure
Registering Your Document Type
Accessing Your Document Contents

Defining Your Document Directory Structure

Apple does not prescribe any specific structure for document packages. The contents and organization of the package directory are left to you. You are encouraged, however, to create either a flat directory structure or use the framework bundle structure, which involves placing your files in a top-level Resources subdirectory. (For more information about the bundle structure of frameworks, see Framework Programming Guide.)

Registering Your Document Type

To register a document as a package, you must modify the document type information in your application’s information property list (Info.plist) file. The CFBundleDocumentTypes key stores information about the document types your application supports. For each document package type, include the LSTypeIsPackage key with an appropriate value. The presence of this key tells the Finder and Launch Services to treat directories with the given file extension as a package. See “Property List Key Reference” in Runtime Configuration Guidelines for more information about Info.plist keys.

Document packages should always have an extension to identify them—even though that extension may be hidden by the user. The extension allows the Finder to identify your document directory and treat it as a package. You should never associate a document package with a MIME type or 4-byte OS type.

Accessing Your Document Contents

There are several ways to access the contents of a document package. Because a document package is a directory, you can access the document's contents using any appropriate file-system routines. If you use a bundle structure for your document, you can also use the NSBundle or CFBundle routines. Use of a bundle structure is especially appropriate for documents that store multiple localizations.

If your document package uses a flat directory structure or contains a fixed set of content files, you might find using file-system routines faster and easier than using NSBundle or CFBundle. If the contents of your document can fluctuate, you should consider using a bundle structure and NSBundle or CFBundle to simplify the dynamic discovery of files inside your document.

If you are creating a Cocoa application, you must also remember to customize the way your NSDocument subclass loads the contents of the document package. The traditional technique of using the loadDataRepresentation:ofType: and dataRepresentationOfType: methods to read and write data are intended for a single file document. To handle a document package, you must use the readFromFile:ofType: and writeToFile:ofType: methods or use an NSFileWrapper object instead. For information about reading and writing document data from your NSDocument subclass, see Document-Based Applications Overview.

---