Filip/matrix-spec
1
0
Fork 0
mirror of https://github.com/matrix-org/matrix-spec synced 2026-03-23 19:44:09 +01:00
Code Issues Actions 1 Packages Projects Releases Wiki Activity

Remove reply fallbacks

Browse source 
As per MSC2781.

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
This commit is contained in:
Kévin Commaille 2024-11-14 10:53:45 +01:00
parent b1f66d1b71
commit 12f1ede3ed
No known key found for this signature in database
GPG key ID: 0C971D9DBC9D678D
3 changed files with 28 additions and 182 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

46
content/client-server-api/modules/event_replacements.md
View file

@ -362,43 +362,9 @@ property under `m.new_content`.
#### Edits of replies #### Edits of replies
Some particular constraints apply to events which replace a {{% boxes/note %}}
[reply](#rich-replies). In particular: {{% changed-in v="1.13" %}}
In previous versions of the specification, events which replace a [reply](#rich-replies)
* In contrast to the original reply, there should be no `m.in_reply_to` could include a fallback in the `content`. They are now treated as any other
property in the the `m.relates_to` object, since it would be redundant (see relation.
[Applying `m.new_content`](#applying-mnew_content) above, which notes that {{% /boxes/note %}}
the original event's `m.relates_to` is preserved), as well as being contrary
to the spirit of the event relationships mechanism which expects only one
"parent" per event.
* `m.new_content` should **not** contain any [reply
fallback](#fallbacks-for-rich-replies),
since it is assumed that any client which can handle edits can also display
replies natively. However, the `content` of the replacement event should provide
fallback content for clients which support neither rich replies nor edits.
An example of an edit to a reply is as follows:
```json
{
"type": "m.room.message",
// irrelevant fields not shown
"content": {
"body": "> <@alice:example.org> question\n\n* reply",
"msgtype": "m.text",
"format": "org.matrix.custom.html",
"formatted_body": "<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 />question</blockquote></mx-reply>* reply",
"m.new_content": {
"body": "reply",
"msgtype": "m.text",
"format": "org.matrix.custom.html",
"formatted_body": "reply"
},
"m.relates_to": {
"rel_type": "m.replace",
"event_id": "$original_reply_event"
}
}
}
```

13
content/client-server-api/modules/instant_messaging.md
View file

@ -98,14 +98,11 @@ having appropriate closing tags, appropriate attributes (considering the
custom ones defined in this specification), and generally valid custom ones defined in this specification), and generally valid
structure. structure.
A special tag, `mx-reply`, may appear on rich replies (described below) {{% boxes/note %}}
and should be allowed if, and only if, the tag appears as the very first {{% changed-in v="1.13" %}}
tag in the `formatted_body`. The tag cannot be nested and cannot be In previous versions of the specification, [rich replies](#rich-replies) could
located after another tag in the tree. Because the tag contains HTML, an use a special tag, `mx-reply`, this is no longer the case.
`mx-reply` is expected to have a partner closing tag and should be {{% /boxes/note %}}
treated similar to a `div`. Clients that support rich replies will end
up stripping the tag and its contents and therefore may wish to exclude
the tag entirely.
{{% boxes/note %}} {{% boxes/note %}}
A future iteration of the specification will support more powerful and A future iteration of the specification will support more powerful and

151
content/client-server-api/modules/rich_replies.md
View file

@ -2,6 +2,7 @@
### Rich replies ### Rich replies
{{% changed-in v="1.3" %}} {{% changed-in v="1.3" %}}
{{% changed-in v="1.13" %}}
Rich replies are a Rich replies are a
special kind of [relationship](#forming-relationships-between-events) which special kind of [relationship](#forming-relationships-between-events) which
@ -18,9 +19,22 @@ Additionally, a rich reply can reference any other event type as of v1.3.
Previously, a rich reply could only reference another `m.room.message` event. Previously, a rich reply could only reference another `m.room.message` event.
{{% /boxes/note %}} {{% /boxes/note %}}
When possible, events SHOULD include a [fallback representation](#fallbacks-for-rich-replies) {{% boxes/note %}}
to allow clients which do not render rich replies to still see something which {{% changed-in v="1.13" %}}
appears to be a quoted reply. In previous versions of the specification, rich replies could include a fallback
format in the `body` and `formatted_body` for clients that do not support rich
replies, this is no longer the case. Clients might still want to remove this
fallback before rendering the event.
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 ("&gt; ", 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.
{{% /boxes/note %}}
Though rich replies form a relationship to another event, they do not Though rich replies form a relationship to another event, they do not
use `rel_type` to create this relationship. Instead, a subkey named `m.in_reply_to` use `rel_type` to create this relationship. Instead, a subkey named `m.in_reply_to`
@ -48,137 +62,6 @@ An example reply would be:
Note that the `event_id` of the `m.in_reply_to` object has the same requirements Note that the `event_id` of the `m.in_reply_to` object has the same requirements
as if it were to be under `m.relates_to` directly instead. as if it were to be under `m.relates_to` directly instead.
#### 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 SHOULD provide the fallback format on
replies, and MUST strip the fallback before rendering the reply. The
specific fallback text is different for each `msgtype`, however the
general format for the `body` is:
```text
> <@alice:example.org> This is the first line of the original body
> This is the second line
This is where the reply goes
```
The `formatted_body`, if present and using an associated `format` of
`org.matrix.custom.html`, should use the following template:
```html
<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 ("&gt; ", 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:
```text
> <@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:
```text
> * <@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:
```html
<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:
```text
> <@alice:example.org> sent a file.
This is the reply
```
```html
<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"`.
#### Mentioning the replied to user #### Mentioning the replied to user
In order to notify users of the reply, it may be desirable to include the `sender` In order to notify users of the reply, it may be desirable to include the `sender`