File Previews
Relevant source files
The following files were used as context for generating this wiki page:
The File Previews system in the put.io iOS application provides a unified interface for rendering and interacting with various file types stored on the user's account. This system handles the transition from a file list view to a specialized viewer based on the file's MIME type or category, including folders, videos, audio, images, and PDF documents.
The architecture relies on a mix of protocol-oriented programming and dedicated view controllers. The FilePresenter protocol serves as the primary router, determining which specialized controller or manager should handle a specific PutioFile object.
Architecture and Routing
The routing logic is centralized within the FilePresenter protocol extension. When a user selects a file, the system evaluates its type and dispatches it to the appropriate navigation path.
The logic differentiates between remote files (via FilePresenter) and locally stored files (via DownloadedFilePresenter). While remote files require active network fetching, downloaded files are resolved to local file URLs before playback.
Sources: Putio/Features/Files/FilePresenter.swift:7-46, Putio/Features/Downloads/DownloadedFilePresenter.swift:9-25
Specialized Viewers
PDF Document Viewing
PDF files are handled by the PDFViewController, which utilizes Apple's PDFKit framework. The viewer implements a vertical, single-page continuous scrolling mode and handles the asynchronous download of the PDF data from the put.io servers.
- Logic Flow:
- Loads a local "blank.pdf" placeholder to initialize the
PDFView. - Constructs a download URL using the file's ID and the user's OAuth token.
- Initiates a
URLSessionDataTaskto fetch the binary data. - Instantiates a
PDFDocumentfrom the received data and updates the UI.
- Loads a local "blank.pdf" placeholder to initialize the
Sources: Putio/Features/Files/PDFViewController.swift:34-40, Putio/Features/Files/PDFViewController.swift:49-80
Media Playback (Video and Audio)
Media files are routed through the MediaPlaybackManager. For videos, the system checks for needConvert status. If a video is not in a native iOS-compatible format (like MP4), it prompts the user through a conversion view before playback starts.
Sources: Putio/Features/Files/FilePresenter.swift:15-25, Putio/Features/Files/FilePresenter.swift:54-56
Data Models and Types
The system categorizes files into specific types to determine preview behavior. These types are derived from the PutioFile object provided by the SDK.
| File Type | Preview Handler | Action / Component |
|---|---|---|
.folder | FilesViewController | Pushes a new file list for the directory |
.video | MediaPlaybackManager | Local playback or Chromecast casting |
.audio | MediaPlaybackManager | Local audio playback |
.image | ImageViewController | Renders image from Image.storyboard |
.pdf | PDFViewController | Renders PDF via PDFKit |
Sources: Putio/Features/Files/FilePresenter.swift:9-41, Putio/Features/Downloads/DownloadModel.swift:13-16
Sequence of a PDF Preview Request
The following diagram illustrates the lifecycle of a PDF preview request from the initial user interaction to the final rendering.
Error Handling in Previews
The preview system includes robust error handling, particularly for network failures or inaccessible local files.
- Remote Failures: In
PDFViewController, if a download fails, an alert is presented with a "Go Back" action that pops the view controller. - Local Failures: In
DownloadedFilePresenter, if a file cannot be reached on disk (potentially due to OS cleanup or corruption), the system offers a "Re-download" option. - Unsupported Types: Files that do not match known preview categories trigger a standard
UIAlertControllerinforming the user of the limitation.
Sources: Putio/Features/Files/PDFViewController.swift:87-100, Putio/Features/Downloads/DownloadedFilePresenter.swift:27-41, Putio/Features/Files/FilePresenter.swift:42-45