Building an App Based on the Document Browser View Controller

Users can store their documents on different cloud storage providers, such as iCloud Drive. An app based on the document browser view controller allows users to browse and access their documents no matter where they are stored. In addition, the document browser view controller lets users create new documents, and acts as a springboard into your application’s main user interface.

This example illustrates how to use the document browser view controller. It registers a custom file format called Particles in the system, and allows the user to create new Particles documents on any of the user’s activated file providers. When the user chooses a document, the app presents an editor view, in which the document contents can be modified. Once the user is done with the modifications, the document is saved, and the user returns to the document browser view controller.

The app also demonstrates proper file handling using the UIDocument class, and how to build a Quick Look preview and thumbnail extension for the Particles file format. Finally, this sample illustrates how to customize the appearance of the document browser view controller, the custom browser actions, and the presentation of document view controllers with a custom zoom transition.

This sample introduces a custom file format to the system called Particles.

• In order to register “Particles” as a new file format system-wide, the Particles app configures an exported UTI in the Info panel of the target. Using the public.filename-extension in the additional exported UTI properties, the “particles” filename extension is bound to the new file format.

• The UTI information configures the supported document types of the Particles app in the same panel to link the Particles app with the Particles file format.

The sample provides two Quick Look extensions:

• The ParticlesPreview extension, which generates preview views.

• The ParticlesThumbnails extension, which generates thumbnails for files of the newly registered file format.

In order for Quick Look to choose the extensions when dealing with Particles documents, the Info.plist file of both extensions are configured with the data of the Particles file format.

An important best practice to follow is to use the UIDocumentBrowserViewController with UIDocument. The UIDocument class helps you to provide the commonly expected features of a document-based application, such as saving and loading documents, asynchronous reading and writing of data, versioning with conflict detection, and much more. Additionally, UIDocument provides the automatic coordinated reading and writing needed to avoid problems when accessing a file on disk that could be read or written by other processes at the same time. If you need to access a file manually, make sure to use file coordination in order to not risk data loss or other severe data inconsistencies.

You should also avoid listing high-level UTIs in the document types configured for your application. Only list the UTIs that your application can actually handle. Otherwise, the document browser view controller will display files of unsupported file formats, for example in the Recents section or in the search results, that are irrelevant to the user.

Make sure to configure the document types and the exported and imported UTIs in your application’s Info.plist file correctly. Dynamic sections such as Recent Documents, collections of tagged documents, and the popover of your application need this information to work properly.

Finally, it’s important to know when to use the picker view controller. The UIDocumentPickerViewController and UIDocumentBrowserViewController are two different view controllers, each with their own purpose. Use the UIDocumentPickerViewController to allow the user to quickly pick an existing file to, e.g., insert into the currently opened document, or to export a document to a certain location. Use the UIDocumentBrowserViewController as the entry point in your application to let the users create new or choose an existing document.