App Frameworks #WWDC15

Building Document Based Apps

Session 234

Mike Hess Software Engineer

Johannes Fortmann Senior Software Engineer

© 2015 Apple Inc. All rights reserved. Redistribution or public display not permitted without written permission from Apple.
What’s a Document Based App?
General characteristics
What’s a Document Based App?
General characteristics

Document is a single standalone entity

What’s a Document Based App?
General characteristics

Document is a single standalone entity

Document based app manages a list of documents
What’s a Document Based App?
General characteristics

Document is a single standalone entity

Document based app manages a list of documents
Presents to user to edit etc
What’s a Document Based App?
General characteristics

Document is a single standalone entity

Document based app manages a list of documents
Presents to user to edit etc
What’s a Document Based App?
General characteristics

Document is a single standalone entity

Document based app manages a list of documents
Presents to user to edit etc
What’s a Document Based App?
General characteristics

Document is a single standalone entity

Document based app manages a list of documents
Presents to user to edit etc
Building a Document Browser
Document Browser
Components
Document Browser
Components

List documents in a meaningful way

Document Browser
Components

List documents in a meaningful way

Use thumbnails for document visibility
Document Browser
Components

List documents in a meaningful way

Use thumbnails for document visibility
Show external documents
Document Browser
Components

List documents in a meaningful way

Use thumbnails for document visibility
Show external documents
Store recently accessed documents
Discovering Documents
Document Browser
Discovering documents
Document Browser
Discovering documents

NSFileManager results are incomplete

Document Browser
Discovering documents

NSFileManager results are incomplete

• iCloud content isn’t always available locally
Document Browser
Discovering documents

NSFileManager results are incomplete

• iCloud content isn’t always available locally
• External documents not included
Document Browser
Discovering documents
Your App’s Container

Doc Doc
1 2

Doc
3

Doc Doc
4 5

Other App’s Container

Document Browser
Discovering documents
Your App’s Container

NSURL 1 Doc Doc

1 2

NSURL 2
Doc
3

Doc Doc
4 5

NSFileManager APIs
Other App’s Container
Document Browser
Discovering documents
Your App’s Container

NSURL 1 Doc Doc

1 2

NSURL 2
Doc
3

Doc Doc
4 5

NSFileManager APIs
Other App’s Container
Document Browser
Discover documents with NSMetadataQuery
Your App’s Container

Doc Doc
1 2

Doc
3

Doc Doc
4 5

Other App’s Container

Document Browser
Discover documents with NSMetadataQuery
Your App’s Container

NSMetadataItem 1 Doc Doc

1 2

NSMetadataItem 2
Doc
3
NSMetadataItem 3

NSMetadataItem 4 Doc Doc

4 5

NSMetadataQuery APIs
Other App’s Container
Document Browser
Discover documents with NSMetadataQuery
Your App’s Container

NSMetadataItem 1 Doc Doc

1 2

NSMetadataItem 2
Doc
3
NSMetadataItem 3

NSMetadataItem 4 Doc Doc

4 5

NSMetadataQuery APIs
Other App’s Container
Document Browser
NSMetadataQuery
Your App’s Container

Doc Doc
1 2

Doc
3

Doc Doc
4 5

Other App’s Container

Document Browser
NSMetadataQuery
Your App’s Container

Doc Doc
1 2

Doc
3

Doc Doc
4 5

Create NSMetadataQuery
Other App’s Container
Document Browser
NSMetadataQuery
Your App’s Container

NSMetadataItem 1 Doc Doc

1 2

NSMetadataItem 2
Doc
3
NSMetadataItem 3

NSMetadataItem 4 Doc Doc

4 5

Initial Gather Phase

Other App’s Container
Document Browser
NSMetadataQuery
Your App’s Container

NSMetadataItem 1 Doc Doc

1 2

NSMetadataItem 2
Doc
3
NSMetadataItem 3

NSMetadataItem 4 Doc Doc

4 5

List Initial Documents

Other App’s Container
Document Browser
NSMetadataQuery
Your App’s Container

NSMetadataItem 1 Doc Doc

1 2

NSMetadataItem 2
Doc Doc
3 6
NSMetadataItem 3

NSMetadataItem 4 Doc Doc

4 5
NSMetadataItem 6

Update Notifications
Other App’s Container
Document Browser
NSMetadataQuery
Your App’s Container

