Element: <oj-list-view>

Oracle® JavaScript Extension Toolkit (JET)
5.0.0

E90577-01

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:
  • 5.0.0
Since:
  • 1.1.0
Module:
  • ojlistview

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

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 TreeDataSource. This is typically used to display data that are logically categorized in groups. There are several types of TreeDataSource that are available out of the box:

  • oj.JsonTreeDataSource
  • oj.CollectionTreeDataSource

oj.JsonTreeDataSource - Use this when the underlying data is a JSON object. See the documentation for oj.JsonTreeDataSource 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.
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 elements can have up to two types of child content:

  • Any child element with a slot attribute will be moved into that named slot, e.g. <span slot='startIcon'>...</span>. All supported named slots are documented below. Child elements with unsupported named slots will be removed from the DOM.
  • Any child element lacking a slot attribute will be moved to the default slot, also known as a regular child.

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 and demos 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.

Example

Initialize the component with a context menu:

<oj-some-element>
    <-- use the contextMenu slot to designate this as the context menu for this component -->
    <oj-menu slot="contextMenu" style="display:none" aria-label="Some element's context menu">
...
    </oj-menu>
</oj-some-element>

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.

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 being rendered
    • componentElement - the <oj-list-view> custom element
    • data - the data for the current item being rendered
    • index - the zero-based index of the current item being rendered
    • key - the key of the current item being rendered
    • depth (available when hierarchical data is provided) - the depth of the current item being rendered. The depth of the first level children under the invisible root is 1
    • leaf (available when hierarchical data is provided) - whether the current item is a leaf node or not
    • parentKey (available when hierarchical data is provided) - the key of the parent item. The parent key is null for root nodes
  • alias - if as attribute was specified, the value will be used to provide an application-named alias for $current.

The content of the template should not include the <li> element, only what's inside it.

When both template and item.renderer are specified, the item.renderer takes precedence.

Example

Initialize the ListView with an inline item template specified:

<oj-list-view>
  <template slot='itemTemplate'>
    <span><oj-bind-text value='[[$current.data.name]]'></span>
  <template>
</oj-list-view>

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.
Default Value:
  • ''
Names
Item Name
Property as
Property change event asChanged
Property change listener attribute (must be of type function) on-as-changed
Example

Initialize the ListView with the as attribute specified:

<oj-list-view as='item'>
  <template slot='itemTemplate'>
    <p><oj-bind-text value='[[item.data.name]]'></oj-bind-text></p>
  </template>
</oj-list-view>

current-item :*

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 highwater 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
Examples

Initialize the ListView with the current-item attribute specified:

<oj-list-view current-item='{{myCurrentItem}}'></oj-list-view>

Get or set the currentItem property after initialization:

// getter
var currentItemValue = myListView.currentItem;

// setter
myListView.currentItem = "item2";

data :oj.TableDataSource|oj.TreeDataSource|oj.DataProvider

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
Examples

Initialize the ListView with the data attribute specified:

<oj-list-view data='{{myDataSource}}'></oj-list-view>

Get or set the data property after initialization:

// getter
var dataValue = myListView.data;

// setter
myListView.data = myDataSource;

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.
Default Value:
  • {"drag": null, "drop": null, "reorder": {"items": "disabled"}}
Names
Item Name
Property dnd
Property change event dndChanged
Property change listener attribute (must be of type function) on-dnd-changed

dnd.drag :Object

Enables and customize the drag functionalities.
Default Value:
  • null
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.
Default Value:
  • null
Names
Item Name
Property dnd.drag.items

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

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

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

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

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

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

A callback function that receives the "dragstart" event and context information as 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

dnd.drop :Object

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

dnd.drop.items :Object

An object that specifies callback functions to handle dropping items.
Default Value:
  • null
Names
Item Name
Property dnd.drop.items

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

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

An optional callback function that receives the "dragenter" event and context information as 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

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

An optional callback function that receives the "dragleave" event and context information as 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

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

An optional callback function that receives the "dragover" event and context information as 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: oj.ojListView.ItemsDropContext)=> void)

A callback function that receives the "drop" event and context information as 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 :string

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:
Name Type Description
"disabled" string Item reordering is disabled.
"enabled" string Item reordering is enabled.
Default Value:
  • "disabled"
Names
Item Name
Property dnd.reorder.items
Examples

Initialize the ListView with the reorder attribute specified:

