Implement a custom document file format to manage user interactions with files on different cloud storage providers.
SDKs
- iOS 11.3+
- Xcode 10.0+
Framework
- UIKit
Overview
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.
Configure a Custom File Format
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
in the additional exported UTI properties, the “particles” filename extension is bound to the new file format..filename-extension 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.
Preview Custom Documents
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
file of both extensions are configured with the data of the Particles file format.
Apply Best Practices
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
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 UIDocument
and UIDocument
are two different view controllers, each with their own purpose. Use the UIDocument
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 UIDocument
as the entry point in your application to let the users create new or choose an existing document.