NSMetadataItem 1 Doc Doc

1 2

NSMetadataItem 2
Doc Doc
3 6
NSMetadataItem 3

NSMetadataItem 4 Doc Doc

4 5
NSMetadataItem 6

Compute Animations
Other App’s Container
Document Browser
NSMetadataQuery
Your App’s Container

NSMetadataItem 1 Doc Doc

1 2

NSMetadataItem 2
Doc Doc
3 6
NSMetadataItem 3

NSMetadataItem 4 Doc Doc

4 5
NSMetadataItem 6

Display Updated UI
Other App’s Container
Loading Thumbnails
Document Browser
Thumbnails
Document Browser
Thumbnails

Gives visual context to users

Document Browser
Thumbnails

Gives visual context to users

Generated automatically for certain documents
Document Browser
Loading thumbnails for display

Main Queue

Background
Queue
Document Browser
Loading thumbnails for display

Main Queue Load Cell

Background
Queue
Document Browser
Loading thumbnails for display

Main Queue Load Cell

Background
Fetch Thumbnail
Queue
Document Browser
Loading thumbnails for display

Display Cell
Main Queue Load Cell
With Placeholder

Background
Fetch Thumbnail
Queue
Document Browser
Loading thumbnails for display

Display Cell
Main Queue Load Cell Reload Cell
With Placeholder

Background
Fetch Thumbnail
Queue
Document Browser
Loading thumbnails for display

Display Cell Display Cell

Main Queue Load Cell Reload Cell
With Placeholder With Thumbnail

Background
Fetch Thumbnail
Queue
Managing a Recents List
Recents List
Storing recently-used items list
Recents List
Storing recently-used items list

Give easy access to recently used documents

Recents List
Storing recently-used items list

Give easy access to recently used documents

Storing NSURLs isn’t robust
Recents List
Storing recently-used items list

Your App’s Container

Doc
1
NSURL
Recents List
Storing recently-used items list

Your App’s Container

NSURL
Doc
1
Recents List
Storing recently-used items list

Your App’s Container

NSURL
Doc
1
Recents List
Use security scoped bookmarks

Your App’s Container

Doc
1
Bookmark
Recents List
Use security scoped bookmarks

Your App’s Container

Bookmark
Doc
1
Recents List
Use security scoped bookmarks

Your App’s Container

Bookmark
Doc
1
Demo
Document Browser Summary
Document Browser Summary

Discover documents using NSMetadataQuery

Document Browser Summary

Discover documents using NSMetadataQuery

Display thumbnails
Document Browser Summary

Discover documents using NSMetadataQuery

Display thumbnails
Store recent list using bookmarks
Document Access
File coordination and presentation
Document Access
File coordination and presentation

Multiple applications can read or write documents

Document Access
File coordination and presentation

Multiple applications can read or write documents

• Your app, other apps, iCloud Drive…
Document Access
File coordination and presentation
Document Access
File coordination and presentation

Your App
Document Access
File coordination and presentation

Write
Your App
Document Access
File coordination and presentation

Write Write
Your App
Document Access
File coordination and presentation

Write Write
Your App

Other App
Document Access
File coordination and presentation

Write Write
Your App

Read
Other App
Document Access
File coordination and presentation

Write Write
Your App

Inconsistent
Read Read
Other App
Document Access
File coordination and presentation

Write Write
Your App

Inconsistent
Read Read Stale Display
Other App
Document Access
File coordination and presentation

Write Write
Your App

Inconsistent Read Stale Display

Other App
Document Access
File coordination and presentation

NSFileCoordination: Reader/writer lock

Write Write
Your App

Inconsistent Read Stale Display

Other App
Document Access
File coordination and presentation

NSFileCoordination: Reader/writer lock

Write Write
Your App

Coordinated Read Stale Display

Other App
Document Access
File coordination and presentation

NSFileCoordination: Reader/writer lock

NSFilePresenter: Notification mechanism

Write Write
Your App

Coordinated Read Stale Display

Other App
Document Access
File coordination and presentation

NSFileCoordination: Reader/writer lock

NSFilePresenter: Notification mechanism

Write Write
Your App

Coordinated Read Update

Other App
Document Management
Creating new documents
Document Management
Creating new documents

Goals
Document Management
Creating new documents

Goals
• Consistent
Document Management
Creating new documents

