Element: <oj-c-list-view>

CORE PACK

Oracle® JavaScript Extension Toolkit (JET)
19.0.0
G25385-01

Since:
  • 15.0.0
Module:
  • list-view

QuickNav

Slots

Attributes

Events

Methods

Type Definitions

Documentation-only Types

Other Topics


JET ListView Component

Description: The JET ListView enhances a HTML list element into a themable, WAI-ARIA compliant, mobile friendly component with advance interactive features. The child content can be configured via a DataProvider which should be used for mutable data.

For migration information from oj-list-view refer to the migration section in the API docs.

Data

The JET ListView gets its data from a DataProvider.

ArrayDataProvider - Use this when the underlying data is an array object or an observableArray. In the observableArray case, ListView will automatically react when items are added or removed from the array. See the documentation for ArrayDataProvider for more details on the available options.

Example of data provider content


  <oj-c-list-view aria-label="Accessible Summary" data="[[dataProvider]]">
  </oj-c-list-view>

Check out the Listview Basic demo

Coming Features

These features will be the domain of new, specialized components

  • Cards in grid layout
  • Cards in waterfall layout
  • Grouped list
  • Expandable list

These features will be available in forthcoming versions

  • Drag and drop between components
  • Managing scroll position

Keyboard End User Information

Target Key Action
List Item F2 Enters tabbable mode. This enables keyboard action on elements inside the item, including navigate between focusable elements inside the item. It can also be used to exit tabbable mode if already in tabbable mode.
Enter Enters tabbable mode if enterKeyFocusBehavior is "focusWithin" (default). This enables keyboard action on elements inside the item, including navigate between focusable elements inside the item.
Esc Exits tabbable mode.
Tab When in tabbable mode, navigates to next focusable element within the item. If the last focusable element is reached, shift focus back to the first focusable element. When not in tabbable mode, navigates to next focusable element on page (outside ListView).
Shift+Tab When in tabbable mode, navigates to previous focusable element within the item. If the first focusable element is reached, shift focus back to the last focusable element. When not in tabbable mode, navigates to previous focusable element on page (outside ListView).
DownArrow Move focus to the item below.
UpArrow Move focus to the item above.
Shift+DownArrow Extend the selection to the item below.
Shift+UpArrow Extend the selection to the item above.
Space Toggles to select and deselect the current item while maintaining previously selected items.
Shift+Space Toggles to select and deselect the current item while maintaining previously selected items.
Shift+Cmd/Ctrl+UpArrow Reorder the current item up.
Shift+Cmd/Ctrl+DownArrow Reorder the current item down.
Ctrl+Space Toggles to select and deselect the current item while maintaining previously selected items.

Accessibility

Application should specify a value for the aria-label attribute with a meaningful description of the purpose of this list.

Note that ListView uses the grid role and follows the Layout Grid design as outlined in the grid design pattern

Nesting collection components such as ListView, Table, TreeView, and ListView inside of ListView is not supported.

When reorder feature is enabled, application should specify a live region which contains an announcement to notify assistive technologies that the item reordering happens.

Custom Colours

Using colors, including background and text colors, is not accessible if it is the only way information is conveyed. Low vision users may not be able to see the different colors, and in high contrast mode the colors are removed. The Redwood approved way to show status is to use badge.

Item Context

For all item options, developers can specify a function as the return value. The function takes a single argument, which is an object that contains contextual information about the particular item. This gives developers the flexibility to return different value depending on the context.

The context parameter contains the following keys:

Key Description
data The data of the item. Note this is made available primarily to ease migration. Applications should get the data from the item property instead.
item An object that contains the data and metadata for the item.
isTabbable A boolean indicating whether the item is in tabbable mode or not. This should be used to implement conditional behavior for all tabbable elements, this avoids creating a keyboard trap when tabbing through a List.
This can be implemented as a conditional tabindex, for example tabindex="[[!item.isTabbable && '-1']]".
When composing with core pack components, this is not needed, as they are tabbable mode aware.

The following keys are not currently supported:

Key Description
componentElement A reference to the root element of ListView.
datasource A reference to the data source object.
index The index of the item, where 0 is the index of the first item. In the hierarchical case the index is relative to its parent.
key The key of the item (this duplicates item.metadata.key and has been deprecated)
metadata The metadata of the item (this is instead available in item)
parentElement This will be supported by the Hierarchical list component and no longer applies to list view..

Custom Data Attributes

ListView supports the following custom data attributes.

Name Description Example
data-oj-as Provides an alias for a specific template instance and has the same subproperties as the $current variable. 
<oj-c-list-view id="listView">
  <template slot="itemTemplate" data-oj-as="item">
  </template>
