Element: <oj-list-view>

Oracle® JavaScript Extension Toolkit (JET)
15.1.0
F83698-01

Since:
  • 1.1.0
Module:
  • ojlistview

QuickNav

Slots

Attributes


Binding Attributes
Context Objects

Events

Methods

Type Definitions

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 inline HTML content or a DataProvider. It is recommended that inline HTML content should only be used for static data and the DataProvider should always be used for mutable data.

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:

  • ArrayDataProvider
  • CollectionTableDataSource
  • 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.

PagingTableDataSource - Use this when the ListView is driven by an associating ojPagingControl. See the documentation for 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.

Any manipulation of static HTML content, including manipulating content generated through Knockout (for example, updating observableArray in a foreach binding), is not supported.

A note about hierarchical data, even though ListView supports data with > 2 levels, it is not recommended because it does not render depth, for that case you should look at using ojTreeView

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>

Example of data provider content


  <oj-list-view data="[[dataProvider]]">
  </oj-list-view>

Check out the Listview Basic demo

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. It can also be used to exit actionable mode if already in actionable mode.
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. This has been deprecated. Applications should designate their own shortcut key and handle the KeyEvent directly.
Ctrl+C Marks the selected items to copy if dnd.reorder is enabled. This has been deprecated. Applications should designate their own shortcut key and handle the KeyEvent directly.
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). This has been deprecated. Applications should designate their own shortcut key and handle the KeyEvent directly.
Group Item LeftArrow (RightArrow in RTL) Collapse the current item if it is expanded and is collapsible. For non-hierarchical data, do nothing.
RightArrow (LeftArrow in RTL) 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.
metadata The metadata 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.

To facilitate drag and drop including item reordering using only keyboard, application must ensure that either to expose the functionality using context menu, and/or allow users to perform the functionality with the appropriate keystroke. You can find examples of how this can be done in the cookbook demos.

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.

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.

Migration

Read about current Core Pack limitations to decide when to migrate.
Please make note of the following:

  • Deprecated APIs are not available in Core Pack, and are not documented in this migration section.
  • Before trying to migrate to Core Pack run the JET audits and fix any issues before proceeding.
  • The refresh() method is no longer supported in Core Pack. See the Core Pack Migration Guide for more information.

Several components will replace oj-list-view in core pack. For a basic list the oj-c-list-view component is available (more information about that below). However the following features will not be added to oj-c-list-view, instead they will be supported in the future in separate, specialized core-pack components.

  • Card grid and waterfall layouts
  • Hierarchical and grouped list views
  • Expandable list items
Migration to oj-c-list-view

To migrate from oj-list-view to oj-c-list-view, you need to revise the import statement and references to oj-c-list-view in your app. Please note the changes between the two components below.

These features are not yet available in oj-c-list-view, they will be available in a forthcoming version.

  • Reordering, as well as drag and drop with other components
  • Context menus
  • Save and restore scroll position

The first step is to determine if your list view requires any of the not yet released features (see above list).

The next step is to determine compatibility with your DataSource. Here are some changes.

  • DataProvider is the only currently supported data source
  • Static content lists are no longer supported

In addition, if you have implemented your own custom-elements which are tabbable (capable of receiving keyboard focus via the Tab key) you will need to implement the useTabbableMode API contract.

Finally review the list below for specific API changes and changes to ItemContext typing.

No static lists

Support for static lists has not been brought forward, purely typographic, non-interactive lists can be created using native HTML and typography API.

An example of a static list. 
<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>
F2 Interaction Mode Change

oj-c-list-view no longer mutates the DOM to manage tab-stops, sub-components in the template need to implement the "isTabbable" API. More information to come on that soon.

Enter Key Behavior Change

Enter key no longer selects an item. Only space key should be used to select an item as recommended by the W3C accessibility guideline.

Styling Class Changes

oj-listview-item-padding-off is no longer relevant, by default padding is no longer added to List items.

Item Context Changes

The types have changed.

The context parameter contains the following keys:

Key Description
data The data object for the item.
metadata The metadata object for the item.

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 metadata.key and has been deprecated)
parentElement This will be supported by the Hierarchical list component and no longer applies to list view..
itemTemplate slot

The root node can now take text, and no longer has to be an element.

current-item attribute

This is currently a read-only property.

gridlines attribute

The gridlines property shape has changed. It now 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.

item.renderer attribute

This is not supported, everything this attribute did can be accomplished through the template.

scroll-policy-options.maxCount attribute

This is no longer supported.

ojBeforeCurrentItem event

this cancellable event is slated for deprecation. It is being replaced with onCurrentItemChanged read-only property change event.

refresh method

This is not supported. Refresh was so that the elements could reread state from the DOM, this is no longer necessary.

