diff --git a/developer_manual/digging_deeper/reference.rst b/developer_manual/digging_deeper/reference.rst index 531f6b372..df99caad7 100644 --- a/developer_manual/digging_deeper/reference.rst +++ b/developer_manual/digging_deeper/reference.rst @@ -226,6 +226,15 @@ For example, resolving ``https://www.themoviedb.org/movie/70981`` if the ``integ } } +Render link previews in clients +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Clients can choose to support some rich objects types. +Developers can follow the rich object formatting recommendations to provide generic information in some cases. +The rich object type is not used to predict the data structure. +We rather recommend to set rich object attributes respecting a strict format for some common use cases. + +More details can be found in `Provide generic data for clients `__ Use the Smart Picker in your app -------------------------------- @@ -289,6 +298,161 @@ the Smart Picker. console.error('Smart Picker promise rejected', error) }) + +Use the Smart Picker in clients +------------------------------- + +Clients can partially support the Smart Picker features. + +There are 2 types of Smart Picker providers: + +* The ones with a custom picker component +* The ones that support one or multiple unified search providers + +As the custom picker components are web components, clients might not be able (or want) to render them. +So we are mostly interested in the second type here: The ones using unified search providers. + +In Nextcloud's web UI, those providers are rendered with a +`generic search Vue component `_ +which shows a search input, lists the search result in a dropdown menu and directly submits the URL of the selected result. +The search is done by directly querying the Unified Search OCS API. This is described later. + +To implement something similar to the Smart Picker in a client, it is required to know how to: + +* Get the provider list +* Use the Unified Search OCS API +* Update the providers last usage date + +Get the provider list +~~~~~~~~~~~~~~~~~~~~~ + +The list of Smart Picker providers can be obtained via an OCS endpoint. +Each provider object contains the list of supported unified search providers. + +Here is the server endpoint to list the smart picker providers: + +.. code-block:: bash + + curl -u USER:PASSWD -H "Accept: application/json" -H "ocs-apirequest: true" \ + "https://my.nextcloud.org/ocs/v2.php/references/providers" + +and an example response: + +.. code-block:: json + + { + "ocs": { + "meta": { + "status": "ok", + "statuscode": 200, + "message": "OK" + }, + "data": [ + { + "id": "github-issue-pr", + "title": "GitHub issues, pull requests and comments", + "icon_url": "https://my.nextcloud.org/apps/integration_github/img/app-dark.svg", + "order": 10, + "search_providers_ids": [ + "github-search-issues", + "github-search-repos" + ] + }, + { + "id": "openstreetmap-point", + "title": "Map location (by OpenStreetMap)", + "icon_url": "https://my.nextcloud.org/apps/integration_openstreetmap/img/app-dark.svg", + "order": 10, + "search_providers_ids": [ + "openstreetmap-search-location" + ] + }, + { + "id": "files", + "title": "Files", + "icon_url": "https://my.nextcloud.org/apps/files/img/folder.svg", + "order": 0 + } + ] + } + } + +In this example, the "files" Smart Picker provider does not support any unified search provider +but the "github-issue-pr" one supports 2 of them and the "openstreetmap-point" support one. + +Use the unified search API +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Here is how to search using the Unified Search OCS API: + +.. code-block:: bash + + curl -u USER:PASSWD -H "Accept: application/json" -H "ocs-apirequest: true" \ + "https://my.nextcloud.org/ocs/v2.php/search/providers/PROVIDER_ID/search?term=QUERY&limit=LIMIT" + + # with a cursor (paginated search) + curl -u USER:PASSWD -H "Accept: application/json" -H "ocs-apirequest: true" \ + "https://my.nextcloud.org/ocs/v2.php/search/providers/PROVIDER_ID/search?term=QUERY&limit=LIMIT&cursor=CURSOR" + + # search a github issue with the query "bug" + curl -u USER:PASSWD -H "Accept: application/json" -H "ocs-apirequest: true" \ + "https://my.nextcloud.org/ocs/v2.php/search/providers/github-search-issues/search?term=bug&limit=2" + +Example response: + +.. code-block:: json + + { + "ocs": { + "meta": { + "status": "ok", + "statuscode": 200, + "message": "OK" + }, + "data": { + "name": "GitHub issues and pull requests", + "isPaginated": true, + "entries": [ + { + "thumbnailUrl": "https://my.nextcloud.org/apps/integration_github/avatar/Daily-DAYO", + "title": " [bug] Change Trim bugs", + "subline": "⑁ DAYO_Android#409", + "resourceUrl": "https://github.com/Daily-DAYO/DAYO_Android/pull/409", + "icon": "", + "rounded": true, + "attributes": [] + }, + { + "thumbnailUrl": "https://my.nextcloud.org/apps/integration_github/avatar/walinejs", + "title": " [Bug]: || [Bug]:", + "subline": "⦿ waline#2014", + "resourceUrl": "https://github.com/walinejs/waline/issues/2014", + "icon": "", + "rounded": true, + "attributes": [] + } + ], + "cursor": 2 + } + } + } + + +Update a provider last usage date +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In Nextcloud's web UI, the order in which the providers are listed to the users depends on the last +date they were used. The most recently used providers are displayed first. + +In a client, once a provider has been used, a request to this endpoint should be done: + +.. code-block:: bash + + curl -u USER:PASSWD -H "Accept: application/json" -H "ocs-apirequest: true" -X PUT \ + "https://my.nextcloud.org/ocs/v2.php/search/provider/PROVIDER_ID" + +A ``timestamp`` optional request parameter can be passed. The last usage date will be set to "now" by default. + Register a reference provider ----------------------------- @@ -498,6 +662,72 @@ in a custom fashion: } +.. _data-for-clients: + +Provide generic data for clients +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In the web interface, the links that your app resolves are rendered with the OpenGraph widget +or the custom reference widget you implemented. So you have complete freedom on which data format you put in your rich objects +because you also control the web rendering implementation. + +But as the web UI components cannot be used by desktop or mobile clients, they have to specifically support some rich objects +that are properly formatted. + +Here are some formatting suggestions for a few use cases. Use them if you want your resolved links to be rendered in clients. +The idea is to add a generic attribute in your rich objects, regardless of the rich object type. + +Version control issue +^^^^^^^^^^^^^^^^^^^^^ + +Set the rich object's ``vcs_issue`` attribute to an object which contains those attributes: + +* ``id``: The issue ID (number) +* ``url``: The issue page URL +* ``title``: The issue title +* ``comment_count``: The number of comments in the issue +* ``state``: The issue state ('open' or 'closed') +* ``labels``: An array of labels. A label is an object with those attributes: + * ``color``: Hexadecimal color code + * ``name``: The label name +* ``created_at``: The creation timestamp +* ``author``: The user ID or name of the issue creator + +Example implementation: `GitHub integration issue link preview `_ + +Version control pull request +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Set the rich object's ``vcs_pull_request`` attribute to an object which contains the same attributes as in ``vcs_issue`` plus these ones: + +* ``merged``: Is it merged? (boolean) +* ``draft``: Is it a draft? (boolean) + +Example implementation: `GitHub integration pull request link preview `_ + +Version control issue or pull request comment +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Set the rich object's ``vcs_comment`` attribute to an object which contains those attributes: + +* ``url``: A direct link/permalink to the comment +* ``body``: The comment content in plain text or markdown +* ``author``: The user ID or name of the comment author +* ``created_at``: The creation timestamp +* ``updated_at``: The last edition timestamp + +``vcs_comment`` can be set in addition to ``vcs_issue`` or ``vcs_pull_request``. + + +Images +^^^^^^ + +Set the rich object's ``image_TYPE`` attribute to ``true``. The clients will then know they can render this as an image +using the reference title, description and image URL that you have set. + +Type can be ``gif``, ``jpeg``, ``png`` etc... + +Example implementation: `Giphy integration `_ Extend the Smart Picker -----------------------