Element: <oj-list-view>

Oracle® JavaScript Extension Toolkit (JET)
7.1.0

F18183-01

Signature:

class ojListView<K, D>

QuickNav

Attributes


Binding Attributes
Context Objects

JET Custom Elements

JET components are implemented as custom HTML elements. In addition to the component attributes documented in this page, JET components also support standard HTML global attributes like id and aria-label.

The JET data binding syntax can be used to define both component and global attributes through the use of dynamically evaluated expressions. All attributes (component and global) support attribute-level binding by prefixing the attribute name with ":" (e.g. :id="[...]"). When using attribute-level binding, all expression values are treated as strings. Additionally, component attributes support property-level binding by using the attribute name directly with no ":" prefix. When using property-level binding, the expressions should evaluate to the types documented by the corresponding attributes. Property-level binding is strongly recommended over attribute-level binding for component attributes.

A detailed description of working with custom HTML elements can be found in: JET Custom Element Usage.



PREVIEW: This is a preview API. Preview APIs are production quality, but can be changed on a major version without a deprecation path.

Version:
  • 7.1.0
Since:
  • 1.1.0
Module:
  • ojlistview

Module usage

See JET Module Loading for an overview of module usage within JET.

Typescript Import Format
//To typecheck the element APIs, import as below.
import {ojListView} from "ojs/ojlistview";

//For the transpiled javascript to load the element's module, import as below
import "ojs/ojlistview";
Generic Parameters
ParameterDescription
KType of key of the dataprovider
DType of data from the dataprovider

JET In Typescript

A detailed description of working with JET elements and classes in your typescript project can be found at: JET Typescript Usage.


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.

Data

The JET ListView gets its data in three different ways. The first way is from a DataProvider/TableDataSource. There are several types of DataProvider/TableDataSource that are available out of the box:

  • oj.ArrayDataProvider
  • oj.CollectionTableDataSource
  • oj.PagingTableDataSource

Note that TableDataSource has been deprecated, please find the equivalent DataProvider implementation.

oj.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 oj.ArrayDataProvider for more details on the available options.

oj.CollectionTableDataSource - Use this when oj.Collection is the model for the underlying data. Note that the ListView will automatically react to model event from the underlying oj.Collection. See the documentation for oj.CollectionTableDataSource for more details on the available options.

oj.PagingTableDataSource - Use this when the ListView is driven by an associating ojPagingControl. See the documentation for oj.PagingTableDataSource for more details on the available options.

The second way is from a TreeDataProvider/TreeDataSource. This is typically used to display data that are logically categorized in groups. There are several types of TreeDataProvider/TreeDataSource that are available out of the box:

  • oj.ArrayTreeDataProvider
  • oj.CollectionTreeDataSource

oj.ArrayTreeDataProvider - 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 of oj.ArrayTreeDataProvider for more details on the available options.

oj.CollectionTreeDataSource - Use this when oj.Collection is the model for each group of data. See the documentation for oj.CollectionTableDataSource for more details on the available options.

Finally, ListView also supports static HTML content as data. The structure of the content can be either flat or hierarhical.

Example of flat static content

<oj-list-view id="listView">
  <ul>
    <li><a id="item1" href="#">Item 1</a></li>
    <li><a id="item2" href="#">Item 2</a></li>
    <li><a id="item3" href="#">Item 3</a></li>
  </ul>
</oj-list-view>

Example of hierarchical static content

<oj-list-view id="listView">
  <ul>
    <li><a id="group1" href="#">Group 1</a>
      <ul>
        <li><a id="item1-1" href="#">Item 1-1</a></li>
        <li><a id="item1-2" href="#">Item 1-2</a></li>
      </ul>
    </li>
    <li><a id="group2" href="#">Group 2</a>
      <ul>
        <li><a id="item2-1" href="#">Item 2-1</a></li>
        <li><a id="item2-2" href="#">Item 2-2</a></li>
      </ul>
    </li>
  </ul>
</oj-list-view>

Touch End User Information

Target Gesture Action
List Item Tap Focus on the item. If selectionMode is enabled, selects the item as well.
Press & Hold Display context menu
Group Item Tap Expand or collapse the group item if drillMode is set to collapsible.
Press & Hold Display context menu

Keyboard End User Information

