Nextcloud Rich Object Strings

[nickvergessen]

Nextcloud Rich Object Strings

The idea is to allow Nextcloud apps (e.g. activity and notification) to have a common syntax for their endpoints to provide markup, which is then also commonly understood by all the endpoint reading applications (desktop and mobile clients).

Motivation

The activity app has an action when someone shares a file to a group. The text of the activity is as follows:

User A shared File B with Group C

So there are 3 "objects" in this message, which should be presented with HTML markup in the web UI:

1. User A
   • Add avatar
   • Use display name instead of uid
2. File B
   • Link file name to the actual file
   • Trim path from file name in the UI
   • On hover show the path
   • Add a preview to the activity
3. Group C
   • Make bold for better readability

The problem is, that when the endpoint already speaks HTML, that other clients (desktop and mobile) can not use this strings. But of course the clients should also allow clicking on the filename and open the local folder (when synced) or the web UI (not synced).

Example

In order to allow this, the message is split into the localized string and the parameters with their meta-data (json):

[
  "{parameter1} shared {parameter2} with {parameter3}",
  {
    "parameter1": {
      "type": "user",
      "id": "a",
      "name": "User A"
    },
    "parameter2": {
      "type": "file",
      "id": 42,
      "name": "file.txt",
      "path": "path\/to\/file.txt"
    },
    "parameter3": {
      "type": "group",
      "id": "c",
      "name": "Group C"
    }
  }
]

In this case there is no markup in the endpoint and all clients (including the web UI) could transform the message into the desired visual representation.

Object type management

The list of known object types is managed in a markdown file within the server repository. This allows app authors to send pull requests to register new object types. However once a stable release is out (Nextcloud X.0.0), the list is frozen, so the list has an API version bound to a server version.

In case a client decides to not implement an object type, it should fallback to using the name and when possible using the optional link.

Minimal object type

Attribute	Status	Example	Description
type	Required	user	A unique identifier for the object type
id	Required	johndoe	A short identifier of the object on the server (int or string)
name	Required	John Doe	A name which should be used in the visual representation

Example object types

user

Attribute	Status	Example	Description
type	Required	user
id	Required	johndoe	The user id used to login and identify the user on the instance
name	Required	John Doe	The display name of the user which should be used in the visual representation

group

Attribute	Status	Example	Description
type	Required	group
id	Required	supportteam	The group id used to identify the group on the instance
name	Required	Support Team	The display name of the group which should be used in the visual representation

file

Attribute	Status	Example	Description
type	Required	file
id	Required	42	The file id used to identify the file on the instance
name	Required	file.txt	The name of the file which should be used in the visual representation
path	Required	path/to/file.txt	Full visible path of the file on the system
link	Optional	http://localhost/index.php/f/42	A full URL which should be used as a target for a click on the name

cc @jancborchardt @LukasReschke @MorrisJobke @AndyScherzinger @tobiasKaminsky @rullzer

Ref nextcloud/notifications#27

[AndyScherzinger]

@nickvergessen how does this one handle localization? I would either have to get a message ID and ship the translations or when requesting the the rich objects string request them for a certain language.

[nickvergessen]

Well the endpoints are already localized in the users language. This is taken from settings, accepted language header or default language config. So no localization needed on client sides

[dinesh-dot-com]

how to make nextcloud chat. like whatsapp's zig zag.

[nickvergessen]

Install https://apps.nextcloud.com/apps/spreed