</oj-c-list-view>
data-oj-clickthrough

Specify on any element inside an item where you want to control whether ListView should perform actions triggered by a click event originating from the element or one of its descendants.

For example, if you specify this attribute with a value of "disabled" on a link inside an item, then ListView will not select or trigger itemAction event to be fired when user clicks on the link.

Note that the currentItem will still be updated to the item that the user clicked on.

Also note you do not need to set this attribute on core pack components such as oj-c-button, as it natively supports disabling clickthrough.

 
<oj-c-list-view id="listView">
  <template slot="itemTemplate">
    <a href="#" data-oj-clickthrough="disabled"></a>
  </template>
</oj-c-list-view>
data-oj-manage-tabs

ListView does not manipulate the tabindex of the item content. Applications should set the tabIndex of any focusable element based on the isTabbableMode property from the context pass to the itemTemplate.

However, there will be cases where you can't control the tabindex of the content, for example, if you are using components from another team.

In that case, applications can specify this attribute on the element or one of its ancestors so that when the itemTemplate is processed, it will scan and manipulate the tabindex of any focusable elements.

 
<oj-c-list-view id="listView">
  <template slot="itemTemplate">
    <some-component-with-focusable-elements data-oj-manage-tabs></some-component-with-focusable-elements>
  </template>
</oj-c-list-view>

Suggestion Items

If ItemMetadata returned by the DataProvider contains suggestion field, ListView will apply special visual to those items. The DataProvider must ensure the suggestion items are the first items returned by the initial fetchFirst call.


Usage

Signature:

interface CListViewElement<K extends string | number,D>

Typescript Import Format
//To typecheck the element APIs, import as below.
import { CListViewElement } from "oj-c/list-view";

//For the transpiled javascript to load the element's module, import as below
import "oj-c/list-view";

For additional information visit:

Note: Application logic should not interact with the component's properties or invoke its methods until the BusyContext indicates that the component is ready for interaction.


Slots

JET components that allow child content support slots. Please see the slots section of the JET component overview doc for more information on allowed slot content and slot types.

itemTemplate

The itemTemplate slot is used to specify the template for rendering each item in the List. The slot content must be a <template> element.

When the template is executed for each item, it will have access to the binding context containing the following properties:

  • $current - an object that contains information for the current item.
Properties of $current:
Name Type Description
data D The data of the item. Note this is made available primarily to ease migration. Applications should get the data from the item property instead.
isTabbable boolean A boolean indicating whether the item is in tabbable mode or not. Template elements should not be tab-stops when the item is not in tabbable mode, this context can be used to implement conditional behavior for all tabbable child elements.
item Item.<K, D> Contains the data and metadata of the item.

noData

The noData slot is used to specify the content to display when the list is empty. The slot content must be a <template> element. If not specified then a default no data message will be displayed.

skeletonTemplate

The skeletonTemplate slot is used to specify the template for rendering each skeleton while waiting for data during initial load as well as load more on scroll. The slot content must be a <template> element. If not specified then the default skeleton will display.

When the template is executed for each skeleton, it will have access to the binding context containing the following properties:

  • $current - an object that contains information for the current skeleton.
Properties of $current:

NameTypeDescription
loadingStatus'initial' | 'loadMore'Whether the skeletons are rendered for initial load of data or for load more data in CardView
indexnumberThe index prop can be used to determine the order of different skeletons that to be place to create the whole list item skeleton.

Example of skeletonTemplate slot usage.


<oj-c-list-view
id="cardview"
       id="listview"
       class="demo-list-view"
       aria-label="listview with skeleton"
       data="[[dataProvider]]">
   <template slot="skeletonTemplate" data-oj-as="context">
     <div>
               <oj-bind-if test="[[context.loadingStatus === 'initial']]">
               <oj-bind-if test="[[context.index % 3 === 0]]">
                   <oj-c-skeleton height="4x" width="4x">
                   </oj-c-skeleton>
               </oj-bind-if>
               <oj-bind-if test="[[context.index % 3 === 1]]">
                <oj-c-skeleton height="4x" width="6x">
                   </oj-c-skeleton>
               </oj-bind-if>
               <oj-bind-if test="[[context.index % 3 === 2]]">
                    <oj-c-skeleton height="4x" width="8x">
                   </oj-c-skeleton>
               </oj-bind-if>
               </oj-bind-if>
               <oj-bind-if test="[[context.loadingStatus === 'loadMore']]">
                    <oj-c-skeleton height="4x" width="8x">
                   </oj-c-skeleton>
               </oj-bind-if>
           </div>
       </template>
       <template slot="itemTemplate" data-oj-as="item">
         <oj-c-list-item-layout>
           <<pan class="oj-typography-body-md oj-text-color-primary">
             <oj-bind-text value="[[item.item.data.name]]">
           </span>
           <oj-c-avatar slot="leading" size="xs" src="[[item.item.data.image]]">
           <span slot="secondary" class="oj-typography-body-sm oj-text-color-secondary">
             <oj-bind-text value="[[item.item.data.title]]">
           </span>
         </oj-c-list-item-layout>
       </template>