Target Key Action
List Item F2 Enters Actionable mode. This enables keyboard action on elements inside the item, including navigate between focusable elements inside the item.
Esc Exits Actionable mode.
Tab When in Actionable 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 Actionable Mode, navigates to next focusable element on page (outside ListView).
Shift+Tab When in Actionable 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 Actionable Mode, navigates to previous focusable element on page (outside ListView).
DownArrow Move focus to the item below.
UpArrow Move focus to the item above.
LeftArrow When display in card layout, move focus to the item on the left.
RightArrow When display in card layout, move focus to the item on the right.
Shift+DownArrow Extend the selection to the item below.
Shift+UpArrow Extend the selection to the item above.
Shift+LeftArrow When display in card layout, extend the selection to the item on the left.
Shift+RightArrow When display in card layout, extend the selection to the item on the right.
Shift+F10 Launch the context menu if there is one associated with the current item.
Enter Selects the current item. No op if the item is already selected.
Space Toggles to select and deselect the current item. If previous items have been selected, deselects them and selects the current item.
Shift+Space Selects contiguous items from the last selected item to the current item.
Ctrl+Space Toggles to select and deselect the current item while maintaining previous selected items.
Ctrl+X Marks the selected items to move if dnd.reorder is enabled.
Ctrl+C Marks the selected items to copy if dnd.reorder is enabled.
Ctrl+V Paste the items that are marked to directly before the current item (or as the last item if the current item is a folder).
Group Item LeftArrow Collapse the current item if it is expanded and is collapsible. For non-hierarchical data, do nothing.
RightArrow Expand the current item if it has children and is expandable. For non-hierarchical data, do nothing.

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 paramter contains the following keys:

Key Description
componentElement A reference to the root element of ListView.
datasource A reference to the data source object. (Not available for static content)
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.
data The data object for the item.
parentElement The list item element. The renderer can use this to directly append content.

If the data is hierarchical, the following additional contextual information are available:

Key Description
depth The depth of the item. The depth of the first level children under the invisible root is 1.
parentKey The key of the parent item. The parent key is null for root node.
leaf Whether the item is a leaf or a group item.

Accessibility

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

Application must ensure that the context menu is available and setup with the appropriate clipboard menu items so that keyboard-only users are able to reorder items just by using the keyboard.

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

Styling

The following CSS classes can be applied by the page author as needed.

Class Description
oj-clickthrough-disabled Use on any element inside an item where you do not want ListView to process the click event.
oj-focus-highlight Under normal circumstances this class is applied automatically. It is documented here for the rare cases that an app developer needs per-instance control.

The oj-focus-highlight class applies focus styling that may not be desirable when the focus results from pointer interaction (touch or mouse), but which is needed for accessibility when the focus occurs by a non-pointer mechanism, for example keyboard or initial page load.

The application-level behavior for this component is controlled in the theme by the $focusHighlightPolicy SASS variable; however, note that this same variable controls the focus highlight policy of many components and patterns. The values for the variable are:

  • nonPointer: oj-focus-highlight is applied only when focus is not the result of pointer interaction. Most themes default to this value.
  • all: oj-focus-highlight is applied regardless of the focus mechanism.
  • none: oj-focus-highlight is never applied. This behavior is not accessible, and is intended for use when the application wishes to use its own event listener to precisely control when the class is applied (see below). The application must ensure the accessibility of the result.

To change the behavior on a per-instance basis, the application can set the SASS variable as desired and then use event listeners to toggle this class as needed.

oj-full-width Use when ListView occupies the entire width of the page. Removes left and right borders in card-layout mode and adjust positioning of cards to improve visual experience.
oj-listview-card-layout Shows items as cards and lay them out in a grid.

Performance

Data Set Size

As a rule of thumb, it's recommended that applications limit the amount of data to display. Displaying large number of items in ListView makes it hard for user to find what they are looking for, but affects the load time and scrolling performance as well. If displaying large number of items is neccessary, use a paging control with ListView to limit the number of items to display at a time. Setting scrollPolicy to 'loadMoreOnScroll' will also reduce the number of items to display initially.

Item Content

ListView allows developers to specify arbitrary content inside its item. In order to minimize any negative effect on performance, you should avoid putting a large number of heavy-weight components inside because as you add more complexity to the structure, the effect will be multiplied because there can be many items in the ListView.

Expand All

While ListView provides a convenient way to initially expand all group items in the ListView, it might have an impact on the initial rendering performance since expanding each group item might cause a fetch from the server depending on the TreeDataSource. Other factors that could impact performance includes the depth of the tree, and the number of children in each level.

Animation

Applications can customize animations triggered by actions in ListView by either listening for animateStart/animateEnd events or overriding action specific style classes on the animated item. See the documentation of oj.AnimationUtils class for details.

The following are actions and their corresponding sass variables in which applications can use to customize animation effects.

Action Sass Variable Description
add $listViewAddAnimation When a new item is added to the oj.TableDataSource associated with ListView.
remove $listViewRemoveAnimation When an existing item is removed from the oj.TableDataSource associated with ListView.
update $listViewUpdateAnimation When an existing item is updated in the oj.TableDataSource associated with ListView.
expand $listViewExpandAnimation When user expands a group item.
collapse $listViewCollapseAnimation When user collapses a group item.
pointerUp $listViewPointerUpAnimation When user finish pressing an item (on touch).

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.

contextMenu

The contextMenu slot is set on the oj-menu within this element. This is used to designate the JET Menu that this component should launch as a context menu on right-click, Shift-F10, Press & Hold, or component-specific gesture. If specified, the browser's native context menu will be replaced by the JET Menu specified in this slot.

The application can register a listener for the Menu's ojBeforeOpen event. The listener can cancel the launch via event.preventDefault(), or it can customize the menu contents by editing the menu DOM directly, and then calling refresh() on the Menu.

