List View

List View provides a list of objects in the system (e.g. filming locations) that users can quickly browse through and take action on.

  • Usage
  • Configuration
  • Examples

List View organizes content into a continuous group that allows users to take action on one or more items in that group. List View is most commonly used for managing objects in the system where one or more attributes of those objects are relevant (e.g. users or groups of users).

While List View has a lot in common with the Table View component in that both display data, List View is best used for situations when the data being displayed is relatively simple and the volume of that data is low. Table View is better for complex, varied data sets where the volume is high.

Anatomy

  1. Title

  2. Add list item button

  3. List item

  4. List item description

  5. Actions

Best practices

  • Position the icon for the primary action users take for objects in the list on the right-most portion of the list item, followed by secondary and tertiary actions to the left of the primary action icon.
  • Sort lists in ways that make sense for the content (i.e. alphabetical, chronological).
  • Configure List View no smaller than small on the grid to ensure the content is legible.
  • Be consistent when using different display treatments (i.e. avoid mixing two different treatments for items at the same hierarchical level in the same list).

Common patterns

With Section Header

When displaying multiple Information Lists, a Section Header can help organize and provide structure to the screen.

Properties

  • Title field – Optional. The title that displays for the list.
  • Show Title checkbox – Optional. If selected, the title of the list displays.
  • Show Icons checkbox – Optional. If selected, the icon displays for each list item.
  • Enable Actions checkbox – Optional. If selected, the action icons display for each list item.
  • Show Descriptions checkbox – Optional. If selected, the description that displays for each list item.
  • Icon Treatment drop-down – Optional. Specifies how to display the icons that display for the list items if the Show Icons checkbox is selected:
    • Plain – The icon displays with no background.
    • Circle Background – The icon displays against a circle background.
    • Square Background – The icon displays against a square background.
  • Data Source field – Required. The query that retrieves the data for the List View, based on the data model. The following information is returned from the specified source: name, description (optional), icon (optional), and ID (internal use only).
  • Actions section – Conditionally required if the Enable Actions checkbox is selected. A section of properties used to configure the actions available for each list item:
    • Icon field – Conditionally required if the Enable Actions checkbox is selected. The UI icon that displays on the screen.
    • API field – Conditionally required if the Enable Actions checkbox is selected. The API called when the user selects the action.
  • Show Total Quantity checkbox – Optional. If selected, the total quantity of list items displays.
  • Maximum Items field – Required. The maximum number of list items. Defaults to 100.
  • Allow Add Action checkbox – Optional. If selected, a button displays at the top of the list, which allows users to add a list item.
  • Allow Selection checkbox – Optional. If selected, a checkbox displays on each list item, which allows users to select the item.
  • Selection Type drop-down – Conditionally required if the Allow Selection checkbox is selected. Specifies whether to allow multiple list items to be selected at the same time:
    • Multi-Selection – (default) Multiple list items can be selected at the same time.
    • Single Selection – Only one list item can be selected at a time.
  • Allow Keyword Search checkbox – Optional. If selected, users can search the items in the list with a Keywords field that displays at the top.
  • Add Action Label field – Optional. The label that displays on the button that allows users to add a list item.
  • Message If No Results field – Required. The message that displays if there is no data available.
  • Visibility Permission field – Optional. The user's permission to access the component. If a user is not assigned a role that includes this permission, they cannot view or interact with the component.
  • Visibility Permission Not Assigned drop-down – Optional. If the user does not have permission to access the component, specifies whether to hide or disable it:
    • Hide – The component is hidden.
    • Disable – The component is visible but not cannot be interacted with.

Emitted events

  • On Item Add – The user chooses to add a list item.
  • On Item Select – The user selects a list item.

Functions

  • Get Selected Item – When invoked in an event, returns the selected list item and its relevant data.
  • Set Selected Items – When invoked in an event, selects the specified list item.
  • Set Updated Items – When invoked in an event, the list items are refreshed with updates.

With title, actions, and add item button

  • Title included.
  • Show Title selected.
  • Show Icons selected.
  • Enable Actions selected.
  • Show Descriptions selected.
  • Icon Treatment is set to Plain.
  • Actions:
    • Icon included.
    • API included.
  • Allow Add Action selected.
  • Allow Selection not selected.
  • Allow Keyword Search not selected.
  • Add Action Label included.

With actions only

  • Title not included.
  • Show Icons selected.
  • Enable Actions selected.
  • Show Descriptions selected.
  • Icon Treatment is set to Plain.
  • Actions:
    • Icon included.
    • API included.
  • Allow Add Action not selected.
  • Allow Selection not selected.
  • Allow Keyword Search not selected.
  • Add Action Label not included.

With multi-selection only

  • Title not included.
  • Show Icons selected.
  • Enable Actions not selected.
  • Show Descriptions selected.
  • Allow Add Action not selected.
  • Allow Selection not selected.
  • Allow Keyword Search not selected.
  • Allow Selection selected.
  • Selection Type set to Multi-Selection.
  • Add Action Label not included.

With title only

  • Title included.
  • Show Title selected.
  • Show Icons not selected.
  • Enable Actions not selected.
  • Show Descriptions selected.
  • Allow Add Action not selected.
  • Allow Selection not selected.
  • Allow Keyword Search not selected.
  • Add Action Label not included.