The following APIs are not yet supported
  • contextMenu slot
  • dnd attribute
  • first-selected-item attribute (this can be derived from the selected attribute combined with the data)
  • item.selectable attribute
  • scroll-policy attribute (currently only load more on scroll is supported)
  • scroll-position attribute
  • scroll-to-key attribute
  • selection-required attribute
  • ojReorder event
  • getContextByNode method
  • getDataForVisibleItem method
The following APIs are no longer applicable to ListView

Instead they will be considered as API for separate, specialized, core-pack components.

  • display attribute (applies to Card view only)
  • drill-mode attribute
  • expanded attribute
  • group-header-position attribute
  • ojBeforeCollapse event
  • ojCollapse event
  • ojExpand event
  • ojBeforeExpand event

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 AnimationUtils class for details

The following are actions in which applications can use to customize animation effects.

Action Description
add When a new item is added to the TableDataSource associated with ListView.
remove When an existing item is removed from the TableDataSource associated with ListView.
update When an existing item is updated in the TableDataSource associated with ListView.
expand When user expands a group item.
collapse When user collapses a group item.
pointerUp When user finish pressing an item (on touch).
cardEntrance When a card is initially rendered.
cardExit When a card is removed due to the entire data set being refreshed.

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-list-view id="listView">
  <template slot="itemTemplate" data-oj-as="item">
  </template>
</oj-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 button inside an item, then ListView will not select or trigger itemAction event to be fired when user clicks on the button. Expand/collapse will also be ignored if the button is inside the group header.

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

 
<oj-list-view id="listView">
  <template slot="itemTemplate">
    <oj-button data-oj-clickthrough="disabled"></oj-button
  </template>
</oj-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. Suggestion items are only supported when display is 'item'. Applications should not allow users to reorder suggestion items.


Usage

Signature:

interface ListViewElement<K, D>

Generic Parameters
ParameterDescription
KType of key of the dataprovider
DType of data from the dataprovider
Typescript Import Format
//To typecheck the element APIs, import as below.
import { ListViewElement } from "ojs/ojlistview";

//For the transpiled javascript to load the element's module, import as below
import "ojs/ojlistview";

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.


Styling Classes

.oj-clickthrough-disabled
Use on any element inside an item where you do not want ListView to process the click event.
Deprecated:
Since Description
10.0.0 Specify data-oj-clickthrough attribute with value disabled instead.
Example
<oj-list-view class="oj-clickthrough-disabled">
  <!-- Content -->
</oj-list-view>
.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.
Example
<oj-list-view class="oj-focus-highlight">
  <!-- Content -->
</oj-list-view>
.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.
Deprecated:
Since Description
10.0.0 Use oj-listview-full-width instead.
Example
<oj-list-view class="oj-full-width">
  <!-- Content -->
</oj-list-view>
.oj-group-header-lg
Use to style group headers as large size group headers according to the current theme.
Example
<oj-list-view class="oj-group-header-lg">
  <!-- Content -->
</oj-list-view>
.oj-group-header-md
Use to style group headers as medium size group headers according to the current theme.
Example
<oj-list-view class="oj-group-header-md">
  <!-- Content -->
</oj-list-view>
.oj-group-header-sm
Use to style group headers as small size group headers according to the current theme.
Example
<oj-list-view class="oj-group-header-sm">
  <!-- Content -->
</oj-list-view>
.oj-listview-card-layout
Shows items as cards and lay them out in a grid.
Example
<oj-list-view class="oj-listview-card-layout">
  <!-- Content -->
</oj-list-view>
.oj-listview-drag-handle
Use to show a drag handle in the item to facilitate item reordering or drag and drop.
Example
<oj-list-view>
  <template slot="itemTemplate" data-oj-as="item">
    ...
    <div class="oj-flex-bar-end oj-sm-align-items-center">
     <div role="button" tabindex="0" class="oj-flex-item oj-listview-drag-handle">
     </div>
    </div>
  </template>
</oj-list-view>
.oj-listview-drill-icon
Use to show a drill-to-detail icon in the item.
Example
<oj-list-view class="oj-listview-card-layout">
  <template slot="itemTemplate" data-oj-as="item">
    ...
    <div class="oj-flex-bar-end oj-sm-align-items-center">
     <div role="presentation" class="oj-flex-item oj-fwk-icon oj-listview-drill-icon">
     </div>
    </div>
  </template>
</oj-list-view>
.oj-listview-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.
Example
<oj-list-view class="oj-listview-full-width">
  <!-- Content -->
</oj-list-view>
.oj-listview-item-layout
Use when the page author overrides the default styling on the item root element and wants to apply the item style on some other element.
Example
<oj-list-view class="">
  <template slot="itemTemplate" data-oj-as="item">
    <div class="oj-listview-item-layout">
    ...
    </div>
  </template>