To help determine whether it's appropriate to cancel the launch or customize the menu, the ojBeforeOpen listener can use component API's to determine which table cell, chart item, etc., is the target of the context menu. See the JSDoc of the individual components for details.

Keep in mind that any such logic must work whether the context menu was launched via right-click, Shift-F10, Press & Hold, or component-specific touch gesture.

itemTemplate

PREVIEW: This is a preview API. Preview APIs are production quality, but can be changed on a major version without a deprecation path.

The itemTemplate slot is used to specify the template for rendering each item in the list. The slot must be a <template> element. The content of the template could either include the <li> element, in which case that will be used as the root of the item. Or it can be just the content which excludes the <li> 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. (See the table below for a list of properties available on $current)
  • alias - if as attribute was specified, the value will be used to provide an application-named alias for $current.
Properties of $current:
Name Type Description
componentElement Element The <oj-list-view> custom element
data Object The data for the current item being rendered
index number The zero-based index of the curent item
key any The key of the current item being rendered
depth number The depth of the current item (available when hierarchical data is provided) being rendered. The depth of the first level children under the invisible root is 1.
leaf boolean True if the current item is a leaf node (available when hierarchical data is provided).
parentkey any The key of the parent item (available when hierarchical data is provided). The parent key is null for root nodes.

Attributes

as :string

PREVIEW: This is a preview API. Preview APIs are production quality, but can be changed on a major version without a deprecation path.

An alias for the current item when referenced inside the item template. This can be especially useful if oj-bind-for-each element is used inside the item template since it has its own scope of data access.
Deprecated:
Since Description
6.2.0 Set the alias directly on the template element using the data-oj-as attribute instead.
Default Value:
  • ''
Names
Item Name
Property as
Property change event asChanged
Property change listener attribute (must be of type function) on-as-changed

current-item :K

The item that currently have keyboard focus. Note that if current item is set to an item that is not available in the view (either not fetched in high-water mark scrolling case or hidden inside a collapsed parent node), then the value is not applied.
Default Value:
  • null
Supports writeback:
  • true
Names
Item Name
Property currentItem
Property change event currentItemChanged
Property change listener attribute (must be of type function) on-current-item-changed

data :(oj.TableDataSource|oj.TreeDataSource|oj.DataProvider) data :oj.DataProvider.<K, D>

The data source for ListView. Must be of type oj.TableDataSource, oj.TreeDataSource, oj.DataProvider See the data source section in the introduction for out of the box data source types. If the data attribute is not specified, the child elements are used as content. If there's no content specified, then an empty list is rendered.
Default Value:
  • null
Names
Item Name
Property data
Property change event dataChanged
Property change listener attribute (must be of type function) on-data-changed

dnd :Object

Enable drag and drop functionality.

JET provides support for HTML5 Drag and Drop events. Please refer to third party documentation on HTML5 Drag and Drop to learn how to use it.
Names
Item Name
Property dnd
Property change event dndChanged
Property change listener attribute (must be of type function) on-dnd-changed

(nullable) dnd.drag :Object

Enables and customizes the drag functionality.
Names
Item Name
Property dnd.drag

dnd.drag.items :Object

If this object is specified, listview will initiate drag operation when the user drags on either a drag handle, which is an element with oj-listview-drag-handle class, or selected items if no drag handle is set on the item.
Names
Item Name
Property dnd.drag.items

(nullable) dnd.drag.items.data-types :string|Array.<string>

The MIME types to use for the dragged data in the dataTransfer object. This can be a string if there is only one type, or an array of strings if multiple types are needed.

For example, if selected items of employee data are being dragged, dataTypes could be "application/employees+json". Drop targets can examine the data types and decide whether to accept the data. A text input may only accept "text" data type, while a chart for displaying employee data may be configured to accept the "application/employees+json" type.

For each type in the array, dataTransfer.setData will be called with the specified type and the JSON version of the selected item data as the value. The selected item data is an array of objects, with each object representing a model object from the underlying data source. For example, if the underlying data is an oj.Collection, then this would be a oj.Model object. Note that when static HTML is used, then the value would be the html string of the selected item.

This property is required unless the application calls setData itself in a dragStart callback function.
Default Value:
  • null
Names
Item Name
Property dnd.drag.items.dataTypes

(nullable) dnd.drag.items.drag :function(Event)

An optional callback function that receives the "drag" event as its argument.
Default Value:
  • null
Names
Item Name
Property dnd.drag.items.drag

(nullable) dnd.drag.items.drag-end :function(Event)

An optional callback function that receives the "dragend" event as its argument.
Default Value:
  • null
Names
Item Name
Property dnd.drag.items.dragEnd

(nullable) dnd.drag.items.drag-start :function(Event, {items: Array.<Element>}):void

A callback function that receives the "dragstart" event and context information as its arguments. The ontext information has the following properties:
  • items: An array of items being dragged