<oj-list-view dnd.reorder.items='enabled'></oj-list-view>

Get or set the reorder property after initialization:

// getter
var reorderValue = myListView.dnd.reorder.items;

// setter
myListView.dnd.reorder.items = 'enabled';

drill-mode :string

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:
Name Type Description
"collapsible" string Group item can be expanded or collapsed by user.
"none" string 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
Examples

Initialize the ListView with the drill-mode attribute specified:

<oj-list-view drill-mode='none'></oj-list-view>

Get or set the drillMode property after initialization:

// getter
var drillModeValue = myListView.drillMode;

// setter
myListView.drillMode = 'none';

expanded :KeySet

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
Examples

Initialize the ListView with specific items expanded:

myListView.expanded = new ExpandedKeySet(['item1', 'item2']);

Initialize the ListView with all items expanded:

myListView.expanded = new ExpandAllKeySet();

(readonly) first-selected-item :Object

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 * The key of the first selected item
data * 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
Example

Get the data of the first selected item:

// getter
var firstSelectedItemValue = myListView.firstSelectedItem;

group-header-position

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:
Name Type Description
"static" string The group header position updates as user scrolls.
"sticky" string 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
Examples

Initialize the ListView with the group-header-position attribute specified:

<oj-list-view group-header-position='static'></oj-list-view>

Get or set the groupHeaderPosition property after initialization:

// getter
var groupHeaderPositionValue = myListView.groupHeaderPosition;

// setter
myListView.groupHeaderPosition = 'static';

item

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: oj.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
Examples

Initialize the ListView with the focusable attribute specified:

<oj-list-view item.focusable='{{myFocusableFunc}}'></oj-list-view>

Get or set the focusable property after initialization:

// getter
var focusable = myListView.item.focusable;

// setter
myListView.item.focusable = myFocusableFunc;