</oj-c-list-view>
Properties of $current:
Name Type
index number
loadingStatus "initial" | "loadMore"

Attributes

context-menu-config :oj-c.ListView.ContextMenuConfig.<K, D>

Specifies a context menu configuration. It takes the keys `accessibleLabel` and `items`, where `accessibleLabel` is optional and items required . `items` function returns an array of menu item object representations that indicates what menu items are going to be part of menu based on some specific context menu context.
Context Menu Item TypeDef
ContextMenuSeparator{ type: 'separator'}
MenuItem{ type?: 'item'; label: string; key: string; disabled?: boolean; onAction?: () => void; startIcon?: MenuIcon; endIcon?: MenuIcon; variant?: 'standard' | 'destructive'; };
ContextMenuSubMenu{ type: 'submenu'; label?: string; disabled?: boolean; startIcon?: string; items?: Array<ContextMenuItems>; };
ContextMenuSelectSingle{ type: 'selectsingle'; key?: string; items?: Array<MenuSelectItem>; selection?: string; onSelection?: (detail: { value: string }) => void; };
ContextMenuSelectMultiple{ type: 'selectmultiple'; key?: string; items?: Array<MenuSelectItem>; selection?: Array<string>; onSelection?: (detail: { value: Array<string> }) => void; };
MenuIcon{ type?: 'class'; class: string; } | { type: 'img'; src: string; };
MenuSelectItem{ label: string; disabled?: boolean; endIcon?: MenuIcon; value: string; }
Names
Item Name
Property contextMenuConfig
Property change event contextMenuConfigChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-context-menu-config-changed

(readonly) current-item :K

The key of the item that currently has keyboard focus
Supports writeback:
  • true
Names
Item Name
Property currentItem
Property change event currentItemChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-current-item-changed

current-item-override :{ rowKey: K; }

The key of the item that will have keyboard focus
Names
Item Name
Property currentItemOverride
Property change event currentItemOverrideChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-current-item-override-changed

current-item-override.row-key* :K

Names
Item Name
Property currentItemOverride.rowKey

data :(DataProvider.<K, D>|null)

The data source for ListView. Must be of type DataProvider.
Names
Item Name
Property data
Property change event dataChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-data-changed

gridlines :oj-c.ListView.Gridlines

Specifies whether the horizontal grid lines should be visible. By default gridlines are hidden. It takes the keys `item`, `top` and `bottom`, each of which are optional and take a value of "hidden" or "visible". `item` toggles the presence of bottom gridlines except the last item, and `top` and `bottom` toggle the initial and trailing gridlines. By default all gridlines are hidden.
Names
Item Name
Property gridlines
Property change event gridlinesChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-gridlines-changed

item :{ padding?: 'disabled' | 'enabled' | oj-c.ListView.ItemPadding; enterKeyFocusBehavior?: 'none' | 'focusWithin'; }

The item option contains a subset of options for items.
Names
Item Name
Property item
Property change event itemChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-item-changed

reorderable :{ items?: 'enabled' | 'disabled'; }

The reorder option contains a subset of options for reordering items.

The following options are supported:

  • items: Enable or disable reordering the items within the same ListView using drag and drop or keyboard. Specify 'enabled' to enable reordering. Setting the value to "disabled" or setting the "reorderable" property to null (or omitting it), disables reordering support.
Names
Item Name
Property reorderable
Property change event reorderableChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-reorderable-changed

reorderable.items :"disabled"|"enabled"

Default Value:
  • "disabled"
Names
Item Name
Property reorderable.items

scroll-policy-options :{ fetchSize?: number; scroller?: string; }

scrollPolicy options.

The following options are supported:

  • fetchSize: The number of items fetched each time when scroll to the end.
  • scroller: The css selector that locates the element in which listview uses to determine the scroll position as well as the maximum scroll position where scroll to the end will trigger a fetch. If not specified then the root element of listview is used.