This function can set its own data and drag image as needed. If dataTypes is specified, event.dataTransfer is already populated with the default data when this function is invoked. If dataTypes is not specified, this function must call event.dataTransfer.setData to set the data or else the drag operation will be cancelled. In either case, the drag image is set to an image of the dragged rows on the listview.
Default Value:
  • null
Names
Item Name
Property dnd.drag.items.dragStart

(nullable) dnd.drop :Object

Names
Item Name
Property dnd.drop

dnd.drop.items :Object

An object that specifies callback functions to handle dropping items.
Names
Item Name
Property dnd.drop.items

(nullable) dnd.drop.items.data-types :string|Array.<string>

A data type or an array of data types this component can accept.

This property is required unless dragEnter, dragOver, and drop callback functions are specified to handle the corresponding events.
Default Value:
  • null
Names
Item Name
Property dnd.drop.items.dataTypes

(nullable) dnd.drop.items.drag-enter :function(Event, {item: Element}):void

An optional callback function that receives the "dragenter" event and context information as its arguments. The context information has the following properties:
  • item: the item being entered


This function should call event.preventDefault to indicate the dragged data can be accepted.

Default Value:
  • null
Names
Item Name
Property dnd.drop.items.dragEnter

(nullable) dnd.drop.items.drag-leave :function(Event, {item: Element}):void

An optional callback function that receives the "dragleave" event and context information as its arguments. The context information has the following properties:
  • item: the item that was last entered


Default Value:
  • null
Names
Item Name
Property dnd.drop.items.dragLeave

(nullable) dnd.drop.items.drag-over :function(Event, {item: Element}):void

An optional callback function that receives the "dragover" event and context information as its arguments. The context information has the following properties:
  • item: the item being dragged over


Similar to dragEnter, this function should call event.preventDefault to indicate the dragged data can be accepted.
Default Value:
  • null
Names
Item Name
Property dnd.drop.items.dragOver

(nullable) dnd.drop.items.drop :((param0: Event, param1: ojListView.ItemsDropContext)=> void)

A callback function that receives the "drop" event and context information as its arguments. The context information has the following properties:
  • item: the item being dropped on
  • position: the drop position relative to the item being dropped on
  • reorder: true if the drop was a reorder in the same listview, false otherwise


This function should call event.preventDefault to indicate the dragged data is accepted.

If the application needs to look at the data for the item being dropped on, it can use the getDataForVisibleItem method.
Default Value:
  • null
Names
Item Name
Property dnd.drop.items.drop

dnd.reorder :Object

The reorder option contains a subset of options for reordering items.
Names
Item Name
Property dnd.reorder

dnd.reorder.items :"enabled"|"disabled"

Enable or disable reordering the items within the same listview using drag and drop.

Specify 'enabled' to enable reordering. Setting the value 'disabled' or setting the "dnd" property to null (or omitting it), disables reordering support.
Supported Values:
Value Description
"disabled" Item reordering is disabled.
"enabled" Item reordering is enabled.
Default Value:
  • "disabled"
Names
Item Name
Property dnd.reorder.items

drill-mode :"collapsible"|"none"

Changes the expand and collapse operations on ListView. If "none" is specified, then the current expanded state is fixed and user cannot expand or collapse an item.
Supported Values:
Value Description
"collapsible" Group item can be expanded or collapsed by user.
"none" The expand state of a group item cannot be changed by user.
Default Value:
  • "collapsible"
Names
Item Name
Property drillMode
Property change event drillModeChanged
Property change listener attribute (must be of type function) on-drill-mode-changed

expanded :oj.KeySet<K>

Specifies the key set containing the keys of the items that should be expanded. Use the ExpandedKeySet class to specify items to expand. Use the ExpandAllKeySet class to expand all items.
Default Value:
  • new ExpandedKeySet();
Supports writeback:
  • true
Names
Item Name
Property expanded
Property change event expandedChanged
Property change listener attribute (must be of type function) on-expanded-changed

(readonly) first-selected-item :{key: K, data: D}

Gets the key and data of the first selected item. The first selected item is defined as the first key returned by the selection property. The value of this property contains:
  • key - the key of the first selected item.
  • data - the data of the first selected item. If the selected item is not locally available, this will be null. If the data property is not set and that static HTML element is used as data, then this will be the item element.
If no items are selected then this property will return an object with both key and data properties set to null.
Properties:
Name Type Description
key any The key of the first selected item
data any The data of the first selected item
Default Value:
  • {'key': null, 'data': null}
Supports writeback:
  • true
Names
Item Name
Property firstSelectedItem
Property change event firstSelectedItemChanged
Property change listener attribute (must be of type function) on-first-selected-item-changed

group-header-position :"static"|"sticky"

Specifies how the group header should be positioned. If "sticky" is specified, then the group header is fixed at the top of the ListView as the user scrolls.
Supported Values:
Value Description
"static" The group header position updates as user scrolls.
"sticky" The group header is fixed at the top when user scrolls.
Default Value:
  • "sticky"
