mirror of
https://github.com/matrix-org/matrix-spec
synced 2026-03-23 11:34:09 +01:00
Remove reply fallbacks
As per MSC2781. Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
This commit is contained in:
Kévin Commaille
parent
b1f66d1b71
commit
12f1ede3ed
|
|
@ -362,43 +362,9 @@ property under `m.new_content`.
|
|||
|
||||
#### Edits of replies
|
||||
|
||||
Some particular constraints apply to events which replace a
|
||||
[reply](#rich-replies). In particular:
|
||||
|
||||
* In contrast to the original reply, there should be no `m.in_reply_to`
|
||||
property in the the `m.relates_to` object, since it would be redundant (see
|
||||
[Applying `m.new_content`](#applying-mnew_content) above, which notes that
|
||||
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"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
{{% boxes/note %}}
|
||||
{{% changed-in v="1.13" %}}
|
||||
In previous versions of the specification, events which replace a [reply](#rich-replies)
|
||||
could include a fallback in the `content`. They are now treated as any other
|
||||
relation.
|
||||
{{% /boxes/note %}}
|
||||
|
|
|
|||
|
|
@ -98,14 +98,11 @@ having appropriate closing tags, appropriate attributes (considering the
|
|||
custom ones defined in this specification), and generally valid
|
||||
structure.
|
||||
|
||||
A special tag, `mx-reply`, may appear on rich replies (described below)
|
||||
and should be allowed if, and only if, the tag appears as the very first
|
||||
tag in the `formatted_body`. The tag cannot be nested and cannot be
|
||||
located after another tag in the tree. Because the tag contains HTML, an
|
||||
`mx-reply` is expected to have a partner closing tag and should be
|
||||
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 %}}
|
||||
{{% changed-in v="1.13" %}}
|
||||
In previous versions of the specification, [rich replies](#rich-replies) could
|
||||
use a special tag, `mx-reply`, this is no longer the case.
|
||||
{{% /boxes/note %}}
|
||||
|
||||
{{% boxes/note %}}
|
||||
A future iteration of the specification will support more powerful and
|
||||
|
|
|
|||
|
|
@ -2,6 +2,7 @@
|
|||
### Rich replies
|
||||
|
||||
{{% changed-in v="1.3" %}}
|
||||
{{% changed-in v="1.13" %}}
|
||||
|
||||
Rich replies are a
|
||||
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.
|
||||
{{% /boxes/note %}}
|
||||
|
||||
When possible, events SHOULD include a [fallback representation](#fallbacks-for-rich-replies)
|
||||
to allow clients which do not render rich replies to still see something which
|
||||
appears to be a quoted reply.
|
||||
{{% boxes/note %}}
|
||||
{{% changed-in v="1.13" %}}
|
||||
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 ("> ", 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
|
||||
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
|
||||
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 ("> ", 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
|
||||
|
||||
In order to notify users of the reply, it may be desirable to include the `sender`
|
||||
|
|
|
|||
Loading…
Reference in a new issue