Description: The JET ListView enhances a HTML list element into a themable, WAI-ARIA compliant, mobile friendly component with advance interactive features.\nThe child content can be configured via a DataProvider which should be used for mutable data.
\n\nFor migration information from oj-list-view refer to the migration section in the API docs.\n\n
The JET ListView gets its data from a DataProvider.
\n\nArrayDataProvider - Use this when the underlying data is an array object or an observableArray. In the observableArray case, ListView will automatically react\nwhen items are added or removed from the array. See the documentation for ArrayDataProvider for more details on the available options.
\n\nExample of data provider content
\n\n <oj-c-list-view aria-label=\"Accessible Summary\" data=\"[[dataProvider]]\">\n </oj-c-list-view>\nCheck out the Listview Basic demo\n\n
These features will be the domain of new, specialized components
\nThese features will be available in forthcoming versions
\n| Target | \nKey | \nAction | \n
|---|---|---|
| List Item | \nF2 | \nEnters 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. | \n
| Enter | \nEnters tabbable mode if enterKeyFocusBehavior is \"focusWithin\" (default). This enables keyboard action on elements inside the item, including navigate between focusable elements inside the item. | \n|
| Esc | \nExits tabbable mode. | \n|
| Tab | \nWhen 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.\n When not in tabbable mode, navigates to next focusable element on page (outside ListView). | \n|
| Shift+Tab | \nWhen 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.\n When not in tabbable mode, navigates to previous focusable element on page (outside ListView). | \n|
| DownArrow | \nMove focus to the item below. | \n|
| UpArrow | \nMove focus to the item above. | \n|
| Shift+DownArrow | \nExtend the selection to the item below. | \n|
| Shift+UpArrow | \nExtend the selection to the item above. | \n|
| Shift+F10 | \nLaunch the context menu if there is one associated with the current item. | \n|
| Space | \nToggles to select and deselect the current item while maintaining previously selected items. | \n|
| Shift+Space | \nToggles to select and deselect the current item while maintaining previously selected items. | \n|
| Ctrl+Space | \nToggles to select and deselect the current item while maintaining previously selected items. | \n|
| Shift+Cmd/Ctrl+UpArrow | \nReorder the current item up. | \n|
| Shift+Cmd/Ctrl+DownArrow | \nReorder the current item down. | \n
\nTo make your component accessible, the application is required to include contextual information for screen readers using one or more of the following methods as appropriate:\n
Application should specify a value for the aria-label attribute with a meaningful description of the purpose of this list.
\nNote that ListView uses the grid role and follows the Layout Grid design as outlined in the grid design pattern
\nNesting collection components such as ListView, Table, TreeView, and ListView inside of ListView is not supported.
\nWhen reorder feature is enabled, application should specify a live region which contains an announcement to notify assistive technologies that the item reordering happens.
\n\nUsing colors, including background and text colors, is not accessible if it is the only way information is conveyed.\nLow vision users may not be able to see the different colors, and in high contrast mode the colors are removed.\nThe Redwood approved way to show status is to use badge.
\n\nFor 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.
\n\nThe context parameter contains the following keys:
\n| Key | \nDescription | \n
|---|---|
| data | \nThe data of the item. Note this is made available primarily to ease migration.\n Applications should get the data from the item property instead. | \n
| item | \nAn object that contains the data and metadata for the item. | \n
| isTabbable | \nA boolean indicating whether the item is in tabbable mode or not.\n This should be used to implement conditional behavior for all tabbable elements, this avoids creating a keyboard trap when tabbing through a List. \n This can be implemented as a conditional tabindex, for example tabindex=\"[[!item.isTabbable && '-1']]\".\n When composing with core pack components, this is not needed, as they are tabbable mode aware.\n | \n
The following keys are not currently supported:
\n\n| Key | \nDescription | \n
|---|---|
| componentElement | \nA reference to the root element of ListView. | \n
| datasource | \nA reference to the data source object. | \n
| index | \nThe index of the item, where 0 is the index of the first item. In the hierarchical case the index is relative to its parent. | \n
| key | \nThe key of the item (this duplicates item.metadata.key and has been deprecated) | \n
| metadata | \nThe metadata of the item (this is instead available in item) | \n
| parentElement | \nThis will be supported by the Hierarchical list component and no longer applies to list view.. | \n
ListView supports the following custom data attributes.\n
| Name | \nDescription | \nExample | \n
|---|---|---|
| data-oj-as | \nProvides an alias for a specific template instance and has the same subproperties as the $current variable. | \n\n | \n
| data-oj-clickthrough | \nSpecify on any element inside an item where you want to control whether ListView should perform actions triggered by\n a click event originating from the element or one of its descendants. \nFor example, if you specify this attribute with a value of \"disabled\" on a link inside an item, then ListView\n will not select or trigger itemAction event to be fired when user clicks on the link. \nNote that the currentItem will still be updated to the item that the user clicked on. \nAlso note you do not need to set this attribute on core pack components such as oj-c-button, as it natively supports\n disabling clickthrough. \n | \n \n | \n
| data-oj-manage-tabs | \nListView does not manipulate the tabindex of the item content. Applications should set the tabIndex of any focusable\n element based on the isTabbableMode property from the context pass to the itemTemplate. \nHowever, there will be cases where you can't control the tabindex of the content, for example, if you are using components from another team. \nIn that case, applications can specify this attribute on the element or one of its ancestors so that when the itemTemplate is processed,\n it will scan and manipulate the tabindex of any focusable elements. \n | \n \n | \n
If ItemMetadata returned by the DataProvider contains suggestion field, ListView will apply special visual to those\n items. The DataProvider must ensure the suggestion items are the first items returned by the initial fetchFirst call.
", "scope": "static", "tagWithoutBrackets": "oj-c-list-view", "tagWithBrackets": "\nThe following options are supported:\n
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.\n\n
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.\nIf 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.\nIf 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.\n
Changing the value of this attribute will not affect the value of the selected attribute.", "ojvalues": [ { "name": "none", "description": "Selection is disabled.", "displayName": "None", "type": { "names": [ "string" ] } }, { "name": "single", "description": "Only a single item can be selected at a time.", "displayName": "Single", "type": { "names": [ "string" ] } }, { "name": "singleRequired", "description": "Only a single item can be selected at a time. In addition, ListView will also ensure that an item is selected at all time.", "displayName": "Single Required", "type": { "names": [ "string" ] } }, { "name": "multiple", "description": "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.", "displayName": "Multiple", "type": { "names": [ "string" ] } }, { "name": "multipleToggle", "description": "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.", "displayName": "MultipleToggle", "type": { "names": [ "string" ] } } ], "ojvalueskeeporder": true, "defaultvalue": "'none'" }, { "id": "oj-c.ListView#contextMenuConfig", "name": "contextMenuConfig", "memberof": "oj-c.ListView", "meta": { "filename": "list-view.tsx", "path": "web/components/oj-c/list-view" }, "kind": "member", "longname": "oj-c.ListView#contextMenuConfig", "scope": "instance", "type": { "names": [ "object" ] }, "optional": true, "ojdisplayname": "Context Menu Config", "ojshortdesc": "Specifies a context menu configuration.", "description": "Specifies a context menu configuration.\nIt takes the keys `accessibleLabel` and `items`,\nwhere `accessibleLabel` is optional and items required . `items` function returns an array\nof menu item object representations that indicates what menu items are going to be part of\nmenu based on some specific context menu context.\n
| Context Menu Item Type | Def |
|---|---|
| ContextMenuSeparator | { type: 'separator'} |
| MenuItem | {\ntype?: 'item';\nlabel: string;\nkey: string;\ndisabled?: boolean;\nonAction?: () => void;\nstartIcon?: MenuIcon;\nendIcon?: MenuIcon;\nvariant?: 'standard' | 'destructive';\n}; |
| ContextMenuSubMenu | {\ntype: 'submenu';\nlabel?: string;\ndisabled?: boolean;\nstartIcon?: string;\nitems?: Array<ContextMenuItems>;\n}; |
| ContextMenuSelectSingle | {\ntype: 'selectsingle';\nkey?: string;\nitems?: Array<MenuSelectItem>;\nselection?: string;\nonSelection?: (detail: { value: string }) => void;\n}; |
| ContextMenuSelectMultiple | {\ntype: 'selectmultiple';\nkey?: string;\nitems?: Array<MenuSelectItem>;\nselection?: Array<string>;\nonSelection?: (detail: { value: Array<string> }) => void;\n}; |
| MenuIcon | {\ntype?: 'class';\n class: string;\n }\n| {\n type: 'img';\n src: string;\n }; |
| MenuSelectItem | {\nlabel: string;\ndisabled?: boolean;\nendIcon?: MenuIcon;\nvalue: string;\n} |
The following options are supported:
\n\"disabled\" or setting the \"reorderable\" property\n to null (or omitting it), disables reordering support.Note: The event detail contains the following properties: [oj-c.ListView.ItemActionDetail]{@link oj-c.ListView.ItemActionDetail}<K, D>
Triggered when user performs an action gesture on an item while ListView is in navigation mode. The action gestures include:\nNote: The event detail contains the following properties: [oj-c.ListView.FirstSelectedItemDetail]{@link oj-c.ListView.FirstSelectedItemDetail}<K, D>
Triggered when data for the first selected item is available. This can occurred when:\nsingleRequired."
},
{
"id": "oj-c.ListView#event:ojContextMenuAction",
"name": "ojContextMenuAction",
"kind": "event",
"memberof": "oj-c.ListView",
"meta": {
"filename": "list-view.tsx",
"path": "web/components/oj-c/list-view"
},
"longname": "oj-c.ListView#event:ojContextMenuAction",
"scope": "instance",
"bubbles": true,
"ojshortdesc": "Triggered when a menu item is clicked, whether by keyboard, mouse, or touch events.",
"ojdisplayname": "onOjContextMenuAction",
"description": "Note: The event detail contains the following properties: [oj-c.ListView.ListViewContextMenuActionDetail]{@link oj-c.ListView.ListViewContextMenuActionDetail}<K, D>
Triggered when a menu item is clicked, whether by keyboard, mouse, or touch events." }, { "id": "oj-c.ListView#event:ojContextMenuSelection", "name": "ojContextMenuSelection", "kind": "event", "memberof": "oj-c.ListView", "meta": { "filename": "list-view.tsx", "path": "web/components/oj-c/list-view" }, "longname": "oj-c.ListView#event:ojContextMenuSelection", "scope": "instance", "bubbles": true, "ojshortdesc": "Triggered when a select menu item is clicked, whether by keyboard, mouse, or touch events.", "ojdisplayname": "onOjContextMenuSelection", "description": "Note: The event detail contains the following properties: [oj-c.ListView.ListViewContextMenuSelectionDetail]{@link oj-c.ListView.ListViewContextMenuSelectionDetail}<K, D>
Triggered when a select menu item is clicked, whether by keyboard, mouse, or touch events." }, { "id": "oj-c.ListView#event:ojReorder", "name": "ojReorder", "kind": "event", "memberof": "oj-c.ListView", "meta": { "filename": "list-view.tsx", "path": "web/components/oj-c/list-view" }, "longname": "oj-c.ListView#event:ojReorder", "scope": "instance", "ojdisplayname": "Reorder", "description": "Note: The event detail contains the following properties: [oj-c.ListView.ReorderDetail]{@link oj-c.ListView.ReorderDetail}<K>
Triggered after items are reordered within ListView via drag and drop or keyboard." }, { "id": "oj-c.ListView#itemTemplate", "name": "itemTemplate", "memberof": "oj-c.ListView", "meta": { "filename": "list-view.tsx", "path": "web/components/oj-c/list-view" }, "kind": "member", "longname": "oj-c.ListView#itemTemplate", "scope": "instance", "ojdisplayname": "itemTemplate", "description": "Note: When the template is executed for each item, it will have access to the binding context containing the following properties: [oj-c.ListView.ListItemContext]{@link oj-c.ListView.ListItemContext}
The itemTemplate slot is used to specify the template for rendering each item in the List. The slot content must be a <template> element.\n
When the template is executed for each item, it will have access to the binding context containing the following properties:
\nThe noData slot is used to specify the content to display when the list is empty. The slot content\nmust be a <template> element. If not specified then a default no data message will be displayed.",
"ojshortdesc": "The noData slot is used to specify the content to show when there is no data. See the Help documentation for more information.",
"ojslot": true,
"properties": []
},
{
"id": "oj-c.ListView#skeletonTemplate",
"name": "skeletonTemplate",
"memberof": "oj-c.ListView",
"meta": {
"filename": "list-view.tsx",
"path": "web/components/oj-c/list-view"
},
"kind": "member",
"longname": "oj-c.ListView#skeletonTemplate",
"scope": "instance",
"ojdisplayname": "skeletonTemplate",
"description": "
Note: When the template is executed for each item, it will have access to the binding context containing the following properties: [oj-c.ListView.SkeletonRendererContext]{@link oj-c.ListView.SkeletonRendererContext}
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\nmust be a <template> element. If not specified then the default skeleton will display.\n
When the template is executed for each skeleton, it will have access to the binding context containing the following properties:
\n| Name | Type | Description |
|---|---|---|
| loadingStatus | 'initial' | 'loadMore' | Whether the skeletons are rendered for initial load of data or for load more data in CardView |
| index | number | The 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.
\n\n\n<oj-c-list-view\nid=\"cardview\"\n id=\"listview\"\n class=\"demo-list-view\"\n aria-label=\"listview with skeleton\"\n data=\"[[dataProvider]]\">\n <template slot=\"skeletonTemplate\" data-oj-as=\"context\">\n <div>\n <oj-bind-if test=\"[[context.loadingStatus === 'initial']]\">\n <oj-bind-if test=\"[[context.index % 3 === 0]]\">\n <oj-c-skeleton height=\"4x\" width=\"4x\">\n </oj-c-skeleton>\n </oj-bind-if>\n <oj-bind-if test=\"[[context.index % 3 === 1]]\">\n <oj-c-skeleton height=\"4x\" width=\"6x\">\n </oj-c-skeleton>\n </oj-bind-if>\n <oj-bind-if test=\"[[context.index % 3 === 2]]\">\n <oj-c-skeleton height=\"4x\" width=\"8x\">\n </oj-c-skeleton>\n </oj-bind-if>\n </oj-bind-if>\n <oj-bind-if test=\"[[context.loadingStatus === 'loadMore']]\">\n <oj-c-skeleton height=\"4x\" width=\"8x\">\n </oj-c-skeleton>\n </oj-bind-if>\n </div>\n </template>\n <template slot=\"itemTemplate\" data-oj-as=\"item\">\n <oj-c-list-item-layout>\n <<pan class=\"oj-typography-body-md oj-text-color-primary\">\n <oj-bind-text value=\"[[item.item.data.name]]\">\n </span>\n <oj-c-avatar slot=\"leading\" size=\"xs\" src=\"[[item.item.data.image]]\">\n <span slot=\"secondary\" class=\"oj-typography-body-sm oj-text-color-secondary\">\n <oj-bind-text value=\"[[item.item.data.title]]\">\n </span>\n </oj-c-list-item-layout>\n </template>\n</oj-c-list-view>\n",
"ojshortdesc": "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. See the Help documentation for more information.",
"ojslot": true,
"ojtemplateslotprops": "oj-c.ListView.SkeletonRendererContext"
},
{
"id": "oj-c.ListView.keyboardDoc",
"name": "keyboardDoc",
"kind": "member",
"longname": "oj-c.ListView.keyboardDoc",
"description": "| Target | \nKey | \nAction | \n
|---|---|---|
| List Item | \nF2 | \nEnters 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. | \n
| Enter | \nEnters tabbable mode if enterKeyFocusBehavior is \"focusWithin\" (default). This enables keyboard action on elements inside the item, including navigate between focusable elements inside the item. | \n|
| Esc | \nExits tabbable mode. | \n|
| Tab | \nWhen 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.\n When not in tabbable mode, navigates to next focusable element on page (outside ListView). | \n|
| Shift+Tab | \nWhen 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.\n When not in tabbable mode, navigates to previous focusable element on page (outside ListView). | \n|
| DownArrow | \nMove focus to the item below. | \n|
| UpArrow | \nMove focus to the item above. | \n|
| Shift+DownArrow | \nExtend the selection to the item below. | \n|
| Shift+UpArrow | \nExtend the selection to the item above. | \n|
| Shift+F10 | \nLaunch the context menu if there is one associated with the current item. | \n|
| Space | \nToggles to select and deselect the current item while maintaining previously selected items. | \n|
| Shift+Space | \nToggles to select and deselect the current item while maintaining previously selected items. | \n|
| Ctrl+Space | \nToggles to select and deselect the current item while maintaining previously selected items. | \n|
| Shift+Cmd/Ctrl+UpArrow | \nReorder the current item up. | \n|
| Shift+Cmd/Ctrl+DownArrow | \nReorder the current item down. | \n