Names
Item Name
Property groupHeaderPosition
Property change event groupHeaderPositionChanged
Property change listener attribute (must be of type function) on-group-header-position-changed

item :Object

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) on-item-changed

(nullable) item.focusable :((param0: ojListView.ItemContext<K,D>) => boolean)|boolean

Whether the item is focusable. An item that is not focusable cannot be clicked on or navigated to. See itemContext in the introduction to see the object passed into the focusable function.
Default Value:
  • true
Names
Item Name
Property item.focusable

(nullable) item.renderer :((param0: ojListView.ItemContext<K,D>) => {insert: Element|string}|undefined)|null

The renderer function that renders the content of the item. See itemContext in the introduction to see the object passed into the renderer function. The function should return one of the following:
  • An Object with the following property:
    • insert: HTMLElement | string - A string or a DOM element of the content inside the item.
  • undefined: If the developer chooses to manipulate the list element directly, the function should return undefined.
If no renderer is specified, ListView will treat the data as a string.
Default Value:
  • null
Names
Item Name
Property item.renderer

(nullable) item.selectable :((param0: ojListView.ItemContext<K,D>) => boolean)|boolean

Whether the item is selectable. Note that if selectionMode is set to "none" this option is ignored. In addition, if focusable is set to false, then the selectable option is automatically overridden and set to false also. See itemContext in the introduction to see the object passed into the selectable function.
Default Value:
  • true
Names
Item Name
Property item.selectable

scroll-policy :"auto"|"loadAll"|"loadMoreOnScroll"

Specifies the mechanism used to scroll the data inside the list view. Possible values are: "auto", "loadMoreOnScroll", and "loadAll". When "loadMoreOnScroll" is specified, additional data is fetched when the user scrolls to the bottom of the ListView. Note that currently this option is only available when non-hierarchical DataProvider is used. When "loadAll" is specified, ListView will fetch all the data when it is initially rendered. If you are using Paging Control with the ListView, please note that "loadMoreOnScroll" scroll-policy is not compatible with Paging Control "loadMore" mode.
Supported Values:
Value Description
"auto" The behavior is determined by the component. By default the behavior is the same as "loadMoreOnScroll" except when legacy TableDataSource is used, in which case the behavior is the same as "loadAll".
"loadAll" Fetch and render all data.
"loadMoreOnScroll" Additional data is fetched when the user scrolls towards the bottom of the ListView.
Not compatible when used with Paging Control "loadMore" mode.
Default Value:
  • "auto"
Names
Item Name
Property scrollPolicy
Property change event scrollPolicyChanged
Property change listener attribute (must be of type function) on-scroll-policy-changed

scroll-policy-options :Object.<string, number>|null

scrollPolicy options.

The following options are supported:

  • fetchSize: The number of items fetched each time when scroll to the end.
  • maxCount: Maximum rows which will be displayed before fetching more rows will be stopped.
  • scroller: The element 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 widget element of listview is used.
When scrollPolicy is loadMoreOnScroll, 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. Note that currently this option is only available when non-hierarchical DataProvider or TableDataSource is used.

Names
Item Name
Property scrollPolicyOptions
Property change event scrollPolicyOptionsChanged
Property change listener attribute (must be of type function) on-scroll-policy-options-changed

(nullable) scroll-policy-options.fetch-size :number

The number of items to fetch in each block
Default Value:
  • 25
Names
Item Name
Property scrollPolicyOptions.fetchSize

(nullable) scroll-policy-options.max-count :number

The maximum total number of items to fetch
Default Value:
  • 500
Names
Item Name
Property scrollPolicyOptions.maxCount

(nullable) scroll-policy-options.scroller :Element

The element which listview uses to determine the scroll position as well as the maximum scroll position. For example in a lot of mobile use cases where ListView occupies the entire screen, developers should set the scroller option to document.documentElement.
Default Value:
  • null
Names
Item Name
Property scrollPolicyOptions.scroller

scroll-position :Object

The current scroll position of ListView. The scroll position is updated when either the vertical or horizontal scroll position (or its scroller, as specified in scrollPolicyOptions.scroller) has changed. The value contains the x and y scroll position, the index and key information of the item closest to the top of the viewport, as well as horizontal and vertical offset from the position of the item to the actual scroll position.

The default value contains just the scroll position. Once data is fetched the 'index' and 'key' sub-properties will be added. If there is no data then the 'index' and 'key' sub-properties will not be available.

When setting the scrollPosition property, applications can change any combination of the sub-properties. If multiple sub-properties are set at once they will be used in key, index, pixel order where the latter serves as hints. If offsetX or offsetY are specified, they will be used to adjust the scroll position from the position where the key or index of the item is located.

If a sparse object is set the other sub-properties will be populated and updated once ListView has scrolled to that position.

