diff --git a/content/client-server-api/modules/event_replacements.md b/content/client-server-api/modules/event_replacements.md index 50109d07..6824cedd 100644 --- a/content/client-server-api/modules/event_replacements.md +++ b/content/client-server-api/modules/event_replacements.md @@ -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": "
In reply to @alice:example.org
question
* 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 %}} diff --git a/content/client-server-api/modules/instant_messaging.md b/content/client-server-api/modules/instant_messaging.md index de388e9e..0b11156f 100644 --- a/content/client-server-api/modules/instant_messaging.md +++ b/content/client-server-api/modules/instant_messaging.md @@ -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 diff --git a/content/client-server-api/modules/rich_replies.md b/content/client-server-api/modules/rich_replies.md index ef07b697..e465dd05 100644 --- a/content/client-server-api/modules/rich_replies.md +++ b/content/client-server-api/modules/rich_replies.md @@ -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 - -
- In reply to - @alice:example.org -
- -
- -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 - -
- In reply to - * @alice:example.org -
- -
- -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 - -
- In reply to - @alice:example.org -
- sent a file. -
- -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`