From 9ceef69c238fd01330912bcef0da2d76b11576c6 Mon Sep 17 00:00:00 2001 From: Julien Veyssier Date: Fri, 14 Apr 2023 16:46:23 +0200 Subject: [PATCH] add reference management admin doc (link previews + smart picker) Signed-off-by: Julien Veyssier --- admin_manual/contents.rst | 5 ++- admin_manual/office/index.rst | 2 +- admin_manual/reference/index.rst | 26 +++++++++++ admin_manual/reference/link_previews.rst | 56 ++++++++++++++++++++++++ admin_manual/reference/smart_picker.rst | 39 +++++++++++++++++ 5 files changed, 125 insertions(+), 3 deletions(-) create mode 100644 admin_manual/reference/index.rst create mode 100644 admin_manual/reference/link_previews.rst create mode 100644 admin_manual/reference/smart_picker.rst diff --git a/admin_manual/contents.rst b/admin_manual/contents.rst index 2ff69967f..e0789991a 100644 --- a/admin_manual/contents.rst +++ b/admin_manual/contents.rst @@ -4,8 +4,8 @@ Table of contents .. toctree:: :maxdepth: 2 - - index + + index release_notes release_schedule installation/index @@ -16,6 +16,7 @@ Table of contents file_workflows/index groupware/index office/index + reference/index configuration_database/index configuration_mimetypes/index maintenance/index diff --git a/admin_manual/office/index.rst b/admin_manual/office/index.rst index 2dacf1a11..a33d6b5e9 100644 --- a/admin_manual/office/index.rst +++ b/admin_manual/office/index.rst @@ -22,4 +22,4 @@ We are able to provide a solution for Online Office for the entire Nextcloud com installation configuration migration - troubleshooting \ No newline at end of file + troubleshooting diff --git a/admin_manual/reference/index.rst b/admin_manual/reference/index.rst new file mode 100644 index 000000000..691c23480 --- /dev/null +++ b/admin_manual/reference/index.rst @@ -0,0 +1,26 @@ +==================== +Reference management +==================== + +The reference management system brings 2 features in Nextcloud: + +* The link previews (also called reference widgets) +* The Smart Picker + +Both those features are generic and need to be extended by the Nextcloud apps. + +Apps can add support for some HTTP links so previews are rendered in various places like Text documents and Talk messages. + +The Smart Picker is a frontend component which allows users to search or generate links or text. + +Apps can register Smart Picker providers to extend its capabilities. +Administrators can choose which Smart Picker providers they want to +make available to the users by choosing which apps they install. +All the Smart Picker providers shipped in the recommended apps do **not** send any data to 3rd party services. +Some community apps Smart Picker providers might rely on 3rd party services. + +.. toctree:: + :maxdepth: 2 + + link_previews + smart_picker diff --git a/admin_manual/reference/link_previews.rst b/admin_manual/reference/link_previews.rst new file mode 100644 index 000000000..019fff16c --- /dev/null +++ b/admin_manual/reference/link_previews.rst @@ -0,0 +1,56 @@ +============= +Link previews +============= + +Link previews are available in some places in Nextcloud. +There are 3 types of link preview: + +* The ones for links that are supported by a reference provider + * Without custom reference widget (uses a default generic style, image + title + description) + * With custom reference widget (implemented by the app which supports the link) +* Default ones from OpenGraph information. This is the fallback for every unsupported link + +Where do they appear? +--------------------- + +The link previews provided by the Nextcloud reference system appear in the following places: + +* Text (and Collectives pages, Notes, Deck card comments, Files comments etc...) + * Directly in the document content, next to the links + * Only one link preview per paragraph is rendered + * Custom widgets can be rendered +* Talk + * In the messages + * Only one link preview per message is rendered + * Custom widgets can be rendered +* Nextcloud Office + * In the document content when hovering on links + * Custom widgets are not rendered + +How does it work? +----------------- + +The Nextcloud frontend asks the server to resolve the links via an API request. A rich object is returned as a response +and is used by the frontend to render the preview. + +The apps can optionally register a custom reference widget to render a specific rich object type (on the links it supports). +Therefore the apps have complete freedom over how some previews look like. + +Known link preview providers +---------------------------- + +* `Collectives `_: Links to Collective pages +* `Tables `_: Links to tables +* `Deck `_: Links to boards, cards and comments +* `Talk `_: Links to conversations + +* `GitHub integration `_: Links to GitHub issues, pull requests, comments and repositories +* `GitLab integration `_: Links to Gitlab issues, merge requests, comments and repositories +* `Zammad integration `_: Links to Zammad tickets +* `Reddit integration `_: Links to subreddits, publications and comments +* `Mastodon integration `_: Links to members and toots +* `The Movie Database integration `_: Links to people, movies and series +* `OpenStreetMap integration `_: Location links from OpenStreetMap, Google maps, Bing maps, Here maps and Duckduckgo maps +* `Giphy integration `_: Links to GIFs +* `Notion integration `_: Links to Notion documents +* `Peertube integration `_: Links to videos diff --git a/admin_manual/reference/smart_picker.rst b/admin_manual/reference/smart_picker.rst new file mode 100644 index 000000000..2df2b6767 --- /dev/null +++ b/admin_manual/reference/smart_picker.rst @@ -0,0 +1,39 @@ +================ +The Smart Picker +================ + +Every Smart Picker provider can be enabled by installing and configuring the corresponding app. + +Where can it be used? +--------------------- + +The Smart Picker can be used in: + +* Text (and everywhere Text is used like Collectives pages, Deck card comments, Files comments...): by pressing the "/" key or using a top menu entry +* Talk: by pressing the "/" key in the message composition input +* Nextcloud Office: with a top menu entry +* Mail: in the email composition area with a context menu entry + +Known Smart Picker providers +---------------------------- + +* Accessing internal data + * `Collectives `_: To get links to Collective pages + * `Tables `_: To get links to tables + * `Deck `_: To get links to boards and comments + * `Talk `_: To get links to conversations + * `Files `_: To get internal links to files (not share links yet) + * `Text templates `_: To get personal and global text templates +* Relying on 3rd party services + * `GitHub integration `_: To get links to GitHub issues, pull requests, and repositories + * `GitLab integration `_: To get links to Gitlab issues, merge requests, and repositories + * `Zammad integration `_: To get links to Zammad tickets + * `Reddit integration `_: To get links to subreddits and publications + * `Mastodon integration `_: To get links to members, toots and hashtags + * `The Movie Database integration `_: To get links to people, movies and series + * `OpenStreetMap integration `_: To get location links from OpenStreetMap + * `Giphy integration `_: To get links to GIFs + * `Notion integration `_: To get links to Notion documents + * `Peertube integration `_: To get links to videos + * `OpenAI integration `_: To generate images with Dall-e, text with GPT and transcribe/translate with Whisper (speech-to-text) + * `Replicate integration `_: To generate images with stable diffusion, and transcribe/translate with Whisper (speech-to-text)