Skip to content

Latest commit

 

History

History
249 lines (158 loc) · 6.56 KB

collection-preferences.md

File metadata and controls

249 lines (158 loc) · 6.56 KB
Raw

Collection preferences (CollectionPreferences)

Enables the user to manage display preferences within a collection.

Properties

cancelLabel

Label of the cancel button in the modal footer.

Type: String

Required: Yes

className

Adds the specified classes to the root element of the component.

Type: String

Required: No

confirmLabel

Label of the confirm button in the modal footer.

Type: String

Required: Yes

customPreference

Configures custom preferences. The function receives two parameters:

  • customValue (CustomPreferenceType) - Current value for your custom preference. It is initialized using the value you provide in preferences.custom.
  • setCustomValue - A function that is called to notify a state update.

It should return the content of your custom preference, for example:

(customValue, setCustomValue) => (
  <Checkbox checked={customValue} onChange={({ detail }) => setCustomValue(detail.checked)} />
)

When the user confirms the changes, the new value is passed in the detail.custom property of the onConfirm listener. When the user cancels the changes, the customValue is reset to the one present in preferences.custom property.

Display

  • If any of the built-in preferences (pageSizePreference, wrapLinesPreference, or visibleContentPreference) are displayed, the custom content is displayed at the bottom of the left column within the modal.
  • If no built-in preference is displayed, the custom content occupies the whole modal.

Type: (customValue: CustomPreferenceType, setCustomValue: React.Dispatch) => React.ReactNode

Required: No

disabled

Determines whether the preferences trigger button is disabled.

Type: Boolean

Default: false

Valid values: true | false

Required: No

id

Adds the specified ID to the root element of the component.

Type: String

Required: No

pageSizePreference

Configures the built-in "page size selection" preference. If you set it, the component displays this preference in the modal.

It contains the following:

  • title (string) - Specifies the text displayed at the top of the preference.
  • options - Specifies an array of options for page size selection. Each entry contains:
    • value (number) - The value for the radio button (that is, the number of items per page).
    • label (string) - A label for the radio button (for example, "10 resources").

You must set the current value in the preferences.pageSize property.

Type:

CollectionPreferencesProps.PageSizePreference {
  options: ReadonlyArray<CollectionPreferencesProps.PageSizeOption>
  title: string
}

Required: No

preferences

Specifies the current preference values. This includes both built-in and custom preferences. It contains the following:

  • pageSize (number) - (Optional)
  • wrapLines (boolean) - (Optional)
  • visibleContent (ReadonlyArray) - Specifies the list of visible content ids. The order of the ids does not influence the display.
  • custom (CustomPreferenceType) - Specifies the value for your custom preference.

Type:

CollectionPreferencesProps.Preferences {
  custom?: CollectionPreferencesProps.Preferences.CustomPreferenceType
  pageSize?: number
  visibleContent?: ReadonlyArray<string>
  wrapLines?: false | true
}

Required: No

title

Specifies the title of the preferences modal dialog. It is also used as an aria-label for the trigger button.

Type: String

Required: Yes

visibleContentPreference

Configures the built-in "visible content selection" preference (for example, visible columns in a table). If you set it, the component displays this preference in the modal.

It contains the following:

  • title (string) - Specifies the text displayed at the top of the preference.
  • options - Specifies an array of groups of options for visible content selection.

Each group of options contains the following:

  • label (string) - The text to display as a title for the options group.
  • options - Specifies an aray of options in the group. Each option contains the following:
    • id (string) - Corresponds to a column id for tables or to a section id for cards.
    • label (string) - Specifies a short description of the content.
    • editable (boolean) - (Optional) Determines whether the user is able to toggle its visibility. This is true by default.

You must set the current list of visible content ids in the preferences.visibleContent property.

Type:

CollectionPreferencesProps.VisibleContentPreference {
  options: ReadonlyArray<CollectionPreferencesProps.VisibleContentOptionsGroup>
  title: string
}

Required: No

wrapLinesPreference

Configures the built-in "wrap lines" preference. If you set it, the component displays this preference in the modal.

It contains the following:

  • label (string) - Specifies the label for the option checkbox.
  • description (string) - Specifies the text displayed below the checkbox label.

You must set the current value in the preferences.wrapLines property.

Type:

CollectionPreferencesProps.WrapLinesPreference {
  description: string
  label: string
}

Required: No

Events

onCancel

Called when the user cancels a preference change using the cancel button in the modal footer or by dismissing the modal.

Cancelable: No

onConfirm

Called when the user confirms a preference change using the confirm button in the modal footer. The event detail contains the following:

  • pageSize (number) - (Optional) The selected page size value. Available only if you specify the pageSizePreference property.
  • wrapLines (boolean) - (Optional) The current line wrapping preference value. Available only if you specify the wrapLinesPreference property.
  • visibleContent (ReadonlyArray) - (Optional) The list of selected content ids. Available only if you specify the visibleContentPreference property.
  • custom (CustomPreferenceType) - (Optional) The selected value for your custom preference.

The values for all configured preferences are present even if the user didn't change their values.

Detail type:

CollectionPreferencesProps.Preferences {
  custom?: CollectionPreferencesProps.Preferences.CustomPreferenceType
  pageSize?: number
  visibleContent?: ReadonlyArray<string>
  wrapLines?: false | true
}

Cancelable: No

License Summary

The documentation is made available under the Creative Commons Attribution-ShareAlike 4.0 International License. See the LICENSE file.