Goals
• Consistent
• Up-to-date
Document Management
Creating new documents

Goals
• Consistent
• Up-to-date

Your App
Document Management
Creating new documents

Goals
• Consistent
• Up-to-date

Your App Document Creation

Document Management
Creating new documents

Goals
• Consistent
• Up-to-date

Your App Document Creation Display in UI

Document Management
Creating new documents

Goals
• Consistent
• Up-to-date

Your App Document Creation Display in UI

Document Management
Creating new documents

Coordinated operations update directly!

Your App Document Creation Display in UI

Document Management
Creating new documents

Coordinated operations update directly!

Your App Document Creation Display in UI

Document Management
Creating new documents

Main Document Creation

thread
Document Management
Creating new documents

Main Document Creation

thread Main Thread Blocked
Document Management
Creating new documents

Coordinated operations can block

Main Document Creation

thread Main Thread Blocked
Document Management
Creating new documents

Coordinated operations can block

Use background queue

Main Document Creation

thread Main Thread Blocked

Background
queue
Document Management
Creating new documents

Coordinated operations can block

Use background queue

Main User action

thread

Background
Document Creation
queue
Document Management
Creating new documents

Coordinated operations can block

Use background queue

Main User action Display in UI

thread

Background
Document Creation
queue
Document Management
Creating new documents

Coordinated operations can block

Use background queue
Deletion same

Main User action Display in UI

thread

Background
Document Creation
queue
Loading and Displaying
Reading documents

UIDocument for reading and writing

Main
thread

Background
queue
Loading and Displaying
Reading documents

UIDocument for reading and writing

Main
open
thread

Background
queue
Loading and Displaying
Reading documents

UIDocument for reading and writing

Main
open
thread

Background Coordinated Read

queue
Loading and Displaying
Reading documents

UIDocument for reading and writing

Main
open
thread

Background Coordinated Read

queue loadFromContents()
Loading and Displaying
Reading documents

UIDocument for reading and writing

Main
open completion
thread

Background Coordinated Read

queue loadFromContents()
Loading and Displaying
Reading documents

Main
open completion
thread

Background Coordinated Read

queue loadFromContents()
Loading and Displaying
Reading documents

Reading may trigger a download

Main
open completion
thread

Background Coordinated Read

queue loadFromContents()
Loading and Displaying
Reading documents

Reading may trigger a download

NSProgressReporting

Main
open completion
thread

Background Coordinated Read

queue loadFromContents()
Loading and Displaying
Reading documents

Reading may trigger a download

NSProgressReporting

Main
open State Change completion
thread

Background Coordinated Read

queue loadFromContents()
Loading and Displaying
Reading documents

Reading may trigger a download

NSProgressReporting

Main
open State Change Progress display completion
thread

Background Coordinated Read

queue loadFromContents()
Loading and Displaying
Reading documents

Reading may trigger a download

NSProgressReporting

Main
open State Change Progress display State Change completion
thread

Background Coordinated Read

queue loadFromContents()
Loading and Displaying
Writing documents

Background
queue
Loading and Displaying
Writing documents

Like reading: File coordination, background queue

Background Coordinated Write

queue contentsForType()
Loading and Displaying
Writing documents

Like reading: File coordination, background queue

Thumbnails

Background Coordinated Write

queue contentsForType() fileAttributesToWriteToURL()
Loading and Displaying
Writing documents

Like reading: File coordination, background queue

Thumbnails
Called on a background queue!

Background Coordinated Write

queue contentsForType() fileAttributesToWriteToURL()
Loading and Displaying
Writing documents

Like reading: File coordination, background queue

Thumbnails
Called on a background queue!
• No UIViews!

Background Coordinated Write

queue contentsForType() fileAttributesToWriteToURL()
Opening from Other Apps
iOS 8—Open by copy
Opening from Other Apps
iOS 8—Open by copy

Apps don’t have access to each others documents

Opening from Other Apps
iOS 8—Open by copy

Apps don’t have access to each others documents

• Opening using the UIDocumentInteractionController causes a copy

Your App’s Container Other App's Container

Opening from Other Apps
iOS 8—Open by copy

Apps don’t have access to each others documents

• Opening using the UIDocumentInteractionController causes a copy

Your App’s Container Other App's Container

