diff --git a/user_manual/desktop/images/macosvfs-context-menu.jpg b/user_manual/desktop/images/macosvfs-context-menu.jpg new file mode 100644 index 00000000000..cd6a7fe663a Binary files /dev/null and b/user_manual/desktop/images/macosvfs-context-menu.jpg differ diff --git a/user_manual/desktop/images/macosvfs-file-locking.jpg b/user_manual/desktop/images/macosvfs-file-locking.jpg new file mode 100644 index 00000000000..e13d0b48f59 Binary files /dev/null and b/user_manual/desktop/images/macosvfs-file-locking.jpg differ diff --git a/user_manual/desktop/images/macosvfs-file-locking.png b/user_manual/desktop/images/macosvfs-file-locking.png deleted file mode 100644 index 78ed5f0c7ac..00000000000 Binary files a/user_manual/desktop/images/macosvfs-file-locking.png and /dev/null differ diff --git a/user_manual/desktop/images/macosvfs-file-sharing.jpg b/user_manual/desktop/images/macosvfs-file-sharing.jpg new file mode 100644 index 00000000000..a5f607601bb Binary files /dev/null and b/user_manual/desktop/images/macosvfs-file-sharing.jpg differ diff --git a/user_manual/desktop/images/macosvfs-file-sharing.png b/user_manual/desktop/images/macosvfs-file-sharing.png deleted file mode 100644 index 234a0db2ffd..00000000000 Binary files a/user_manual/desktop/images/macosvfs-file-sharing.png and /dev/null differ diff --git a/user_manual/desktop/images/macosvfs-finder-sidebar.jpg b/user_manual/desktop/images/macosvfs-finder-sidebar.jpg new file mode 100644 index 00000000000..d8a13ff1c06 Binary files /dev/null and b/user_manual/desktop/images/macosvfs-finder-sidebar.jpg differ diff --git a/user_manual/desktop/images/macosvfs-finder-sidebar.png b/user_manual/desktop/images/macosvfs-finder-sidebar.png deleted file mode 100644 index c6bccf74f4e..00000000000 Binary files a/user_manual/desktop/images/macosvfs-finder-sidebar.png and /dev/null differ diff --git a/user_manual/desktop/images/macosvfs-settings.jpg b/user_manual/desktop/images/macosvfs-settings.jpg new file mode 100644 index 00000000000..87e89c90ec8 Binary files /dev/null and b/user_manual/desktop/images/macosvfs-settings.jpg differ diff --git a/user_manual/desktop/images/macosvfs-settings.png b/user_manual/desktop/images/macosvfs-settings.png deleted file mode 100644 index 058e33cd06e..00000000000 Binary files a/user_manual/desktop/images/macosvfs-settings.png and /dev/null differ diff --git a/user_manual/desktop/images/macosvfs-sync-status-icons.png b/user_manual/desktop/images/macosvfs-sync-status-icons.png deleted file mode 100644 index 5a1515576be..00000000000 Binary files a/user_manual/desktop/images/macosvfs-sync-status-icons.png and /dev/null differ diff --git a/user_manual/desktop/macosvfs.rst b/user_manual/desktop/macosvfs.rst index f223e32ab0e..b8d1c8800f3 100644 --- a/user_manual/desktop/macosvfs.rst +++ b/user_manual/desktop/macosvfs.rst @@ -1,129 +1,117 @@ ========================== -macOS Virtual Files client +macOS Virtual Files Client ========================== -Virtual file-based synchronisation for Nextcloud desktop users is now -available on macOS. - -Unlike on Windows, virtual files support on macOS is provided by a -separate client version. This allows us to maintain the best possible -experience for classically-synced files, including sync status -integration and context menu actions, for users who want to keep using -this sync method. Just like our classic sync client, the macOS virtual -files client is released alongside the desktop client for Windows and -Linux, and will benefit from regular bug-fix and feature updates that -improve the user experience. +On macOS, our client can also seamlessly integrate Nextcloud files into macOS +as a file provider extension. Any newly configured Nextcloud account will have +the integration enabled by default. Supported features ------------------ -- Per-file local retention and eviction -- Intelligent local copy eviction -- Integration with Spotlight -- File previews within Finder for virtual files -- Support for Apple-specific formats such as app bundles and iWork - (Pages, Numbers, Keynote) bundles -- Remote file locking compatibility +- Keeping files or whole folders available offline +- Freeing up local disk space by evicting local copies without deleting items +- Intelligent and automatic local data eviction +- File previews within Finder for files which are not downloaded yet +- Support for Apple-specific formats, for example Pages, Numbers or Keynote bundles +- Support for server-side file locking (if supported by the connected server) - “Edit locally” support -- File sharing with other users -- Automatic synchronisation of remote changes -- More! +- Sharing with other users +- Automatic discovery of server-side changes .. note:: - To improve remote change detection, we recommend enabling the - ``notify_push`` app on your Nextcloud server. This app will notify - the desktop client of changes on the server as soon as they happen, - reducing the time it takes for the client to detect changes. This - will also eliminate the need for the desktop client to continuously - poll the server for changes. - -Installation and initial setup ------------------------------- - -The virtual files client is distributed as an installer package that -resembles the macOS classic sync client. The desktop client can be -installed by following the steps presented by the installer. + Due to technical limitations in macOS which are imposed by Apple, + it is not possible to have the Finder integration for classic sync folders + running in parallel to an enabled virtual files integration. + This means that item decorations and context menu options will be + unavailable for classic sync folders while the file provider extension is + enabled. -The virtual files desktop client is interchangeable with the classic -sync desktop client. This means your existing accounts and settings will -carry over to this client and vice-versa, should you ever decide to go -back to the classic sync client. This includes any pre-existing standard -sync folders, as the virtual files client also supports classic sync. - -.. note:: - Due to technical limitations in macOS we are unable to provide - integration in Finder for both classic sync folders and virtual file - sync folders. Classic sync folders in the virtual files client will - therefore not have Finder integrations such as sync state icons or - context menu actions. +Configuration +------------- +Virtual files-related settings can be adjusted on a per-account basis +via the Nextcloud desktop client's settings window. -Any existing or newly-configured accounts will have virtual files -automatically enabled. On macOS, each account’s virtual files live under -their own domain, separate from any pre-existing classic sync folders. -These domains can be found listed under the “Locations” group in the -Finder sidebar. +.. image:: images/macosvfs-settings.jpg + :alt: Screenshot of client settings for the file provider extension -.. image:: images/macosvfs-finder-sidebar.png - :alt: Finder sidebar showing virtual files domains +Here the integration into Finder can be enabled or disabled. -Upon first accessing one of these domains, the desktop client will being -to request information on remote files from the server. This first -synchronisation may take some time depending on the quantity of files -hosted on the server. +When disabling the file provider extension while still having unsynchronized +changes, macOS will save the unsynchronized items in a folder that is +automatically revealed after the integration is disabled. Finder integration ------------------ -The virtual files client has distinct Finder integrations that allow it -to more deeply and more natively integrate with the macOS file browser -than the classic sync client. +On macOS, remote storage like a Nextcloud files account appears like a +dedicated location in the Finder sidebar. The actual location of the +content on disk is defined by macOS. -Sync status indicators ----------------------- +.. image:: images/macosvfs-finder-sidebar.jpg + :alt: Finder sidebar showing a Nextcloud file provider domain -Similarly to classic sync client, the virtual files client displays -icons next to virtual files that indicate what their status is. +.. note:: + To accelerate server-side change detection, we recommend enabling the + ``notify_push`` app on your Nextcloud server. This app will notify + the desktop client of changes on the server as soon as they happen, + reducing the time it takes for changes to appear in Finder. + Otherwise the client needs to poll the server which will result in an + increased delay between a change on the server and its local visibility. -.. image:: images/macosvfs-sync-status-icons.png - :alt: Sync status icons for macOS virtual files +Sync status indicators +---------------------- -- *Cloud with arrow*: item or its children is virtual and is available - for local keeping -- *Cloud outline*: item is partially available locally -- *No icon*: item is available offline +Similar to classic synchronization folders, Finder displays status +indicators next to items. Unlike the custom indicators in classic +synchronization folders, these standardized indicators are provided by macOS to +ensure a consistent appearance across all cloud storage apps which a user may +use on their system. + +- *Cloud with downward arrow*: The item and its descendants are not downloaded + yet. They can be downloaded, assuming a network connection is available. +- *Outlined cloud*: The item is not fully uploaded yet in its current local + state. +- *Strikethrough cloud*: The item is excluded from synchronization. +- *Pie chart*: The item is currently being uploaded or downloaded, and the progress + is visualized. +- *Filled circle with downward arrow*: The item is available offline and will + be kept locally. +- *No icon*: The item is available offline and up to date. Context menu actions -------------------- -Control-clicking, two-finger clicking, or right-clicking on a Finder -item will provide the context menu, in which you may find several -entries provided by the virtual files client that allow you to use some -of the features supported by Nextcloud. These include: +.. image:: images/macosvfs-context-menu.jpg + :alt: Screenshot of Finder with an open context menu -- File locking (if supported by server) +The file provider extension also provides special Nextcloud features through +the context menu in Finder. -.. image:: images/macosvfs-file-locking.png - :alt: File locking UI for macOS virtual files +Keep Downloaded +^^^^^^^^^^^^^^^ -- File sharing (if supported by server) +Depending on the download state of a folder or file, the context menu will +offer to always keep an item downloaded or free up local disk space by +evicting the local copy while not actually deleting the item. This way, it +stays available any time for download from the server. -.. image:: images/macosvfs-file-sharing.png - :alt: File sharing UI for macOS virtual files +Locking +^^^^^^^ -Configuration -------------- +.. image:: images/macosvfs-file-locking.jpg + :alt: Screenshot of Finder showing the successful locking of a file -Virtual files-related settings can be adjusted on a per-account basis -via the Nextcloud desktop client’s settings window. +If the server supports file locking, the client will offer manual locking and +unlocking of files in Finder. -.. image:: images/macosvfs-settings.png - :alt: macOS virtual files settings +Sharing +^^^^^^^ -The virtual files section offers a number of options relevant to -virtual files interaction: +.. image:: images/macosvfs-file-sharing.jpg + :alt: Screenshot of Finder showing the share management -- Enable/disable virtual files for the target account -- Enable/disable fast sync -- Manage local storage usage and evict local copies -- Force the virtual files domain to check for updates +When the server supports sharing and the item is allowed to be shared, +then you can create new shares or manage existing shares for an item directly +from the context menu in Finder, as in the Nextcloud web interface. \ No newline at end of file