By default, the next block of rows is fetched when the user scrolls to the end of the list/scroller. The fetchSize option determines how many rows are fetched in each block.

Names
Item Name
Property scrollPolicyOptions
Property change event scrollPolicyOptionsChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-scroll-policy-options-changed

scroll-policy-options.fetch-size :number

Names
Item Name
Property scrollPolicyOptions.fetchSize

scroll-policy-options.scroller :string

Names
Item Name
Property scrollPolicyOptions.scroller

selected :ImmutableKeySet.<K>

The current selected items in the ListView. An empty KeySet indicates nothing is selected. Note that property change event for the deprecated selection property will still be fire when selected property has changed. In addition, AllKeySetImpl set can be used to represent select all state. In this case, the value for selection would have an 'inverted' property set to true, and would contain the keys of the items that are not selected.
Supports writeback:
  • true
Names
Item Name
Property selected
Property change event selectedChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-selected-changed

selection-mode :"none"|"single"|"singleRequired"|"multiple"|"multipleToggle"

The type of selection behavior that is enabled on the ListView. This attribute controls the number of selections that can be made via selection gestures at any given time.

If the specified value is not none, selection gestures will be enabled, and the ListView's selection styling will be applied to all items specified by the selected attribute. If singleRequired is specified, then the behavior is the same as single except that ListView will ensure there is an item selected at all times. Specifically, the user will not be able to de-selected a selected item. And if selection is initially empty, ListView will select the first item. If none is specified, selection gestures will be disabled, and the ListView's selection styling will not be applied to any items specified by the selected attribute.

Changing the value of this attribute will not affect the value of the selected attribute.

Supported Values:
Value Description
multiple Multiple items can be selected at the same time with the 'replace' selection behavior. For example, clicking on an already selected item will not affect that item's selection, and clicking on a non-selected item will select that item and deselect any other previously selected items. In order to perform additive selections, users can click on selector checkboxes, use spacebar, or ctrl/cmd click on individual items to perform 'toggle' selection gestures.
multipleToggle Multiple items can be selected at the same time with the 'toggle' selection behavior. For example, clicking on an already selected item will deselect that item, and clicking on any non-selected item will select that item without affecting any previously selected items.
none Selection is disabled.
single Only a single item can be selected at a time.
singleRequired Only a single item can be selected at a time. In addition, ListView will also ensure that an item is selected at all time.
Default Value:
  • "none"
Names
Item Name
Property selectionMode
Property change event selectionModeChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-selection-mode-changed

Events

ojContextMenuAction

Triggered when a menu item is clicked, whether by keyboard, mouse, or touch events.
Properties:

All of the event payloads listed below can be found under event.detail. See Events and Listeners for additional information.

Name Type
contextMenuContext oj-c.ListView.ListItemContextProps.<K, D>
menuItemKey string

ojContextMenuSelection

Triggered when a select menu item is clicked, whether by keyboard, mouse, or touch events.
Properties:

All of the event payloads listed below can be found under event.detail. See Events and Listeners for additional information.

Name Type
contextMenuContext oj-c.ListView.ListItemContextProps.<K, D>
menuSelectionGroupKey string
value string|Array<string>

ojFirstSelectedItem

Triggered when data for the first selected item is available. This can occurred when:
  • ListView is initialized with a selection or first item is selected due to singleRequired selection mode.
  • Selection has changed.
  • Data for the first selected item is updated.
Note this event will only be enabled if selection-mode is set to singleRequired.
Properties:

All of the event payloads listed below can be found under event.detail. See Events and Listeners for additional information.

Name Type
data D
key K

ojItemAction

Triggered when user performs an action gesture on an item while ListView is in navigation mode. The action gestures include:
  • User clicks anywhere in an item
  • User taps anywhere in an item
  • User pressed enter key while item has focus
Properties:

All of the event payloads listed below can be found under event.detail. See Events and Listeners for additional information.

Name Type
context oj-c.ListView.ListItemContextProps.<K, D>

ojReorder

Triggered after items are reordered within ListView via drag and drop or keyboard.
Properties:

All of the event payloads listed below can be found under event.detail. See Events and Listeners for additional information.

Name Type Description
itemKeys Array<K> An array of keys of the items that are moved
referenceKey K | null The key of the item where the moved items will be dropped after. If the moved items were dropped at the very beginning, the referenceKey will be null.
reorderedKeys Array<K> An array of keys matching the new order of items

Methods

getProperty(property) : {any}

Retrieves the value of a property or a subproperty.
Parameters:
Name Type Description
property string The property name to get. Supports dot notation for subproperty access.
Returns:
Type
any

setProperties(properties) : {void}