</oj-list-view>
.oj-listview-item-padding-off
Use when the page author wants to remove the default padding around the item. This is mostly used in the case where the component used inside the itemTemplate already supply its own padding (ex: oj-list-item-layout), and therefore the default padding provided by ListView should be remove.
Example
<oj-list-view class="oj-listview-item-padding-off">
  <!-- Content -->
</oj-list-view>

CSS Variables

See JET CSS Variables for additional details.
List view item padding CSS
Name Type Description
--oj-list-view-item-padding-horizontal <length> List view horizontal item padding
List view group header CSS
CSS variables that specify list view group header styles
Name Type Description
--oj-list-view-group-header-bg-color <color> List view group header background color
--oj-list-view-group-header-bg-color-sticky <color> List view group header sticky background color
--oj-list-view-group-header-font-weight <font_weight> List view group header font weight
--oj-list-view-group-header-font-size <length> List view group header font size
--oj-list-view-group-header-line-height <number> List view group header horizontal line height

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

The itemTemplate slot is used to specify the template for rendering each item in the list. The slot content 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 oj.ojListView.ItemTemplateContext or 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 D The data for 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.
index number The zero-based index of the current item during initial rendering. Note the index is not updated in response to item additions and removals.
item Item.<K, D> The current item being rendered
key K The key of the current item being rendered
leaf boolean True if the current item is a leaf node (available when hierarchical data is provided).
parentkey K The key of the parent item (available when hierarchical data is provided). The parent key is null for root nodes.

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.

Attributes

as :string

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, see Events and Listeners for additional information.) 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, see Events and Listeners for additional information.) on-current-item-changed

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

The data source for ListView. Must be of type oj.TableDataSource, oj.TreeDataSource, 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, see Events and Listeners for additional information.) on-data-changed

display :"list"|"card"

Whether to display items as list items or as cards.
Supported Values:
Value Description
card Display items as cards.
list Display items as list items.
Default Value:
  • "list"
Names
Item Name
Property display
Property change event displayChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-display-changed

dnd :Object

Enable drag and drop functionality. Note the ojlistviewdnd module must be imported in order to use the dnd 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, see Events and Listeners for additional information.) 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

(nullable) 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, see Events and Listeners for additional information.) 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, see Events and Listeners for additional information.) on-expanded-changed

(readonly) first-selected-item :CommonTypes.ItemContext<K,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.
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, see Events and Listeners for additional information.) on-first-selected-item-changed

gridlines :Object

The gridlines option contains a subset of options for gridlines.
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

gridlines.item :"visible"|"visibleExceptLast"|"hidden"

Specifies whether the horizontal grid lines should be visible. Note this attribute has no effect when ListView is in card display mode.

The default value varies by theme.

Supported Values:
Value Description
hidden The horizontal gridlines are hidden.
visible The horizontal gridlines are visible.
visibleExceptLast The horizontal gridlines are visible, except for the last item. Note this will not have an effect for themes that renders a bottom border for the component.
Default Value:
  • "visible"
Names
Item Name
Property gridlines.item

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, see Events and Listeners for additional information.) 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, see Events and Listeners for additional information.) 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.
Deprecated:
Since Description
13.0.0 Not accessible by screen reader.
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, see Events and Listeners for additional information.) 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, see Events and Listeners for additional information.) 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 | keyof HTMLElementTagNameMap | keyof SVGElementTagNameMap | string

The element or a CSS selector string to an 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
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.
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.
parent K <optional>
 The key of the parent where the index is relative to. If not specified, then the root is assumed
x number <optional>
 The horizontal position in pixels.
y number <optional>
 The vertical position in pixels.
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, see Events and Listeners for additional information.) on-scroll-position-changed

scroll-to-key :"auto"|"capability"|"always"|"never"

Specifies the behavior when ListView needs to scroll to a position based on an item key. This includes the case where 1) a value of scrollPosition attribute is specified with a key property, 2) ListView scrolls to the selection anchor after a refresh has occurred.
Supported Values:
Value Description
always ListView will scroll to a position based on an item key as long as the key is valid.
auto The behavior is determined by the component. By default the behavior is the same as "capability" except when legacy TableDataSource/TreeDataSource is used, in which case the behavior is the same as "always".
capability ListView will only scroll to a position based on an item key if either the item has already been fetched or if the associated DataProvider supports 'immediate' iterationSpeed for 'fetchFirst' capability.
never ListView will not change the scroll position if the request is based on an item key.
Default Value:
  • "auto"
Names
Item Name
Property scrollToKey
Property change event scrollToKeyChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-scroll-to-key-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, see Events and Listeners for additional information.) 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, see Events and Listeners for additional information.) on-selection-changed

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

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 single or multiple is specified, selection gestures will be enabled, and the ListView's selection styling will be applied to all items specified by the selection and selected attributes. 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 selection and selected attributes.

Changing the value of this attribute will not affect the value of the selection or selected attributes.

