Instance-level settings page

Author: Yihui Wang
Last edit: May 30, 2023

Overview

This document provides a template that is applicable to the settings page within an instance.

Default instance-level settings page

1. Filter: The search box supports filtering automatically, as soon as the user starts typing. The user can only filter by one input at a time.
2. Group titles (optional): Settings could be grouped in cards. The group title is optional.
3. Boolean type setting: The current status (on/off) is displayed next to the settings label. Clicking on the toggle button could change the status.
4. Integer/number type setting: The current value is displayed under the description. Clicking on the pencil icon allows the user to edit inline, or can trigger a modal for more complex edits.
5. Helper text (optional): For some of the settings, helper text may be needed to provide additional guidance. The icon indicates the property of this helper text.
6. String type setting: The current value is displayed under the description. Row height may be variable and sizes to the value. Clicking on the pencil icon allows the user to edit inline, or can trigger a modal for more complex edits.

Group settings

Settings could be grouped into different cards. The group title is optional. Determine when and how to group based on the following rules:

• Avoid artificial groupings.
• Items should be grouped when they have associated meanings.
• Items should be grouped if values are dependent on each other, i.e. some settings will be hidden or shown based on the values of other settings.
• Items should be grouped if they need to be saved together

Card layout

The structure and layout of each card are as following specs.

A card should have a card title (optional), a full-width divider, and a card body that includes all settings. Within the card body, each setting is separated by a divider.

In the example above, the card structure should be organized like this:

• Card title
• Full-width divider
• Card body
  • Setting 1
    • Setting label
    • Setting description
    • Action button
  • Spaced divider
  • Setting 2
    • Setting label
    • Setting description
    • Setting value
    • Action button

Progressive disclosure settings

Some settings will be hidden or shown based on the values of other settings. Here are some possible cases.

Responsive behavior

The maximum width of a card is 55rem. These cards will take up the whole width of the page by default, as shown in the following screenshots. When the page width exceeds 848px, the cards will maintain the maximum width.

Edit settings

Boolean type setting

For boolean type settings, changes will be saved directly after the user clicks on the toggle button.

1. Toast alert: According to the response from the API call, a success/error toast alert will be displayed. Every setting raises an individual toast alert.
2. Status: Text changes to reflect the current status.
3. Toggle button: Toggle button changes to reflect the current status.

Integer/number type setting

For integer/number type settings, clicking on the pencil icon will enable the inline edit in a row. For more complex edits, clicking on the pencil icon could also trigger a modal or even drill down to a new page. Settings will be refreshed after the user saves them.

1. Value: Shows the current value.
2. Number input: Allows the user to enter and modify a numeric value. The unit could be static or editable according to the specific use case.
3. Action group: Allows the user to save or cancel changes.
4. Toast alert: According to the response from the API call, a success/error toast alert will be displayed. Every setting raises an individual toast alert.

String type setting

For string type settings, clicking on the pencil icon will enable the inline edit in a row. For more complex edits, clicking on the pencil icon could also trigger a modal or even drill down to a new page. Settings will be refreshed after the user saves them.

1. Value: Shows the current value.
2. Text input: Allows the user to modify a string type value. Row height could be sized according to the value.
3. Toast alert: According to the response from the API call, a success/error toast alert will be displayed. Every setting raises an individual toast alert.

Confirmation prompt

Clarify risk before disabling

For the changes that may lead to potential risks, provide a confirmation modal before the user saves the changes. Here is an example:

Leave without saving

When the user tries to leave a page with unsaved changes, the following confirmation prompt should appear on the screen to provide a warning.

Validations

Pass thresholds

In the case of the integer/number type setting, it is possible to configure a threshold. When a threshold is applied to the input, the left/right buttons of the number input control will be disabled once the numeric value surpasses the specified threshold. This prevents users from increasing or decreasing the value beyond the defined limit.

Maximum length

In the case of the string type setting, it is possible to define a maximum length. The client-side validation ensures that the length of the input does not exceed the specified maximum. This validation occurs when the input field loses focus, ensuring that the entered text adheres to the length constraint.

1. Saving action: The save button should be disabled if the text input doesn’t pass the validation.

Filter settings

The search box supports filtering automatically, as soon as the user starts typing. The user can only filter by one input at a time.

Both the labels and the descriptions will be compared with the search input. All the matches would be highlighted. The highlight color is gold-50 (see PatternFly example for more details).

Toast alerts

Time-outs

The time-outs behavior follows the general pattern provided by Console Dot. Refer to the guidelines of c.rh.c for more details.

Content

The general patterns and examples for toast alert content are as followed.