Also, if scrollPolicy is set to 'loadMoreOnScroll' and the scrollPosition is set to a value outside of the currently rendered region, then ListView will attempt to fetch until the specified scrollPosition is satisfied or the end is reached (either at max count or there's no more items to fetch), in which case the scroll position will remain at the end. The only exception to this is when the key specified does not exists and a DataProvider is specified for data, then the scroll position will not change (unless other sub-properties like index or x/y are specified as well).

Lastly, when a re-rendered is triggered by a refresh event from the DataProvider, or if the value for data attribute has changed, then the scrollPosition will be adjusted such that the selection anchor (typically the last item selected by the user) prior to refresh will appear at the top of the viewport after refresh. If selection is disabled or if there is no selected items, then the scrollPosition will remain at the top.

Properties:
Name Type Argument Description
x number <optional>
the horizontal position in pixels
y number <optional>
the vertical position in pixels
index number <optional>
the zero-based index of the item. If scrollPolicy is set to 'loadMoreOnScroll' and the index is greater than maxCount set in scrollPolicyOptions, then it will scroll and fetch until the end of the list is reached and there's no more items to fetch.
parent K <optional>
the key of the parent where the index is relative to. If not specified, then the root is assumed
key K <optional>
the key of the item. If DataProvider is used for data and the key does not exists in the DataProvider, then the value is ignored. If DataProvider is not used then ListView will fetch and scroll until the item is found or the end of the list is reached and there's no more items to fetch.
offsetX number <optional>
the horizontal offset in pixels relative to the item identified by key/index.
offsetY number <optional>
the vertical offset in pixels relative to the item identified by key/index.
Default Value:
  • {"x": 0, "y": 0}
Supports writeback:
  • true
Names
Item Name
Property scrollPosition
Property change event scrollPositionChanged
Property change listener attribute (must be of type function) on-scroll-position-changed

selected :oj.KeySet<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.
Default Value:
  • new KeySetImpl();
Supports writeback:
  • true
Names
Item Name
Property selected
Property change event selectedChanged
Property change listener attribute (must be of type function) on-selected-changed

selection :Array<K>

The current selections in the ListView. An empty array indicates nothing is selected.
Deprecated:
Since Description
7.0.0 Use selected attribute instead.
Default Value:
  • []
Supports writeback:
  • true
Names
Item Name
Property selection
Property change event selectionChanged
Property change listener attribute (must be of type function) on-selection-changed

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

Specifies whether selection can be made and the cardinality of selection in the ListView. Selection is initially disabled, but setting the value to null will disable selection.
Supported Values:
Value Description
"multiple" Multiple items can be selected at the same time.
"none" Selection is disabled.
"single" Only one item can be selected at a time.
Default Value:
  • "none"
Names
Item Name
Property selectionMode
Property change event selectionModeChanged
Property change listener attribute (must be of type function) on-selection-mode-changed

selection-required :boolean

PREVIEW: This is a preview API. Preview APIs are production quality, but can be changed on a major version without a deprecation path.

Specifies whether ListView should enforce that there will always be an item selected when selection is enabled and there are one or more selectable items. Specifically, when this is enabled, then the first selectable item in ListView will be selected. Furthermore, users will not be able to toggle selection such that it will result in no selected items. See selectionMode on how to enable/disable selection. See item.selectable on how to enable/disable selection for individual item.
Default Value:
  • false
Names
Item Name
Property selectionRequired
Property change event selectionRequiredChanged
Property change listener attribute (must be of type function) on-selection-required-changed

translations :object|null

A collection of translated resources from the translation bundle, or null if this component has no resources. Resources may be accessed and overridden individually or collectively, as seen in the examples.

If the component does not contain any translatable resource, the default value of this attribute will be null. If not, an object containing all resources relevant to the component.

If this component has translations, their documentation immediately follows this doc entry.

Names
Item Name
Property translations
Property change event translationsChanged
Property change listener attribute (must be of type function) on-translations-changed

translations.accessible-navigate-skip-items :string

Provides properties to customize the screen reader text when focus skips a number of items as a result of up/down arrow navigation in card layout mode.

Since:
  • 4.0.0
Names
Item Name
Property translations.accessibleNavigateSkipItems

translations.accessible-reorder-after-item :string

Provides properties to customize the screen reader text when the tentative drop target is after a certain item.

Since:
  • 2.1.0
Names
Item Name
Property translations.accessibleReorderAfterItem

translations.accessible-reorder-before-item :string

Provides properties to customize the screen reader text when the tentative drop target is before a certain item.

Since:
  • 2.1.0
Names
Item Name
Property translations.accessibleReorderBeforeItem

translations.accessible-reorder-inside-item :string

Provides properties to customize the screen reader text when the tentative drop target is inside a certain item.

Since:
  • 2.1.0
Names
Item Name
Property translations.accessibleReorderInsideItem

translations.accessible-reorder-touch-instruction-text :string

Provides properties to customize the screen reader touch instructional text for reordering items.

Since:
  • 2.1.0
Names
Item Name
Property translations.accessibleReorderTouchInstructionText

translations.indexer-characters :string

Provides properties to customize the characters to display in the Indexer.

Since:
  • 1.2.0
Names
Item Name
Property translations.indexerCharacters

translations.label-copy :string

Provides properties to customize the context menu copy label.

See the translations attribute for usage examples.

Since:
  • 2.1.0
Names
Item Name
Property translations.labelCopy

translations.label-cut :string

Provides properties to customize the context menu cut label.

See the translations attribute for usage examples.

Since:
  • 2.1.0
Names
Item Name
Property translations.labelCut

translations.label-paste :string

Provides properties to customize the context menu paste label.

See the translations attribute for usage examples.

Since:
  • 2.1.0
Names
Item Name
Property translations.labelPaste

translations.label-paste-after :string

Provides properties to customize the context menu paste after label.

See the translations attribute for usage examples.

Since:
  • 2.1.0
Names
Item Name
Property translations.labelPasteAfter

translations.label-paste-before :string

Provides properties to customize the context menu paste before label.

See the translations attribute for usage examples.

Since:
  • 2.1.0
Names
Item Name
Property translations.labelPasteBefore

translations.msg-fetching-data :string

Provides properties to customize the message text used by ListView when waiting for data.

See the translations attribute for usage examples.

Since:
  • 1.1.0
Names
Item Name
Property translations.msgFetchingData

translations.msg-items-appended :string

Provides properties to customize the message text used by ListView when items are appended.

See the translations attribute for usage examples.

Since:
  • 7.0.0
Names
Item Name
Property translations.msgItemsAppended

translations.msg-no-data :string

Provides properties to customize the message text used by ListView when there are no items.

See the translations attribute for usage examples.

Since:
  • 1.1.0
Names
Item Name
Property translations.msgNoData

Binding Attributes

Binding attributes are similar to component properties, but are exposed only via the ojComponent binding.

item.template :string|null

The knockout template used to render the content of the item. This attribute is only exposed via the ojComponent binding, and is not a component option.
Default Value:
  • null
Names
Item Name
Property item.template

Context Objects

Each context object contains, at minimum, a subId property, whose value is a string that identifies a particular DOM node in this element. It can have additional properties to further specify the desired node. See getContextByNode for more details.

Properties:
Name Type Description
subId string Sub-id string to identify a particular dom node.

Following are the valid subIds:

oj-listview-item

Context for items within ListView.

Properties:
Name Type Description
index number the zero based item index relative to its parent
key Object the key of the item
parent Element the parent group item. Only available if item has a parent.
group boolean whether the item is a group.

Events

ojAnimateEnd

Triggered when the default animation of a particular action has ended. Note this event will not be triggered if application cancelled the default animation on animateStart.
Properties:

All of the event payloads listed below can be found under event.detail.

Name Type Description
action string the action that started the animation. See animation section for a list of actions.
element Element the target of animation.

ojAnimateStart

Triggered when the default animation of a particular action is about to start. The default animation can be cancelled by calling event.preventDefault.
Properties:

All of the event payloads listed below can be found under event.detail.

Name Type Description
action string the action that starts the animation. See animation section for a list of actions.
element Element the target of animation.
endCallback function():void if the event listener calls event.preventDefault to cancel the default animation, it must call the endCallback function when it finishes its own animation handling and when any custom animation ends.

ojBeforeCollapse

Triggered before an item is collapsed via the expanded option, the collapse method, or via the UI.
Properties:

All of the event payloads listed below can be found under event.detail.

Name Type Description
key K the key of the item to be collapsed
item Element the item to be collapsed

ojBeforeCurrentItem

Triggered before the current item is changed via the current option or via the UI.
Properties:

All of the event payloads listed below can be found under event.detail.

Name Type Description
previousKey K the key of the previous item
previousItem Element the previous item
key K the key of the new current item
item Element the new current item

ojBeforeExpand

Triggered before an item is expanded via the expanded option, the expand method, or via the UI.
Properties:

All of the event payloads listed below can be found under event.detail.

Name Type Description
key K the key of the item to be expanded
item Element the item to be expanded

ojCollapse

Triggered after an item has been collapsed via the expanded option or via the UI. Note if the collapse is triggered by updating the expanded option, applications should avoid vetoing the beforeCollapse event. In addition, due to internal optimizations, when multiple items are collapsed due to update of expanded option, there is no guarantee that this event will be fired for all the collapsible items.
Properties:

All of the event payloads listed below can be found under event.detail.

Name Type Description
key K The key of the item that was just collapsed.
item Element The list item that was just collapsed.

ojCopy

Triggered when the copy action is performed on an item via context menu or keyboard shortcut.
Properties:

All of the event payloads listed below can be found under event.detail.

Name Type Description
items Array.<Element> an array of items in which the copy action is performed on

ojCut

Triggered when the cut action is performed on an item via context menu or keyboard shortcut.
Properties:

All of the event payloads listed below can be found under event.detail.

Name Type Description
items Array.<Element> an array of items in which the cut action is performed on

ojExpand

Triggered after an item has been expanded via the expanded option or via the UI. Note if the expand is triggered by updating the expanded option, applications should avoid vetoing the beforeExpand event. In addition, due to internal optimizations, when multiple items are collapsed due to update of expanded option, there is no guarantee that this event will be fired for all the expandable items.
Properties:

All of the event payloads listed below can be found under event.detail.

Name Type Description
key K The key of the item that was just expanded.
item Element The list item that was just expanded.

ojPaste

Triggered when the paste action is performed on an item via context menu or keyboard shortcut.
Properties:

All of the event payloads listed below can be found under event.detail.

Name Type Description
item Element the element in which the paste action is performed on

ojReorder

Triggered after items are reorder within listview via drag and drop or cut and paste.
Properties:

All of the event payloads listed below can be found under event.detail.

Name Type Description
items Array.<Element> an array of items that are moved
position string the drop position relative to the reference item. Possible values are "before", "after", "inside"
reference Element the item where the moved items are drop on

Methods

getContextByNode(node) → {(oj.ojListView.ContextByNode.<K>|null)}

Returns an object with context for the given child DOM node. This will always contain the subid for the node, defined as the 'subId' property on the context object. Additional component specific information may also be included. For more details on returned objects, see context objects.
Parameters:
Name Type Argument Description
node Element <not nullable>
The child DOM node
Returns:
The context for the DOM node, or null when none is found.
Type
(oj.ojListView.ContextByNode.<K>|null)

getDataForVisibleItem(context) → {D}

Return the raw data for an item in ListView. The item must have been already fetched.
Parameters:
Name Type Description
context Object The context of the item to retrieve raw data.
Properties
Name Type Argument Description
key K <optional>
The key of the item. If both index and key are specified, then key takes precedence.
index number <optional>
The index of the item relative to its parent.
parent Element <optional>
The parent node, not required if parent is the root.
Returns:
data of the item. If the item is not found or not yet fetched, returns null. Also, if static HTML is used as data (data attribute is not specified), then the element for the item is returned.
Type
D

getIndexerModel() → {Object}

Gets the IndexerModel which can be used with the ojIndexer. The IndexerModel provided by ListView by defaults returns a list of locale dependent characters. See translations for the key used to return all characters. When a user selects a character in the ojIndexer ListView will scroll to the group header (or the closest one) with the character as its prefix.
Deprecated:
Since Description
3.0.0 Implements your own IndexerModel or use the IndexerModelTreeDataSource class instead.
Returns:
ListView's IndexerModel to be used with the ojIndexer
Type
Object

getProperty(property) → {any}

Retrieves the value of a property or a subproperty. The return type will be the same as the type of the property as specified in this API document. If the method is invoked with an incorrect property/subproperty name, it returns undefined.
Parameters:
Name Type Description
property string The property name to get. Supports dot notation for subproperty access.
Since:
  • 4.0.0
Returns:
Type
any
Example

Get a single subproperty of a complex property:

let subpropValue = myComponent.getProperty('complexProperty.subProperty1.subProperty2');

refresh() → {void}

Redraw the entire list view after having made some external modifications.

This method does not accept any arguments.

Returns:
Type
void

scrollToItem(item) → {void}

Scrolls the list until the specified item is visible. If the item is not yet loaded (if scrollPolicy is set to 'loadMoreOnScroll'), then no action is taken.
Parameters:
Name Type Description
item Object An object with a 'key' property that identifies the item to scroll to.
Properties:
Name Type Description
item.key K the key of the item to scroll to.
Returns:
Type
void

setProperties(properties) → {void}

Performs a batch set of properties. The type of value for each property being set must match the type of the property as specified in this API document.
Parameters:
Name Type Description
properties Object An object containing the property and value pairs to set.
Since:
  • 4.0.0
Returns:
Type
void
Example

Set a batch of properties:

myComponent.setProperties({"prop1": "value1", "prop2.subprop": "value2", "prop3": "value3"});

setProperty(property, value) → {void}

Sets a property or a subproperty (of a complex property) and notifies the component of the change, triggering a [property]Changed event. The value should be of the same type as the type of the attribute mentioned in this API document.
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.
Since:
  • 4.0.0
Returns:
Type
void
Example

Set a single subproperty of a complex property:

myComponent.setProperty('complexProperty.subProperty1.subProperty2', "someValue");

Type Definitions

ContextByNode<K>

Properties:
Name Type Argument Description
subId string the sub id that represents the element
key K the key of the item
index number the zero based index of the item, relative to its parent
parent Element <optional>
the parent group DOM element
group boolean <optional>
whether the item is a group item

ItemContext<K,D>

Properties:
Name Type Argument Description
datasource oj.DataProvider.<K, D> the data source/data provider
index number the zero based index of the item, relative to its parent
key K the key of the item
data D the data object of the item
parentElement Element the item DOM element
depth number <optional>
the depth of the item
parentKey K <optional>
the key of the parent item
leaf boolean <optional>
whether the item is a leaf

ItemsDropContext

Properties:
Name Type Description
item Element the item being dropped on
position 'before' | 'after' | 'inside' the drop position relative to the item being dropped on
reorder boolean true if the drop was a reorder in the same listview, false otherwise