wholetrans/docs-matrix-spec
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Improve presentation of push rules kinds and actions (#1348)

Browse source
This commit is contained in:
David Robertson 2022-11-22 16:01:23 +00:00 • committed by GitHub
parent 4534124742
commit 07442876ce
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
3 changed files with 83 additions and 46 deletions
Download patch file Download diff file Expand all files Collapse all files

28
assets/scss/custom.scss
View file

@ -474,3 +474,31 @@ Make padding symmetrical (this selector is used in the default styles to apply p
background-repeat: no-repeat;
padding-left: 100px;
}
/* Adjust the styling of definition lists. */
/* Add a little spacing between the term and its definition. */
dt {
margin-bottom: 0.15rem;
}
/* _reboot.scss deliberately sets margin-left to 0. Undo this. */
dd {
margin-left: 2rem;
}
/* docsy's _code.scss does only styles <code> elements matching
* .td-content { p code, li > code, table code }.
* Copy those styles here to apply to code <elements> in definition terms too. */
.td-content {
dt code {
color: inherit;
padding: 0.2em 0.4em;
margin: 0;
font-size: 85%;
word-break: normal;
background-color: rgba($black, 0.05);
border-radius: 0.25rem; // was $border-radius, but that var isn't accessible here.
}
}

1
changelogs/client_server/newsfragments/1348.clarification Normal file
View file

@ -0,0 +1 @@
Improve the presentation of push rule kinds and actions.

98
content/client-server-api/modules/push.md
View file

@ -144,27 +144,27 @@ the value of `kind`.
The different `kind`s of rule, in the order that they are checked, are:
Override Rules `override`
The highest priority rules are user-configured overrides.
1. **Override rules (`override`).**
The highest priority rules are user-configured overrides.
Content-specific Rules `content`
These configure behaviour for (unencrypted) messages that match certain
patterns. Content rules take one parameter: `pattern`, that gives the
glob pattern to match against. This is treated in the same way as
`pattern` for `event_match`.
1. **Content-specific rules (`content`).**
These configure behaviour for (unencrypted) messages that match certain
patterns. Content rules take one parameter: `pattern`, that gives the
glob pattern to match against. This is treated in the same way as
`pattern` for `event_match`.
Room-specific Rules `room`
These rules change the behaviour of all messages for a given room. The
`rule_id` of a room rule is always the ID of the room that it affects.
1. **Room-specific rules (`room`).**
These rules change the behaviour of all messages for a given room. The
`rule_id` of a room rule is always the ID of the room that it affects.
Sender-specific rules `sender`
These rules configure notification behaviour for messages from a
specific Matrix user ID. The `rule_id` of Sender rules is always the
Matrix user ID of the user whose messages they'd apply to.
1. **Sender-specific rules (`sender`).**
These rules configure notification behaviour for messages from a
specific Matrix user ID. The `rule_id` of Sender rules is always the
Matrix user ID of the user whose messages they'd apply to.
Underride rules `underride`
These are identical to `override` rules, but have a lower priority than
`content`, `room` and `sender` rules.
1. **Underride rules (`underride`).**
These are identical to `override` rules, but have a lower priority than
`content`, `room` and `sender` rules.
Rules with the same `kind` can specify an ordering priority. This
determines which rule is selected in the event of multiple matches. For
@ -186,48 +186,56 @@ how a notification is delivered for a matching event. The following
actions are defined:
`notify`
This causes each matching event to generate a notification.
: This causes each matching event to generate a notification.
`dont_notify`
This prevents each matching event from generating a notification
: This prevents each matching event from generating a notification.
`coalesce`
This enables notifications for matching events but activates homeserver
specific behaviour to intelligently coalesce multiple events into a
single notification. Not all homeservers may support this. Those that do
not support it should treat it as the `notify` action.
: This enables notifications for matching events but activates homeserver
specific behaviour to intelligently coalesce multiple events into a
single notification. Not all homeservers may support this. Those that do
not support it should treat it as the `notify` action.
`set_tweak`
Sets an entry in the `tweaks` dictionary key that is sent in the
notification request to the Push Gateway. This takes the form of a
dictionary with a `set_tweak` key whose value is the name of the tweak
to set. It may also have a `value` key which is the value to which it
should be set.
The following tweaks are defined:
: Sets an entry in the `tweaks` dictionary key that is sent in the
notification request to the Push Gateway. This takes the form of a
dictionary with a `set_tweak` key whose value is the name of the tweak
to set. It may also have a `value` key which is the value to which it
should be set.
* `sound`: A string representing the sound to be played when this notification
arrives. A value of `default` means to play a default sound. A device
may choose to alert the user by some other means if appropriate, eg.
vibration.
The following tweaks are defined:
* `highlight`: A boolean representing whether or not this message should be highlighted
in the UI. This will normally take the form of presenting the message in
a different colour and/or style. The UI might also be adjusted to draw
particular attention to the room in which the event occurred. If a
`highlight` tweak is given with no value, its value is defined to be
`true`. If no highlight tweak is given at all then the value of
`highlight` is defined to be false.
`sound`
Tweaks are passed transparently through the homeserver so client
applications and Push Gateways may agree on additional tweaks. For
example, a tweak may be added to specify how to flash the notification
light on a mobile device.
: A string representing the sound to be played when this notification
arrives. A value of `default` means to play a default sound. A device
may choose to alert the user by some other means if appropriate, eg.
vibration.
`highlight`
: A boolean representing whether or not this message should be highlighted
in the UI. This will normally take the form of presenting the message in
a different colour and/or style. The UI might also be adjusted to draw
particular attention to the room in which the event occurred. If a
`highlight` tweak is given with no value, its value is defined to be
`true`. If no highlight tweak is given at all then the value of
`highlight` is defined to be false.
Tweaks are passed transparently through the homeserver so client
applications and Push Gateways may agree on additional tweaks. For
example, a tweak may be added to specify how to flash the notification
light on a mobile device.
Actions that have no parameters are represented as a string. Otherwise,
they are represented as a dictionary with a key equal to their name and
other keys as their parameters, e.g.
`{ "set_tweak": "sound", "value": "default" }`
`{ "set_tweak": "sound", "value": "default" }`.
###### Conditions