Doc 1 Doc 1
_v1 _v2
Opening from Other Apps
iOS 8—Open by copy

Apps don’t have access to each others documents

• Opening using the UIDocumentInteractionController causes a copy
• Proliferation of copies

Your App’s Container Other App's Container

Doc 1 Doc 1
 Doc 1

_v1 _v3 _v2
Opening from Other Apps
iOS 9—Open in place

Your App’s Container Other App's Container

Opening from Other Apps
iOS 9—Open in place

Access to other app’s containers granted by document interaction controller

Your App’s Container Other App's Container

Doc 1
_v1
Opening from Other Apps
iOS 9—Open in place

Access to other app’s containers granted by document interaction controller

Your App’s Container Other App's Container

Doc 1 Doc 1
_v1 _v1
Opening from Other Apps
iOS 9—Open in place

Access to other app’s containers granted by document interaction controller

• Includes files opened from the iCloud Drive app and Spotlight

Your App’s Container Other App's Container

Doc 1 Doc 1
_v1 _v1
Opening from Other Apps
iOS 9—Open in place

Access to other app’s containers granted by document interaction controller

• Includes files opened from the iCloud Drive app and Spotlight
• UIDocumentMenuViewController, UIDocument

Your App’s Container Other App's Container

Doc 1 Doc 1
_v1 _v1
Opening from Other Apps
Supporting open in place
Opening from Other Apps
Supporting open in place

Support is simple
Opening from Other Apps
Supporting open in place

Support is simple
• LSSupportsOpeningDocumentsInPlace key in Info.plist
Opening from Other Apps
Supporting open in place

Support is simple
• LSSupportsOpeningDocumentsInPlace key in Info.plist
• Adopt new delegate method
Opening from Other Apps
Handling open in place versus copy

func application(app: UIApplication, openURL url: NSURL, 


sourceApplication: String?, annotation: AnyObject) -> Bool {
let newURL = copyFileToContainer(url)
documentBrowser.openDocumentAtURL(newURL)
return true
}
Opening from Other Apps
Handling open in place versus copy

func application(app: UIApplication, openURL url: NSURL, options: [String:

AnyObject]) -> Bool {
let newURL = copyFileToContainer(url)
documentBrowser.openDocumentAtURL(newURL)
return true
}
Opening from Other Apps
Handling open in place versus copy

func application(app: UIApplication, openURL url: NSURL, options: [String:

AnyObject]) -> Bool {
guard let shouldOpenInPlace =
options[UIApplicationOpenURLOptionsOpenInPlaceKey] as? Bool else {
return false
}

let newURL = copyFileToContainer(url)

documentBrowser.openDocumentAtURL(newURL)

return true
}
Opening from Other Apps
Handling open in place versus copy

func application(app: UIApplication, openURL url: NSURL, options: [String:

AnyObject]) -> Bool {
guard let shouldOpenInPlace =
options[UIApplicationOpenURLOptionsOpenInPlaceKey] as? Bool else {
return false
}

let newURL = shouldOpenInPlace ? url : copyFileToContainer(url)

documentBrowser.openDocumentAtURL(newURL)

return true
}
Opening from Other Apps
Handling open in place versus copy

func application(app: UIApplication, openURL url: NSURL, options: [String:

AnyObject]) -> Bool {
guard let shouldOpenInPlace =
options[UIApplicationOpenURLOptionsOpenInPlaceKey] as? Bool else {
return false
}

let newURL = shouldOpenInPlace ? url : copyFileToContainer(url)

documentBrowser.openDocumentAtURL(newURL)

return true
}
Summary
Summary

Make your app performant, responsive, and beautiful

Summary

Make your app performant, responsive, and beautiful

• NSMetadataQuery
Summary

Make your app performant, responsive, and beautiful

• NSMetadataQuery
• Bookmarks
Summary

Make your app performant, responsive, and beautiful

• NSMetadataQuery
• Bookmarks
• Progress
Summary

Make your app performant, responsive, and beautiful

• NSMetadataQuery
• Bookmarks
• Progress
• Open-in-place
More Information

Sample Code

http://developer.apple.com/library/
prerelease/ios/samplecode/ShapeEdit

Technical Support

Apple Developer Forums

http://developer.apple.com/forums

iCloud Documentation

http://developer.apple.com/icloud

Related Sessions

Building a Document Based App Session 234 WWDC14