(nullable) item.renderer :((param0: oj.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
Examples

Initialize the ListView with the renderer attribute specified:

<oj-list-view item.renderer='{{myRendererFunc}}'></oj-list-view>

Get or set the renderer property after initialization:

// getter
var renderer = myListView.item.renderer;

// setter
myListView.item.renderer = myRendererFunc;

(nullable) item.selectable :((param0: oj.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
Examples

Initialize the ListView with the selectable attribute specified:

<oj-list-view item.selectable='{{mySelectableFunc}}'></oj-list-view>

Get or set the selectable property after initialization:

// getter
var selectable = myListView.item.selectable;

// setter
myListView.item.selectable = mySelectableFunc;

scroll-policy :string|null

Specifies the mechanism used to scroll the data inside the list view. Possible values are: auto and loadMoreOnScroll. 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 TableDataSource is used.
Supported Values:
Name Type Description
"auto" string The behavior is determined by the component.
"loadMoreOnScroll" string Additional data is fetched when the user scrolls to the bottom of the ListView.
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
Examples

Initialize the ListView with the scroll-policy attribute specified:

<oj-list-view scroll-policy='loadMoreOnScroll'></oj-list-view>

Get or set the scrollPolicy property after initialization:

// getter
var scrollPolicyValue = myListView.scrollPolicy;

// setter
myListView.scrollPolicy = 'loadMoreOnScroll';

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
Examples

Initialize the ListView with the scroll-policy-options attribute specified:

<oj-list-view scroll-policy-options.fetch-size='30'></oj-list-view>

Get or set the scroll-policy-options attribute after initialization:

// getter
var fetchSizeValue = myListView.scrollPolicyOptions.fetchSize;

// setter
myListView.scrollPolicyOptions.fetchSize = 30;

Initialize the ListView with the scroll-policy-options attribute specified:

<!-- Using dot notation -->
<oj-list-view scroll-policy-options.fetch-size='30' scroll-policy-options.max-count='1000'></oj-list-view>

Get or set the scrollPolicyOptions property after initialization:

// Get one
var fetchSizeValue = myListView.scrollPolicyOptions.fetchSize;

// Get all
var scrollPolicyOptionsValues = myListView.scrollPolicyOptions;

// Set one, leaving the others intact
myListView.setProperty('scrollPolicyOptions.fetchSize', 30);

// Set all.
myListView.scrollPolicyOptions = {fetchSize: 30, maxCount: 1000};

scroll-policy-options.fetch-size :number

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

scroll-policy-options.max-count :number

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

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).

Properties:
Name Type Argument Description
x number <optional>
the horizontal position in pixel
y number <optional>
the vertical position in pixel
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 * <optional>
the key of the parent where the index is relative to. If not specified, then the root is assumed
key * <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 pixel relative to the item identified by key/index.
offsetY number <optional>
the vertical offset in pixel relative to the item identified by key/index.
Default Value:
  • {"x": 0, "y": 0}
Names
Item Name
Property scrollPosition
Property change event scrollPositionChanged
Property change listener attribute (must be of type function) on-scroll-position-changed
Examples

Initialize the ListView with the scroll-position attribute specified:

<!-- Using dot notation -->
<oj-list-view scroll-position.index='10'></oj-list-view>

<!-- Using JSON notation -->
<oj-list-view scroll-position='{"index": 10}'></oj-list-view>

Get or set the scrollPosition property after initialization:

// Get one
var scrollPositionValue = myListView.scrollPosition.index;

// Set one, leaving the others intact
myListView.setProperty('scrollPosition.index', 10);

// Get all
var scrollPositionValues = myListView.scrollPosition;

// Set all.  Those not listed will be lost until the scroll completes and the remaining fields are populated.
myListView.scrollPosition = {x: 0, y: 150};

selection :Array.<*>

The current selections in the ListView. An empty array indicates nothing is selected.
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
Examples

Initialize the ListView with the selection attribute specified:

<oj-list-view selection='{{mySelection}}'></oj-list-view>

Get or set the selection property after initialization:

// getter
var selectionValue = myListView.selection;

// setter
myListView.selection = ['item1', 'item2', 'item3'];

selection-mode :string

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:
Name Type Description
"multiple" string Multiple items can be selected at the same time.
"none" string Selection is disabled.
"single" string 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
Examples

Initialize the ListView with the selection-mode attribute specified:

<oj-list-view selection-mode='multiple'></oj-list-view>

Get or set the selectionMode property after initialization:

// getter
var selectionModeValue = myListView.selectionMode;

// setter
myListView.selectionMode = 'multiple';

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
Examples

Initialize the ListView with the selection-required attribute specified:

<oj-list-view selection-required='true'></oj-list-view>

Get or set the selectionRequired property after initialization:

// getter
var selectionRequiredValue = myListView.selectionRequired;

// setter
myListView.selectionRequired = true;

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
Examples

Initialize the component, overriding some translated resources and leaving the others intact:

<!-- Using dot notation -->
<oj-some-element translations.some-key='some value' translations.some-other-key='some other value'></oj-some-element>

<!-- Using JSON notation -->
<oj-some-element translations='{"someKey":"some value", "someOtherKey":"some other value"}'></oj-some-element>

Get or set the translations property after initialization:

// Get one
var value = myComponent.translations.someKey;

// Set one, leaving the others intact. Always use the setProperty API for 
// subproperties rather than setting a subproperty directly.
myComponent.setProperty('translations.someKey', 'some value');

// Get all
var values = myComponent.translations;

// Set all.  Must list every resource key, as those not listed are lost.
myComponent.translations = {
    someKey: 'some value',
    someOtherKey: 'some other value'
};

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-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
Example

Specify the template when initializing ListView:

// set the template
<ul id="listview" data-bind="ojComponent: {component: 'ojListView', data: dataSource, item: {template: 'my_template'}}"></ul>

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.
Examples

Specify an ojAnimateEnd listener via the DOM attribute:

<oj-list-view on-oj-animate-end='[[listener]]'></oj-list-view>

Specify an ojAnimateEnd listener via the JavaScript property:

myListView.onOjAnimateEnd = listener;

Add an ojAnimateEnd listener via the addEventListener API:

myListView.addEventListener('ojAnimateEnd', listener);

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.
Examples

Specify an ojAnimateStart listener via the DOM attribute:

<oj-list-view on-oj-animate-start='[[listener]]'></oj-list-view>

Specify an ojAnimateStart listener via the JavaScript property:

myListView.onOjAnimateStart = listener;

Add an ojAnimateStart listener via the addEventListener API:

myListView.addEventListener('ojAnimateStart', listener);

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 * the key of the item to be collapsed
item Element the item to be collapsed
Examples

Specify an ojBeforeCollapse listener via the DOM attribute:

<oj-list-view on-oj-before-collapse='[[listener]]'></oj-list-view>

Specify an ojBeforeCollapse listener via the JavaScript property:

myListView.onOjBeforeCollapse = listener;

Add an ojBeforeCollapse listener via the addEventListener API:

myListView.addEventListener('ojBeforeCollapse', listener);

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 * the key of the previous item
previousItem Element the previous item
key * the key of the new current item
item Element the new current item
Examples

Specify an ojBeforeCurrentItem listener via the DOM attribute:

<oj-list-view on-oj-before-current-item='[[listener]]'></oj-list-view>

Specify an ojBeforeCurrentItem listener via the JavaScript property:

myListView.onOjBeforeCurrentItem = listener;

Add an ojBeforeCurrentItem listener via the addEventListener API:

myListView.addEventListener('ojBeforeCurrentItem', listener);

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 * the key of the item to be expanded
item Element the item to be expanded
Examples

Specify an ojBeforeExpand listener via the DOM attribute:

<oj-list-view on-oj-before-expand='[[listener]]'></oj-list-view>

Specify an ojBeforeExpand listener via the JavaScript property:

myListView.onOjBeforeExpand = listener;

Add an ojBeforeExpand listener via the addEventListener API:

myListView.addEventListener('ojBeforeExpand', listener);

ojCollapse

Triggered after an item has been 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 * The key of the item that was just collapsed.
item Element The list item that was just collapsed.
Examples

Specify an ojCollapse listener via the DOM attribute:

<oj-list-view on-oj-collapse='[[listener]]'></oj-list-view>

Specify an ojCollapse listener via the JavaScript property:

myListView.onOjCollapse = listener;

Add an ojCollapse listener via the addEventListener API:

myListView.addEventListener('ojCollapse', listener);

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
Examples

Specify an ojCopy listener via the DOM attribute:

<oj-list-view on-oj-copy='[[listener]]'></oj-list-view>

Specify an ojCopy listener via the JavaScript property:

myListView.onOjCopy = listener;

Add an ojCopy listener via the addEventListener API:

myListView.addEventListener('ojCopy', listener);

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
Examples

Specify an ojCut listener via the DOM attribute:

<oj-list-view on-oj-cut='[[listener]]'></oj-list-view>

Specify an ojCut listener via the JavaScript property:

myListView.onOjCut = listener;

Add an ojCut listener via the addEventListener API:

myListView.addEventListener('ojCut', listener);

ojExpand

Triggered after an item has been 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 * The key of the item that was just expanded.
item Element The list item that was just expanded.
Examples

Specify an ojExpand listener via the DOM attribute:

<oj-list-view on-oj-expand='[[listener]]'></oj-list-view>

Specify an ojExpand listener via the JavaScript property:

myListView.onOjExpand = listener;

Add an ojExpand listener via the addEventListener API:

myListView.addEventListener('ojExpand', listener);

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
Examples

Specify an ojPaste listener via the DOM attribute:

<oj-list-view on-oj-paste='[[listener]]'></oj-list-view>

Specify an ojPaste listener via the JavaScript property:

myListView.onOjPaste = listener;

Add an ojPaste listener via the addEventListener API:

myListView.addEventListener('ojPaste', listener);

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
Examples

Specify an ojReorder listener via the DOM attribute:

<oj-list-view on-oj-reorder='[[listener]]'></oj-list-view>

Specify an ojReorder listener via the JavaScript property:

myListView.onOjReorder = listener;

Add an ojReorder listener via the addEventListener API:

myListView.addEventListener('ojReorder', listener);

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)
Example
// Returns {'subId': 'oj-some-sub-id', 'componentSpecificProperty': someValue, ...}
var context = myComponent.getContextByNode(nodeInsideElement);

getDataForVisibleItem(context) → {*}

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 * <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
*
Example

Invoke the getDataForVisibleItem method:

var data = myListView.getDataForVisibleItem( {'index': 2} );

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) → {*}

Retrieves a value for a property or a single subproperty for complex properties.
Parameters:
Name Type Description
property string The property name to get. Supports dot notation for subproperty access.
Since:
  • 4.0.0
Returns:
Type
*
Example

Get a single subproperty of a complex property:

var 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
Example

Invoke the refresh method:

myListView.refresh();

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.
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 single subproperty for complex properties and notifies the component of the change, triggering a [property]Changed event.
Parameters:
Name Type Description
property string The property name to set. Supports dot notation for subproperty access.
value * 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

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

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