Spec /relations and aggregations (#1062)
* Commit to show changes to rich replies section * Move rich replies to a module * Add remainder of MSC2674 * Pivot away from MSC3440: Threads * Add changelog entries so far * Make a note for why we have aggregations/relations if nothing uses it * Outright remove threads references Apparently this breaks the table of contents * Define MSC2675 * Define MSC3666 * Add note for rich replies? * Update content/client-server-api/_index.md Co-authored-by: Patrick Cloke <clokep@users.noreply.github.com> * Clarify how ignoring works for aggregations. * Try to clarify redactions a bit * Clarify using parent/child language * Add missing bits of MSC2675 * Add changelog for aggregations * Appease the linters * Update data/api/client-server/relations.yaml Co-authored-by: Patrick Cloke <clokep@users.noreply.github.com> * Apply suggestions from code review Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> * Apply suggestions from code review Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> * Try to clarify the return of /relations * Fix required attribute * Fix wording round 1 * Try to fix pagination * Copy/paste the endpoint to make Open API happy * Fix code block examples for rich replies * Apply suggestions from code review Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> * Apply suggestions on all 3 endpoints * Fix description of relationships API * Fix warning about server-side aggregation/bundling Co-authored-by: Patrick Cloke <clokep@users.noreply.github.com> Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
This commit is contained in:
Travis Ralston
GitHub
parent
f14e18131b
commit
c4db688af8
8 changed files with 875 additions and 163 deletions
|
|
@ -287,169 +287,6 @@ when using the `m.heroes` to calculate the name. Clients SHOULD use
|
|||
minimum 5 heroes to calculate room names where possible, but may use
|
||||
more or less to fit better with their user experience.
|
||||
|
||||
##### Rich replies
|
||||
|
||||
In some cases, events may wish to reference other events. This could be
|
||||
to form a thread of messages for the user to follow along with, or to
|
||||
provide more context as to what a particular event is describing.
|
||||
Currently, the only kind of relation defined is a "rich reply" where a
|
||||
user may reference another message to create a thread-like conversation.
|
||||
|
||||
Relationships are defined under an `m.relates_to` key in the event's
|
||||
`content`. If the event is of the type `m.room.encrypted`, the
|
||||
`m.relates_to` key MUST NOT be covered by the encryption and instead be
|
||||
put alongside the encryption information held in the `content`.
|
||||
|
||||
A rich reply is formed through use of an `m.relates_to` relation for
|
||||
`m.in_reply_to` where a single key, `event_id`, is used to reference the
|
||||
event being replied to. The referenced event ID SHOULD belong to the
|
||||
same room where the reply is being sent. Clients should be cautious of
|
||||
the event ID belonging to another room, or being invalid entirely. Rich
|
||||
replies can only be constructed in the form of `m.room.message` events
|
||||
with a `msgtype` of `m.text` or `m.notice`. Due to the fallback
|
||||
requirements, rich replies cannot be constructed for types of `m.emote`,
|
||||
`m.file`, etc. Rich replies may reference any other `m.room.message`
|
||||
event, however. Rich replies may reference another event which also has
|
||||
a rich reply, infinitely.
|
||||
|
||||
An `m.in_reply_to` relationship looks like the following:
|
||||
|
||||
```
|
||||
{
|
||||
...
|
||||
"type": "m.room.message",
|
||||
"content": {
|
||||
"msgtype": "m.text",
|
||||
"body": "<body including fallback>",
|
||||
"format": "org.matrix.custom.html",
|
||||
"formatted_body": "<HTML including fallback>",
|
||||
"m.relates_to": {
|
||||
"m.in_reply_to": {
|
||||
"event_id": "$another:event.com"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
##### Fallbacks for rich replies
|
||||
|
||||
Some clients may not have support for rich replies and therefore need a
|
||||
fallback to use instead. Clients that do not support rich replies should
|
||||
render the event as if rich replies were not special.
|
||||
|
||||
Clients that do support rich replies MUST provide the fallback format on
|
||||
replies, and MUST strip the fallback before rendering the reply. Rich
|
||||
replies MUST have a `format` of `org.matrix.custom.html` and therefore a
|
||||
`formatted_body` alongside the `body` and appropriate `msgtype`. The
|
||||
specific fallback text is different for each `msgtype`, however the
|
||||
general format for the `body` is:
|
||||
|
||||
> <@alice:example.org> This is the original body
|
||||
|
||||
This is where the reply goes
|
||||
|
||||
The `formatted_body` should use the following template:
|
||||
|
||||
<mx-reply>
|
||||
<blockquote>
|
||||
<a href="https://matrix.to/#/!somewhere:example.org/$event:example.org">In reply to</a>
|
||||
<a href="https://matrix.to/#/@alice:example.org">@alice:example.org</a>
|
||||
<br />
|
||||
<!-- This is where the related event's HTML would be. -->
|
||||
</blockquote>
|
||||
</mx-reply>
|
||||
This is where the reply goes.
|
||||
|
||||
If the related event does not have a `formatted_body`, the event's
|
||||
`body` should be considered after encoding any HTML special characters.
|
||||
Note that the `href` in both of the anchors use a [matrix.to
|
||||
URI](/appendices#matrixto-navigation).
|
||||
|
||||
###### Stripping the fallback
|
||||
|
||||
Clients which support rich replies MUST strip the fallback from the
|
||||
event before rendering the event. This is because the text provided in
|
||||
the fallback cannot be trusted to be an accurate representation of the
|
||||
event. After removing the fallback, clients are recommended to represent
|
||||
the event referenced by `m.in_reply_to` similar to the fallback's
|
||||
representation, although clients do have creative freedom for their user
|
||||
interface. Clients should prefer the `formatted_body` over the `body`,
|
||||
just like with other `m.room.message` events.
|
||||
|
||||
To strip the fallback on the `body`, the client should iterate over each
|
||||
line of the string, removing any lines that start with the fallback
|
||||
prefix ("> ", including the space, without quotes) and stopping when
|
||||
a line is encountered without the prefix. This prefix is known as the
|
||||
"fallback prefix sequence".
|
||||
|
||||
To strip the fallback on the `formatted_body`, the client should remove
|
||||
the entirety of the `mx-reply` tag.
|
||||
|
||||
###### Fallback for `m.text`, `m.notice`, and unrecognised message types
|
||||
|
||||
Using the prefix sequence, the first line of the related event's `body`
|
||||
should be prefixed with the user's ID, followed by each line being
|
||||
prefixed with the fallback prefix sequence. For example:
|
||||
|
||||
> <@alice:example.org> This is the first line
|
||||
> This is the second line
|
||||
|
||||
This is the reply
|
||||
|
||||
The `formatted_body` uses the template defined earlier in this section.
|
||||
|
||||
###### Fallback for `m.emote`
|
||||
|
||||
Similar to the fallback for `m.text`, each line gets prefixed with the
|
||||
fallback prefix sequence. However an asterisk should be inserted before
|
||||
the user's ID, like so:
|
||||
|
||||
> * <@alice:example.org> feels like today is going to be a great day
|
||||
|
||||
This is the reply
|
||||
|
||||
The `formatted_body` has a subtle difference for the template where the
|
||||
asterisk is also inserted ahead of the user's ID:
|
||||
|
||||
<mx-reply>
|
||||
<blockquote>
|
||||
<a href="https://matrix.to/#/!somewhere:example.org/$event:example.org">In reply to</a>
|
||||
* <a href="https://matrix.to/#/@alice:example.org">@alice:example.org</a>
|
||||
<br />
|
||||
<!-- This is where the related event's HTML would be. -->
|
||||
</blockquote>
|
||||
</mx-reply>
|
||||
This is where the reply goes.
|
||||
|
||||
###### Fallback for `m.image`, `m.video`, `m.audio`, and `m.file`
|
||||
|
||||
The related event's `body` would be a file name, which may not be very
|
||||
descriptive. The related event should additionally not have a `format`
|
||||
or `formatted_body` in the `content` - if the event does have a `format`
|
||||
and/or `formatted_body`, those fields should be ignored. Because the
|
||||
filename alone may not be descriptive, the related event's `body` should
|
||||
be considered to be `"sent a file."` such that the output looks similar
|
||||
to the following:
|
||||
|
||||
> <@alice:example.org> sent a file.
|
||||
|
||||
This is the reply
|
||||
|
||||
<mx-reply>
|
||||
<blockquote>
|
||||
<a href="https://matrix.to/#/!somewhere:example.org/$event:example.org">In reply to</a>
|
||||
<a href="https://matrix.to/#/@alice:example.org">@alice:example.org</a>
|
||||
<br />
|
||||
sent a file.
|
||||
</blockquote>
|
||||
</mx-reply>
|
||||
This is where the reply goes.
|
||||
|
||||
For `m.image`, the text should be `"sent an image."`. For `m.video`, the
|
||||
text should be `"sent a video."`. For `m.audio`, the text should be
|
||||
`"sent an audio file"`.
|
||||
|
||||
##### Spoiler messages
|
||||
|
||||
{{% added-in v="1.1" %}}
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue