diff --git a/changelogs/client_server/newsfragments/1283.clarification b/changelogs/client_server/newsfragments/1283.clarification new file mode 100644 index 00000000..12fee9c6 --- /dev/null +++ b/changelogs/client_server/newsfragments/1283.clarification @@ -0,0 +1 @@ +Improve display of event subtypes. \ No newline at end of file diff --git a/content/client-server-api/modules/end_to_end_encryption.md b/content/client-server-api/modules/end_to_end_encryption.md index 3deae943..ed15d17d 100644 --- a/content/client-server-api/modules/end_to_end_encryption.md +++ b/content/client-server-api/modules/end_to_end_encryption.md @@ -736,7 +736,7 @@ following error codes are used in addition to those already specified: - `m.mismatched_commitment`: The hash commitment did not match. - `m.mismatched_sas`: The SAS did not match. -{{% event event="m.key.verification.start$m.sas.v1" %}} +{{% event event="m.key.verification.start$m.sas.v1" title="`m.key.verification.start` with `method: m.sas.v1`" %}} {{% event event="m.key.verification.accept" %}} @@ -1145,7 +1145,7 @@ base64). ###### Verification messages specific to QR codes -{{% event event="m.key.verification.start$m.reciprocate.v1" %}} +{{% event event="m.key.verification.start$m.reciprocate.v1" title="`m.key.verification.start` with `method: m.reciprocate.v1`" %}} #### Sharing keys between devices diff --git a/content/client-server-api/modules/instant_messaging.md b/content/client-server-api/modules/instant_messaging.md index 5b6d3326..3a10db8f 100644 --- a/content/client-server-api/modules/instant_messaging.md +++ b/content/client-server-api/modules/instant_messaging.md @@ -10,7 +10,7 @@ room itself such as a room name and topic. #### Events -{{% event event="m.room.message" %}} +{{% event event="m.room.message" desired_example_name="m.room.message$m.text" %}} {{% event event="m.room.name" %}} diff --git a/content/client-server-api/modules/server_notices.md b/content/client-server-api/modules/server_notices.md index b0e2fa22..05f9e270 100644 --- a/content/client-server-api/modules/server_notices.md +++ b/content/client-server-api/modules/server_notices.md @@ -35,7 +35,7 @@ maximum. New connections are being refused by the server. What defines "active" is left as an implementation detail, however servers are encouraged to treat syncing users as "active". -{{% event event="m.room.message$m.server_notice" %}} +{{% event event="m.room.message$m.server_notice" title="`m.room.message` with `msgtype: m.server_notice`" %}} #### Client behaviour diff --git a/layouts/partials/events/example.html b/layouts/partials/events/example.html new file mode 100644 index 00000000..181de88f --- /dev/null +++ b/layouts/partials/events/example.html @@ -0,0 +1,17 @@ +{{/* + + Renders an event example. Resolves `$ref`s, serializes as JSON, and ensures + that it can be included in HTML. + + This partial is called with the example event object as its context. + +*/}} + +{{ $example_content := partial "json-schema/resolve-refs" (dict "schema" . "path" "event-schemas/examples") }} +{{ $example_json := jsonify (dict "indent" " ") $example_content }} +{{ $example_json = replace $example_json "\\u003c" "<" }} +{{ $example_json = replace $example_json "\\u003e" ">" | safeHTML }} + +```json +{{ $example_json }} +``` diff --git a/layouts/partials/events/render-event.html b/layouts/partials/events/render-event.html index 5e9f5c13..369a80db 100644 --- a/layouts/partials/events/render-event.html +++ b/layouts/partials/events/render-event.html @@ -2,11 +2,13 @@ Renders a single event, given: - * `event_name`: the name we want to display for the event + * `event_name`: the name to use for the event * `event_data`: the event specification * `desired_example_name` (optional): the exact name of the examples to render. If `desired_example_name` is omitted we render all examples whose names start with the `event_name`. + * `title` (optional): the title to display. May contain markdown. Defaults to + `event_name` wrapped in a element. */}} @@ -20,7 +22,7 @@

- {{ $event_name }} + {{ with .title }}{{ . | markdownify }}{{ else }}{{ $event_name }}{{ end }}

@@ -72,11 +74,16 @@ */}} {{ if $desired_example_name }} {{ if eq $example_name $desired_example_name }} - {{ $example_content := partial "json-schema/resolve-refs" (dict "schema" $example "path" "event-schemas/examples") }} -```json -{{ jsonify (dict "indent" " ") $example_content }} -``` + {{ partial "events/example" $example }} {{ end }} + {{/* + If `$desired_example_name` is not given, we will include any + example that is equal to the event name. Normally, this would + be handled by the case below, but that case does not work if + the event name includes a "$". + */}} + {{ else if eq $event_name $example_name }} + {{ partial "events/example" $example }} {{/* If `$desired_example_name` is not given, we will include any examples whose first part (before "$") matches the event name @@ -86,14 +93,7 @@ {{ $pieces := split $example_name "$" }} {{ $example_base_name := index $pieces 0 }} {{ if eq $event_name $example_base_name }} - {{ $example_content := partial "json-schema/resolve-refs" (dict "schema" $example "path" "event-schemas/examples") }} - {{ $example_json := jsonify (dict "indent" " ") $example_content }} - {{ $example_json = replace $example_json "\\u003c" "<" }} - {{ $example_json = replace $example_json "\\u003e" ">" | safeHTML }} - -```json -{{ $example_json }} -``` + {{ partial "events/example" $example }} {{ end }} {{ end }} {{ end }} diff --git a/layouts/shortcodes/event.html b/layouts/shortcodes/event.html index 71c9c534..a9838542 100644 --- a/layouts/shortcodes/event.html +++ b/layouts/shortcodes/event.html @@ -2,10 +2,23 @@ This template is used to render an event. - It expects to be passed an `event` parameter, which is the name of a schema file under - "data/event-schemas/schema". The file extension is omitted. For example: + It takes the following parameters: - {{% event event="m.accepted_terms" %}} + * `event` (required): the name of a schema file under "data/event-schemas/schema". + The file extension is omitted. For example: + + {{% event event="m.accepted_terms" %}} + + * `desired_example_name` (optional): the name of the example file to use under + "data/event-schemas/examples", without the file extension. If omitted + defaults to the example file with the same name as the `event` parameter, and + (if the name does not contain a "$"), all examples that begin with the name + given by the `event` parameter followed by a "$". For example, if the + `event` parameter is "m.foo", then by default it will include the "m.foo" + example along with any examples starting with "m.foo$". + + * `title` (optional): the title to use for the event. Defaults to the name + given in the `event` parameter. This template replaces the old {{*_event}} template. @@ -17,4 +30,4 @@ {{ $event_data = partial "json-schema/resolve-refs" (dict "schema" $event_data "path" $path) }} {{ $event_data := partial "json-schema/resolve-allof" $event_data }} -{{ partial "events/render-event" (dict "event_name" .Params.event "event_data" $event_data)}} +{{ partial "events/render-event" (dict "event_name" .Params.event "event_data" $event_data "desired_example_name" .Params.desired_example_name "title" .Params.title)}}