@ -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`_
Richard van der Hoff
6 years ago