Performs a batch set of properties.
Parameters:
Name Type Description
properties object An object containing the property and value pairs to set.
Returns:
Type
void

setProperty(property, value) : {void}

Sets a property or a single subproperty for complex properties and notifies the component of the change, triggering a corresponding event.
Parameters:
Name Type Description
property string The property name to set. Supports dot notation for subproperty access.
value any The new value to set the property to.
Returns:
Type
void

Type Definitions

Documentation-only Types

Note: Type definitions in this section have been provided for documentation purposes and cannot be imported into application code.

ContextMenuConfig<K,D>

Properties:
Name Type Argument
accessibleLabel string <optional>
items (context: oj-c.ListView.ListItemContextProps<K, D>) => Array<oj-c.ListView.ContextMenuItems>

ContextMenuItems :(oj-c.ListView.MenuItem|oj-c.ListView.ContextMenuSeparator|oj-c.ListView.ContextMenuSubMenu|oj-c.ListView.ContextMenuSelectSingle|oj-c.ListView.ContextMenuSelectMultiple)

ContextMenuSelectMultiple

Properties:
Name Type Argument Description
items Array.<oj-c.ListView.MenuSelectItem> <optional>
 Specifies the array of select items that make up the select multiple.
key string A unique key associated with the select multiple.
onSelection (detail: oj-c.ListView.SelectMenuItemDetail<string[]>) => void <optional>
selection Array<string> <optional>
type "selectmultiple" Specifies a select multiple menu item.

ContextMenuSelectSingle

Properties:
Name Type Argument Description
items Array.<oj-c.ListView.MenuSelectItem> <optional>
 Specifies the array of select items that make up the select single.
key string A unique key associated with the select single.
onSelection (detail: oj-c.ListView.SelectMenuItemDetail<string>) => void <optional>
selection string <optional>
type "selectsingle" Specifies a select single menu item.

ContextMenuSeparator

Properties:
Name Type
type "separator"

ContextMenuSubMenu

Properties:
Name Type Argument Description
disabled boolean <optional>
 Specifies if the submenu is disabled (enabled by default).
items Array<string | oj-c.ListView.MenuItem | oj-c.ListView.ContextMenuSeparator | oj-c.ListView.ContextMenuSubMenu | oj-c.ListView.ContextMenuSelectSingle | oj-c.ListView.ContextMenuSelectMultiple> <optional>
key string <optional>
 A unique key associated with the submenu menu item.
label string <optional>
 The submenu label.
startIcon string <optional>
 Optional icon to render at the start of the submenu.
type "submenu" Specifies a submenu menu item.

Gridlines

Properties:
Name Type Argument
bottom "hidden" | "visible" <optional>
item "hidden" | "visible" <optional>
top "hidden" | "visible" <optional>

ItemPadding

Properties:
Name Type Argument
bottom "disabled" | "enabled" <optional>
end "disabled" | "enabled" <optional>
start "disabled" | "enabled" <optional>
top "disabled" | "enabled" <optional>

ListItemContextProps<K,D>

Properties:
Name Type Description
data D The data of the item. Note this is made available primarily to ease migration. Applications should get the data from the item property instead.
item Item.<K, D> Contains the data and metadata of the item.
Specifies a standard menu item.
Properties:
Name Type Argument Description
disabled boolean <optional>
 Specifies if the menu item is disabled (enabled by default).
endIcon { type?: 'class'; class: string; } | { type: 'img'; src: string; } <optional>
 Optional icon to render at the end of the menu item.
key string A unique key associated with the menu item.
label string The menu item label.
onAction function <optional>
 Optional callback function associated with the menu item.
startIcon { type?: 'class'; class: string; } | { type: 'img'; src: string; } <optional>
 Optional icon to render at the start of the menu item.
type "item" <optional>
 Specifies a standard menu item.
variant "standard" | "destructive" <optional>
 Specifies the menu item behavior.
Properties:
Name Type Description
at (index: number) => string | undefined Takes an integer value and returns the item at that index, allowing for positive and negative integers. Negative integers count back from the last item in the array.
Specifies a selectable item in a menu item.
Properties:
Name Type Argument Description
disabled boolean <optional>
 Specifies if the selectable item is disabled (enabled by default).
endIcon { type?: 'class'; class: string; } | { type: 'img'; src: string; } <optional>
 Optional icon to render at the end of the selectable item.
label string The selectable item label.
value string The value associated with the selectable item.

SelectMenuItemDetail<T extends oj-c.ListView.MenuSelection>

Properties:
Name Type
menuSelectionGroupKey string
value T