Building an app with a document browser

At a glance

Project structure

Document Browser/
├── BrowserSceneDelegate.swift
├── AppDelegate.swift
├── DocumentBrowserViewController.swift
├── TextDocument.swift
├── TextDocumentViewController.swift
└── Base.lproj/
    ├── Main.storyboard
    └── LaunchScreen.storyboard

Structure observations

• Browser routing, document persistence, and editing UI are separate source-file roles.
• The storyboard supplies the browser root and navigation/editor hierarchy; the browser injects the opened TextDocument.
• AppDelegate contains application lifecycle plumbing, not the feature’s composition logic.

Overall architecture

flowchart LR
    FileIntent["Scene URL context"] --> Scene["BrowserSceneDelegate"]
    Scene --> Browser["DocumentBrowserViewController"]
    Browser -->|"create / import / pick"| Document["TextDocument : UIDocument"]
    Browser -->|"instantiate and inject"| Editor["TextDocumentViewController"]
    Browser --> Transition["UIDocumentBrowserTransitionController"]
    Editor -->|"edit + updateChangeCount"| Document
    Document -->|"weak events"| Editor
    Document --> Storage["UTF-8 file contents"]

Reference code

Document Browser/DocumentBrowserViewController.swift:128 — the browser composes the open-document session, connects progress to the transition, injects the model, and presents only after a successful open.

transitionController = transitionController(forDocumentAt: documentURL)

let doc = TextDocument(fileURL: documentURL)
transitionController!.targetView = documentViewController.textView
transitionController!.loadingProgress = doc.loadProgress

documentViewController.document = doc
documentViewController.document.open { success in
    if success {
        self.transitionController!.loadingProgress = nil
        self.present(docNavController, animated: true)
    }
}

Interpretation

The browser is the composition and presentation boundary, while TextDocument is the persistence/state boundary. The editor does not read files itself; it mutates the document and tells UIDocument that a change occurred.

Ownership and state

classDiagram
    BrowserSceneDelegate o-- DocumentBrowserViewController : finds root
    DocumentBrowserViewController *-- UIDocumentBrowserTransitionController : current transition
    DocumentBrowserViewController --> TextDocument : creates
    DocumentBrowserViewController --> TextDocumentViewController : injects document
    TextDocumentViewController o-- TextDocument : strong document reference
    TextDocument --> TextDocumentViewController : weak delegate
    TextDocument *-- Progress : loadProgress
    TextDocument *-- NotificationToken : document state observer
    TextDocumentViewController *-- NotificationToken : keyboard observers

Ownership evidence

Document Browser/TextDocument.swift:28 — the document owns text/progress and observer state, but deliberately keeps its callback recipient weak.

public var text = "" {
    didSet {
        delegate?.textDocumentUpdateContent(self)
    }
}

public weak var delegate: TextDocumentDelegate?
public var loadProgress = Progress(totalUnitCount: 10)

private var docStateObserver: Any?
private var transfering: Bool = false

Class and protocol design

TextDocumentDelegate is genuine protocol-oriented design: the model reports semantic document events without importing editor details. The sample has one concrete conformer, so the value is separation and weak ownership rather than multiple implementations.

Access control

Reference code

Document Browser/BrowserSceneDelegate.swift:47 — the public scene callbacks funnel both connection-time and later URL events into one private router.

private func openURLContext(_ urlContext: UIOpenURLContext) {
    guard let documentBrowserViewController =
            window?.rootViewController as? DocumentBrowserViewController else {
        fatalError("*** The root view is not a document browser ***")
    }

    documentBrowserViewController.revealDocument(
        at: urlContext.url,
        importIfNeeded: !urlContext.options.openInPlace
    ) { revealedURL, error in
        // Resolve the URL, then call presentDocument(at:).
    }
}

Logic ownership and placement

Design patterns

Naming conventions

• Types name framework roles directly: DocumentBrowserViewController, TextDocument, and TextDocumentViewController.
• Callback methods use the subject-event form: textDocumentTransferBegan and textDocumentSaveFailed.
• Commands use explicit verbs and objects: presentDocument, openURLContext, resolveDocumentConflict, and setupNotifications.
• State names are concrete (loadProgress, docStateObserver); transfering is source spelling and represents a Boolean phase flag.

Architecture takeaways

• Put file-format and document-state invariants in the UIDocument subclass, not the editor.
• Let the document browser construct each open-session graph because it owns URLs, transitions, and presentation.
• Use a weak, semantic delegate to keep the document independent of concrete UI.
• Keep lifecycle flags and observer tokens private; expose only the model/progress surface collaborators need.

Source map

• Official Apple documentation