mirror of
https://github.com/matrix-org/matrix-spec
synced 2025-12-25 10:28:37 +01:00
Merge pull request #1617 from turt2live/travis/c2s/rich-replies
Add rich replies
This commit is contained in:
Travis Ralston
GitHub
commit
25a461b86e
1
changelogs/client_server/newsfragments/1617.feature
Normal file
1
changelogs/client_server/newsfragments/1617.feature
Normal file
|
|
@ -0,0 +1 @@
|
|||
Add "rich replies" - a way for users to better represent the conversation thread they are referencing in their messages.
|
||||
|
|
@ -62,9 +62,9 @@ support an additional ``format`` parameter of ``org.matrix.custom.html``. When
|
|||
this field is present, a ``formatted_body`` with the HTML must be provided. The
|
||||
plain text version of the HTML should be provided in the ``body``.
|
||||
|
||||
Clients should limit the HTML they render to avoid Cross-Site Scripting, HTML
|
||||
Clients should limit the HTML they render to avoid Cross-Site Scripting, HTML
|
||||
injection, and similar attacks. The strongly suggested set of HTML tags to permit,
|
||||
denying the use and rendering of anything else, is: ``font``, ``del``, ``h1``,
|
||||
denying the use and rendering of anything else, is: ``font``, ``del``, ``h1``,
|
||||
``h2``, ``h3``, ``h4``, ``h5``, ``h6``, ``blockquote``, ``p``, ``a``, ``ul``,
|
||||
``ol``, ``sup``, ``sub``, ``li``, ``b``, ``i``, ``u``, ``strong``, ``em``,
|
||||
``strike``, ``code``, ``hr``, ``br``, ``div``, ``table``, ``thead``, ``tbody``,
|
||||
|
|
@ -73,7 +73,7 @@ denying the use and rendering of anything else, is: ``font``, ``del``, ``h1``,
|
|||
Not all attributes on those tags should be permitted as they may be avenues for
|
||||
other disruption attempts, such as adding ``onclick`` handlers or excessively
|
||||
large text. Clients should only permit the attributes listed for the tags below.
|
||||
Where ``data-mx-bg-color`` and ``data-mx-color`` are listed, clients should
|
||||
Where ``data-mx-bg-color`` and ``data-mx-color`` are listed, clients should
|
||||
translate the value (a 6-character hex color code) to the appropriate CSS/attributes
|
||||
for the tag.
|
||||
|
||||
|
|
@ -112,6 +112,13 @@ surrounding text due to Rich Text Editors. HTML included in events should otherw
|
|||
such as 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.
|
||||
|
||||
.. Note::
|
||||
A future iteration of the specification will support more powerful and extensible
|
||||
message formatting options, such as the proposal `MSC1225 <https://github.com/matrix-org/matrix-doc/issues/1225>`_.
|
||||
|
|
@ -346,6 +353,192 @@ change unexpectedly.
|
|||
an English-language implementation on them all? See
|
||||
https://matrix.org/jira/browse/SPEC-425.
|
||||
|
||||
|
||||
Forming relationships between events
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
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``.
|
||||
|
||||
|
||||
Rich replies
|
||||
++++++++++++
|
||||
|
||||
Users may wish to reference another message when forming their own message, and
|
||||
clients may wish to better embed the referenced message for the user to have a
|
||||
better context for the conversation being had. This sort of embedding another
|
||||
message in a message is known as a "rich reply", or occasionally just a "reply".
|
||||
|
||||
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 and event representation
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
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:
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
> <@alice:example.org> This is the original body
|
||||
|
||||
This is where the reply goes
|
||||
|
||||
|
||||
The ``formatted_body`` should use the following template:
|
||||
|
||||
.. code-block:: html
|
||||
|
||||
<mx-reply>
|
||||
<blockquote>
|
||||
<a href="https://matrix.to/#/!somewhere:domain.com/$event:domain.com">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.html#matrix-to-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:
|
||||
|
||||
.. code-block:: html
|
||||
|
||||
<mx-reply>
|
||||
<blockquote>
|
||||
<a href="https://matrix.to/#/!somewhere:domain.com/$event:domain.com">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
|
||||
|
||||
|
||||
.. code-block:: html
|
||||
|
||||
<mx-reply>
|
||||
<blockquote>
|
||||
<a href="https://matrix.to/#/!somewhere:domain.com/$event:domain.com">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"``.
|
||||
|
||||
|
||||
Server behaviour
|
||||
----------------
|
||||
|
||||
|
|
@ -362,4 +555,4 @@ Clients should sanitise **all displayed keys** for unsafe HTML to prevent Cross-
|
|||
Scripting (XSS) attacks. This includes room names and topics.
|
||||
|
||||
.. _`E2E module`: `module:e2e`_
|
||||
.. _`Matrix Content (MXC) URI`: `module:content`_
|
||||
.. _`Matrix Content (MXC) URI`: `module:content`_
|
||||
|
|
|
|||
Loading…
Reference in a new issue