Supported Values:
Value Description
multiple Multiple items can be selected at the same time.
none Selection is disabled.
single Only a single 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, see Events and Listeners for additional information.) on-selection-mode-changed

selection-required :boolean

Specifies whether selection is required on the ListView. This attribute will only take effect when selection is enabled and at least one selectable item is present. When true, the ListView will ensure that at least one valid item is selected at all times. If no items are specified by the selection or selected attributes, the first selectable item in the ListView will be added to the selection state during initial render. Additionally, selection gestures that would otherwise leave the ListView with no selected items will be disabled.

When true, the ListView will also attempt to validate all items specified by the selection and selected attributes. If any items specified are not immediately available, the ListView's underlying DataProvider will be queried. This will only occur if the data provider supports getCapability, and returns a fetchByKeys capability implementation of lookup. Any items that fail this validation process will be removed from the selection and selected attributes. This guarantees that the ListView's firstSelectedItem attribute is populated at all times.

See selectionMode for information on how to enable or disable selection on the ListView.

See item.selectable for information on how to enable or disable selection for individual items.

Default Value:
  • false
Names
Item Name
Property selectionRequired
Property change event selectionRequiredChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) 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, see Events and Listeners for additional information.) on-translations-changed

translations.accessible-expand-collapse-instruction-text :string

Provides instruction text for group header expand or collapse

Since:
  • 14.0.0
Names
Item Name
Property translations.accessibleExpandCollapseInstructionText

translations.accessible-group-collapse :string

Provides notification for group header collapse

Since:
  • 14.0.0
Names
Item Name
Property translations.accessibleGroupCollapse

translations.accessible-group-expand :string

Provides notification for group header expand

Since:
  • 14.0.0
Names
Item Name
Property translations.accessibleGroupExpand

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.accessible-suggestion :string

Provides properties to customize the screen reader text for suggestions returned by OARS service.

Since:
  • 15.0.0
Names
Item Name
Property translations.accessibleSuggestion

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-fetch-completed :string

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

See the translations attribute for usage examples.

Since:
  • 13.0.0
Names
Item Name
Property translations.msgFetchCompleted

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
group boolean whether the item is a group.
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.

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. See Events and Listeners for additional information.

Name Type Description
action string the action that triggered 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. See Events and Listeners for additional information.

Name Type Description
action string the action that triggers 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. See Events and Listeners for additional information.

Name Type Description
item Element the item to be collapsed
key K the key of 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. See Events and Listeners for additional information.

Name Type Description
item Element the new current item
key K the key of the new current item
previousItem Element the previous item
previousKey K the key of the previous 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. See Events and Listeners for additional information.

Name Type Description
item Element the item to be expanded
key K the key of 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. See Events and Listeners for additional information.

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

ojCopy

Triggered when the copy action is performed on an item via context menu or keyboard shortcut.
Deprecated:
Since Description
11.0.0 Use event from context menu or KeyEvent instead.
Properties:

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

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.
Deprecated:
Since Description
11.0.0 Use event from context menu or KeyEvent instead.
Properties:

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

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. See Events and Listeners for additional information.

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

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 an item or its content 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 Description
context CommonTypes.ItemContext<K,D> the context information about the item where the action gesture is performed on.
originalEvent Event the DOM event that triggers the action.

ojPaste

Triggered when the paste action is performed on an item via context menu or keyboard shortcut.
Deprecated:
Since Description
11.0.0 Use event from context menu or KeyEvent instead.
Properties:

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

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. See Events and Listeners for additional information.

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.
Deprecated:
Since Description
13.0.0 The scrollToItem method is deprecated. Use scrollPosition instead.
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
group boolean <optional>
 whether the item is a group item
index number the zero based index of the item, relative to its parent
key K the key of the item
parent Element <optional>
 the parent group DOM element
subId string the sub id that represents the element

ItemContext<K,D>

Properties:
Name Type Argument Description
data D the data object of the item
datasource DataProvider.<K, D> the data source/data provider
depth number <optional>
 the depth of the item
index number the zero based index of the item, relative to its parent during initial rendering. Note the index is not updated in response to item additions and removals.
key K the key of the item
leaf boolean <optional>
 whether the item is a leaf
metadata oj.ItemMetadata.<K> the metadata object of the item
parentElement Element the item DOM element
parentKey K <optional>
 the key of the parent item

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

ItemTemplateContext<K = any,D = any>

Properties:
Name Type Description
componentElement Element The <oj-list-view> custom element
data D The data for 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.
index number The zero-based index of the current item during initial rendering. Note the index is not updated in response to item additions and removals.
item Item.<K, D> The current item being rendered
key K The key of the current item being rendered
leaf boolean True if the current item is a leaf node (available when hierarchical data is provided).
parentkey K The key of the parent item (available when hierarchical data is provided). The parent key is null for root nodes.