Usage
Signature:
interface ListViewElement<K, D>
Generic Parameters
Parameter Description K Type of key of the dataprovider D Type 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
-
List view item padding CSS
-
List view group header CSS
Name | Type | Description |
---|---|---|
--oj-list-view-item-padding-horizontal |
<length> | List view horizontal item padding |
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.
- Default Value:
"list"
Supported Values:
Value Description card
Display items as cards. list
Display items as list items. 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 callevent.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 callevent.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 onposition
: the drop position relative to the item being dropped onreorder
: true if the drop was a reorder in the same listview, false otherwise
This function should callevent.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 tonull
(or omitting it), disables reordering support.- Default Value:
"disabled"
Supported Values:
Value Description disabled
Item reordering is disabled. enabled
Item reordering is enabled. 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.
- Default Value:
"collapsible"
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. 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.
- 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.
- Default Value:
"visible"
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. 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.
- Default Value:
"sticky"
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. 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.
- Default Value:
null
Names
Item Name Property item.renderer
- An Object with the following property:
-
(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.
- Default Value:
"auto"
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.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.
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.
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.- Default Value:
{"x": 0, "y": 0}
- Supports writeback:
true
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. 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.
- Default Value:
"auto"
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 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. 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
ormultiple
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. Ifnone
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.
- Default Value:
"none"
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. 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 oflookup
. 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. -
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, thecollapse
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. -
ojBeforeExpand
-
Triggered before an item is expanded via the
expanded
option, theexpand
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.
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.