diff --git a/templates/zerver/api/update-display-settings.md b/templates/zerver/api/update-display-settings.md new file mode 100644 index 0000000000..48896b462e --- /dev/null +++ b/templates/zerver/api/update-display-settings.md @@ -0,0 +1,35 @@ +# Update display settings + +{generate_api_description(/settings/display:patch)} + +## Usage examples + +{start_tabs} +{tab|python} + +{generate_code_example(python)|/settings/display:patch|example} + +{tab|curl} + +{generate_code_example(curl, include=["left_side_userlist", "emojiset"])|/settings/display:patch|example} + +{end_tabs} + +## Parameters + +{generate_api_arguments_table|zulip.yaml|/settings/display:patch} + +## Response + +#### Return values + +The server will return the settings that have been changed after the request, +with their new value. Please note that this doesn't necessarily mean that it +will return all the settings passed as parameters in the request, but only +those ones that were different from the already existing setting. + +#### Example response + +A typical successful JSON response may look like: + +{generate_code_example|/settings/display:patch|fixture(200)} diff --git a/templates/zerver/help/include/rest-endpoints.md b/templates/zerver/help/include/rest-endpoints.md index cd3af218e9..b3831efd28 100644 --- a/templates/zerver/help/include/rest-endpoints.md +++ b/templates/zerver/help/include/rest-endpoints.md @@ -44,6 +44,7 @@ * [Set "typing" status](/api/set-typing-status) * [Get user presence](/api/get-user-presence) * [Get attachments](/api/get-attachments) +* [Update display settings](/api/update-display-settings) * [Update notification settings](/api/update-notification-settings) * [Get user groups](/api/get-user-groups) * [Create a user group](/api/create-user-group) diff --git a/zerver/openapi/python_examples.py b/zerver/openapi/python_examples.py index 6970fe028f..a370981d4a 100644 --- a/zerver/openapi/python_examples.py +++ b/zerver/openapi/python_examples.py @@ -1101,6 +1101,22 @@ def update_notification_settings(client: Client) -> None: validate_against_openapi_schema(result, "/settings/notifications", "patch", "200") +@openapi_test_function("/settings/display:patch") +def update_display_settings(client: Client) -> None: + + # {code_example|start} + # Show user list on left sidebar in narrow windows. + # Change emoji set used for display to Google modern. + request = { + "left_side_userlist": True, + "emojiset": '"google"', + } + result = client.call_endpoint("settings/display", method="PATCH", request=request) + # {code_example|end} + + validate_against_openapi_schema(result, "/settings/display", "patch", "200") + + @openapi_test_function("/user_uploads:post") def upload_file(client: Client) -> None: path_to_file = os.path.join(ZULIP_DIR, "zerver", "tests", "images", "img.jpg") @@ -1391,6 +1407,7 @@ def test_users(client: Client, owner_client: Client) -> None: get_subscription_status(client) get_profile(client) update_notification_settings(client) + update_display_settings(client) upload_file(client) get_attachments(client) set_typing_status(client) diff --git a/zerver/openapi/zulip.yaml b/zerver/openapi/zulip.yaml index 9835a83083..bf82f02cb2 100644 --- a/zerver/openapi/zulip.yaml +++ b/zerver/openapi/zulip.yaml @@ -8949,6 +8949,236 @@ paths: "msg": "", "result": "success", } + /settings/display: + patch: + operationId: update_display_settings + tags: ["users"] + description: | + This endpoint is used to edit the current user's user interface settings. + + `PATCH {{ api_url }}/v1/settings/display` + parameters: + - name: twenty_four_hour_time + in: query + description: | + Whether time should be [displayed in 24-hour notation](/help/change-the-time-format). + schema: + type: boolean + example: true + - name: dense_mode + in: query + description: | + This setting has no effect at present. It is reserved for use in controlling + the default font size in Zulip. + schema: + type: boolean + example: true + - name: starred_message_counts + in: query + description: | + Whether clients should display the [number of starred + messages](/help/star-a-message#display-the-number-of-starred-messages). + schema: + type: boolean + example: true + - name: fluid_layout_width + in: query + description: | + Whether to use the [maximum available screen width](/help/enable-full-width-display) + for the webapp's center panel (message feed, recent topics) on wide screens. + schema: + type: boolean + example: true + - name: high_contrast_mode + in: query + description: | + This setting is reserved for use to control variations in Zulip's design + to help visually impaired users. + schema: + type: boolean + example: true + - name: color_scheme + in: query + description: | + Controls which [color theme](/help/night-mode) to use. + + * 1 - Automatic + * 2 - Night mode + * 3 - Day mode + + Automatic detection is implementing using the standard `prefers-color-scheme` + media query. + content: + application/json: + schema: + type: integer + enum: + - 1 + - 2 + - 3 + example: 1 + - name: translate_emoticons + in: query + description: | + Whether to [translate emoticons to emoji](/help/enable-emoticon-translations) + in messages the user sends. + schema: + type: boolean + example: true + - name: default_language + in: query + description: | + What [default language](/help/change-your-language) to use for the account. + + This controls both the Zulip UI as well as email notifications sent to the user. + + The value needs to be a standard language code that the Zulip server has + translation data for; for example, `"en"` for English` or `"de"` for German. + content: + application/json: + schema: + type: string + example: "en" + - name: default_view + in: query + description: | + The [default view](/help/change-default-view) used when opening a new + Zulip webapp window or hitting the `Esc` keyboard shortcut repeatedly. + + * "recent_topics" - Recent topics view + * "all_messages" - All messages view + schema: + type: string + example: all_messages + - name: left_side_userlist + in: query + description: | + Whether the users list on left sidebar in narrow windows. + + This feature is not heavily used and is likely to be reworked. + schema: + type: boolean + example: true + - name: emojiset + in: query + description: | + The user's configured [emoji set](/help/emoji-and-emoticons#use-emoticons), + used to display emoji to the user everything they appear in the UI. + + * "google" - Google modern + * "google-blob" - Google classic + * "twitter" - Twitter + * "text" - Plain text + schema: + type: string + example: google + - name: demote_inactive_streams + in: query + description: | + Whether to [demote inactive streams](/help/manage-inactive-streams) in the left sidebar. + + * 1 - Automatic + * 2 - Always + * 3 - Never + content: + application/json: + schema: + type: integer + enum: + - 1 + - 2 + - 3 + example: 1 + - name: timezone + in: query + description: | + The user's [configured timezone](/help/change-your-timezone). + + Timezone values supported by the server are served at + [/static/generated/timezones.json](/static/generated/timezones.json). + content: + application/json: + schema: + type: string + example: "Asia/Kolkata" + responses: + "200": + description: Success + content: + application/json: + schema: + allOf: + - $ref: "#/components/schemas/JsonSuccessBase" + - additionalProperties: false + properties: + result: {} + msg: {} + twenty_four_hour_time: + type: boolean + description: | + The setting for `twenty_four_hour_time`, if it was changed in this request. + dense_mode: + type: boolean + description: | + The setting for `dense_mode`, if it was changed in this request. + This setting is however reserved for future, and can not be + modified in production environment. + starred_message_counts: + type: boolean + description: | + The setting for `starred_message_counts`, if it was changed + in this request. + fluid_layout_width: + type: boolean + description: | + The setting for `fluid_layout_width`, if it was changed + in this request. + high_contrast_mode: + type: boolean + description: | + The setting for `high_contrast_mode`, if it was changed in + this request. + This setting is however reserved for future, and can not be + modified in production environment. + color_scheme: + type: integer + description: | + The numerical key corresponding to new `color_scheme` if it was changed in this request. + translate_emoticons: + type: boolean + description: | + The setting for `translate_emoticons`, if it was changed in this request. + default_language: + type: string + description: | + The language code corresponding to new `default_language` if it was changed in this request. + default_view: + type: string + description: | + The new setting for `default_view`, if it was changed in this request. + left_side_userlist: + type: boolean + description: | + The setting for `left_side_userlist`, if it was changed in this request. + emojiset: + type: string + description: | + The string identifier corresponding to new `emojiset` if it was changed in this request. + demote_inactive_streams: + type: integer + description: | + The numerical key corresponding to new `demote_inactive_streams` setting if it was changed in this request. + timezone: + type: string + description: | + The setting for `timezone`, if it was changed in this request. + example: + { + "emojiset": "google", + "left_side_userlist": true, + "msg": "", + "result": "success", + } /streams: get: operationId: get_streams diff --git a/zerver/tests/test_openapi.py b/zerver/tests/test_openapi.py index 800356692a..909724e4cf 100644 --- a/zerver/tests/test_openapi.py +++ b/zerver/tests/test_openapi.py @@ -266,8 +266,6 @@ class OpenAPIArgumentsTest(ZulipTestCase): "/settings", "/users/me/avatar", "/users/me/api_key/regenerate", - # Not very useful outside the UI - "/settings/display", # Much more valuable would be an org admin bulk-upload feature. "/users/me/profile_data", #### Should be documented as part of interactive bots documentation