File Management & Browsing
Relevant source files
The following files were used as context for generating this wiki page:
- Putio/Features/Files/FilesViewController.swift
- Putio/Common/API/PutioSDK.swift
- Putio/Features/Files/FilesViewController+Selection.swift
- Putio/Features/Files/FilesViewController+Navigation.swift
- Putio/Features/Files/MoveFilesViewController.swift
- Putio/Features/Files/FilesRootViewController.swift
- Putio/Features/Files/FilesViewController+TableView.swift
The File Management & Browsing system is a core module of the putio-ios application, responsible for navigating the user's cloud storage, searching for content, and performing file-level operations such as moving, deleting, and renaming. It utilizes a UIKit-based architecture, heavily relying on UITableView for display and a specialized SDK wrapper for remote communication.
This system provides a hierarchical browsing experience, starting from the "Your Files" root directory and allowing deep navigation into folder structures. It integrates advanced selection modes for batch operations and utilizes a state machine to handle various network and data states, ensuring a responsive user interface even during intermittent connectivity.
Core Architecture and Data Flow
The architecture follows a Model-View-ViewModel (MVVM) pattern supplemented by delegates and extensions to handle specific UI responsibilities. The FilesViewController serves as the primary base class, while FilesRootViewController extends it to provide root-specific functionality like searching.
State Management
The system implements StatefulViewController to manage the UI based on the data retrieval status. The state machine transitions between several predefined views to reflect the current context.
| State | Description | UI Component |
|---|---|---|
loading | Data is being fetched from the API. | LoaderView |
empty | The current folder contains no files. | EmptyStateView |
offline | No network connection is detected. | OfflineStatusView |
404 | The requested file or folder does not exist. | EmptyStateView (Customized) |
error | A general API or decoding error occurred. | EmptyStateView (Oops) |
none | Data has been successfully loaded and is ready for display. | UITableView |
Sources: Putio/Features/Files/FilesViewController.swift:85-110
File Retrieval Flow
Data fetching is triggered during viewDidLoad, on pull-to-refresh, or when network reachability changes. The PutioSDK provides an asynchronous interface to the getFiles endpoint.
File Operations and Multi-Selection
The system supports both single-file contextual actions and batch operations through a dedicated editing mode.
Selection Workflow
When a user enters editing mode via the "Select" action, the navigation bar and toolbar transform to support batch processing.
- Select All / Deselect All: Dynamically updates based on the current visible file list.
- Batch Delete: Prompts for confirmation unless "Move to Trash" is enabled in user settings.
- Batch Move: Initiates the
MoveFilesViewControllerflow with an array of selected file IDs.
Sources: Putio/Features/Files/FilesViewController+Selection.swift:10-40, Putio/Features/Files/FilesViewController+Selection.swift:70-85
Contextual Actions (Swipe)
Individual files support trailing swipe actions for quick management. The available actions depend on whether the file is shared or owned by the user.
| Action | Visibility | Purpose |
|---|---|---|
| Delete / Trash | Owned Files | Moves file to trash or permanently deletes it. |
| More | Owned Files | Accesses Rename and Move sub-actions. |
| Copy | Shared Files | Copies a shared file to the user's own storage. |
| Download | All Media | Initiates VideoDownloadManager or AudioDownloadManager. |
Sources: Putio/Features/Files/FilesViewController+TableView.swift:135-155
Moving Files and Folders
Moving content involves a specialized navigation stack handled by MoveFilesViewController. This controller allows users to traverse their folder hierarchy to pick a destination.
Move Logic Sequence
The following diagram illustrates the interaction between the file listing and the move selection UI:
Search and Filtering
Root-level browsing includes a search interface integrated into the navigation bar. FilesRootViewController manages search states and utilizes a debouncer to prevent excessive API calls while typing.
- Search Debouncing: A delay of 0.2 seconds is enforced before triggering
performSearch. - Mode Transition: The UI switches between
.files(standard browsing) and.search(keyword-based results). - Cached State: When entering search, the current file list is cached to allow instant restoration when search is cancelled.
Sources: Putio/Features/Files/FilesRootViewController.swift:5-15, Putio/Features/Files/FilesRootViewController.swift:90-130
Technical Implementation Details
API Integration
The PutioSDK wrapper simplifies interactions with the backend. Key methods used for management include:
// Putio/Common/API/PutioSDK.swift
func getFiles(parentID: Int, query: PutioFilesListQuery, completion: ...)
func createFolder(name: String, parentID: Int, completion: ...)
func deleteFiles(fileIDs: [Int], _ completion: ...)
func moveFiles(fileIDs: [Int], parentID: Int, _ completion: ...)
func renameFile(fileID: Int, name: String, _ completion: ...)
Sources: Putio/Common/API/PutioSDK.swift:65-110
Sorting Logic
Sorting is performed server-side. Users can toggle between various keys (NAME, SIZE, DATE, MODIFIED, TYPE, WATCH). If the same key is selected twice, the sort direction (ASC/DESC) is toggled.
Sources: Putio/Features/Files/FilesViewController.swift:174-192
Summary
The File Management & Browsing system provides a robust interface for cloud file manipulation. By separating concerns into extensions for table view logic, navigation, and multi-selection, the codebase maintains clarity despite the complexity of stateful cloud interactions. The use of a centralized SDK ensures consistent error handling and data synchronization across different browsing modes (root, subfolder, and search).