From 99cd692ed0902a9a02d79be4b90bf08755384171 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Wed, 12 Oct 2022 15:49:21 -0400 Subject: [PATCH 1/5] improve display of event subtypes --- .../modules/end_to_end_encryption.md | 4 ++-- .../modules/server_notices.md | 2 +- layouts/partials/events/example.html | 8 +++++++ layouts/partials/events/render-event.html | 22 +++++++------------ layouts/shortcodes/event.html | 2 +- 5 files changed, 20 insertions(+), 18 deletions(-) create mode 100644 layouts/partials/events/example.html 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 10f21e86..99a138c1 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/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..95e17e22 --- /dev/null +++ b/layouts/partials/events/example.html @@ -0,0 +1,8 @@ +{{ $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 }} +``` diff --git a/layouts/partials/events/render-event.html b/layouts/partials/events/render-event.html index 5e9f5c13..73421741 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 }}{{ $.title | markdownify }}{{ else }}{{ $event_name }}{{ end }}

@@ -72,11 +74,10 @@ */}} {{ 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" (dict "example" $example)}} {{ end }} + {{ else if eq $event_name $example_name }} + {{ partial "events/example" (dict "example" $example)}} {{/* If `$desired_example_name` is not given, we will include any examples whose first part (before "$") matches the event name @@ -86,14 +87,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" (dict "example" $example)}} {{ end }} {{ end }} {{ end }} diff --git a/layouts/shortcodes/event.html b/layouts/shortcodes/event.html index 71c9c534..5ee32605 100644 --- a/layouts/shortcodes/event.html +++ b/layouts/shortcodes/event.html @@ -17,4 +17,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 "title" .Params.title)}} From 089f1fee7dd3033c8df753eaaed6b7b24aaea272 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Wed, 12 Oct 2022 16:02:07 -0400 Subject: [PATCH 2/5] add changelog --- changelogs/client_server/newsfragments/1283.clarification | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelogs/client_server/newsfragments/1283.clarification 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 From d6345f0df2fec12c08aaadac6fe3c6423a4bf87b Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Wed, 26 Oct 2022 16:33:41 -0400 Subject: [PATCH 3/5] apply changes from code review --- .../client-server-api/modules/instant_messaging.md | 2 +- layouts/partials/events/example.html | 11 ++++++++++- layouts/partials/events/render-event.html | 14 ++++++++++---- 3 files changed, 21 insertions(+), 6 deletions(-) diff --git a/content/client-server-api/modules/instant_messaging.md b/content/client-server-api/modules/instant_messaging.md index 47440cd3..efa2c579 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/layouts/partials/events/example.html b/layouts/partials/events/example.html index 95e17e22..7059d453 100644 --- a/layouts/partials/events/example.html +++ b/layouts/partials/events/example.html @@ -1,4 +1,13 @@ -{{ $example_content := partial "json-schema/resolve-refs" (dict "schema" .example "path" "event-schemas/examples") }} +{{/* + + 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 data 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 }} diff --git a/layouts/partials/events/render-event.html b/layouts/partials/events/render-event.html index 73421741..71951937 100644 --- a/layouts/partials/events/render-event.html +++ b/layouts/partials/events/render-event.html @@ -22,7 +22,7 @@

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

@@ -74,10 +74,16 @@ */}} {{ if $desired_example_name }} {{ if eq $example_name $desired_example_name }} - {{ partial "events/example" (dict "example" $example)}} + {{ 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" (dict "example" $example)}} + {{ partial "events/example" $example }} {{/* If `$desired_example_name` is not given, we will include any examples whose first part (before "$") matches the event name @@ -87,7 +93,7 @@ {{ $pieces := split $example_name "$" }} {{ $example_base_name := index $pieces 0 }} {{ if eq $event_name $example_base_name }} - {{ partial "events/example" (dict "example" $example)}} + {{ partial "events/example" $example }} {{ end }} {{ end }} {{ end }} From 60d9518a630f9d416b1797fdb46d952b47a05462 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Fri, 28 Oct 2022 16:15:04 -0400 Subject: [PATCH 4/5] pass the desired example name to the template --- layouts/shortcodes/event.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/layouts/shortcodes/event.html b/layouts/shortcodes/event.html index 5ee32605..4ae7c37f 100644 --- a/layouts/shortcodes/event.html +++ b/layouts/shortcodes/event.html @@ -17,4 +17,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 "title" .Params.title)}} +{{ partial "events/render-event" (dict "event_name" .Params.event "event_data" $event_data "desired_example_name" .Params.desired_example_name "title" .Params.title)}} From d0d7bdb807890d66bcc23fa680256d26b4f8c561 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Tue, 1 Nov 2022 11:39:15 -0400 Subject: [PATCH 5/5] apply changes from code review --- layouts/partials/events/example.html | 2 +- layouts/partials/events/render-event.html | 2 +- layouts/shortcodes/event.html | 19 ++++++++++++++++--- 3 files changed, 18 insertions(+), 5 deletions(-) diff --git a/layouts/partials/events/example.html b/layouts/partials/events/example.html index 7059d453..181de88f 100644 --- a/layouts/partials/events/example.html +++ b/layouts/partials/events/example.html @@ -3,7 +3,7 @@ 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 data as its context. + This partial is called with the example event object as its context. */}} diff --git a/layouts/partials/events/render-event.html b/layouts/partials/events/render-event.html index 71951937..369a80db 100644 --- a/layouts/partials/events/render-event.html +++ b/layouts/partials/events/render-event.html @@ -8,7 +8,7 @@ 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 + `event_name` wrapped in a element. */}} diff --git a/layouts/shortcodes/event.html b/layouts/shortcodes/event.html index 4ae7c37f..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.