Element: <oj-navigation-list>

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>

Attributes

current-item :any

Key of the current item. Current item is the list item which is having active focus. Note that if currentItem is set to an item that is currently not available (not fetched or inside a collapsed parent node), then the value is ignored.

When the current item is changed, the event.detail of the currentItemChanged event will contain the following additional properties:

Name	Type	Description
item	Element	Current Item element

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 Navigation List with the current-item attribute specified:

 <oj-navigation-list current-item='settings'> ... </oj-navigation-list>

Get the current item:

var currentItem = myNavList.currentItem;

Set the current item on the NavigationList during initialization:

myNavList.currentItem = "newItem";

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

The data source for the NavigationList accepts either a oj.TableDataSource or oj.TreeDataSource. 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 Navigation List with the data attribute specified:

 <oj-navigation-list data='[[tableDataSource]]'> ... </oj-navigation-list>

Get the data:

var dataSource = myNavList.data;

Set the data attribute using one-dimensional array:

myNavList.data = new oj.ArrayTableDataSource([1,2,3]);

Set the data attribute using oj.Collection:

myNavList.data = new oj.CollectionTableDataSource(collection);

display :string

Whether to display both the label and icons ("all") or just the icons ("icons"). In the latter case, the label is displayed in a tooltip instead, unless a tooltip was already supplied at create time. Note: display="icons" is valid only when drillMode=none and navigation list is a flat list. It is also mandatory to provide icons for each item as stated in icons section.

Supported Values:

Name	Type	Description
"all"	string	Display both the label and icons.
"icons"	string	Display only the icons.

Default Value:

• all

Names

Item	Name
Property	display
Property change event	displayChanged
Property change listener attribute (must be of type function)	on-display-changed

Examples

Initialize the Navigation List with the display attribute specified:

 <oj-navigation-list display='icons'> ... </oj-navigation-list>

Get or set the display property:

// getter
var display = myNavList.display;

// setter
myNavList.display = "icons";

drill-mode :string

Defines style of navigation used to drill down hierarchical list items.

• none
• collapsible
• sliding

Supported Values:

Name	Type	Description
"collapsible"	string	Allows user to expand and collapse group items. If there are more than two levels in hierarchy, sliding is preferered drill mode.
"none"	string	All group items are expanded by default and user not allowed to collapse them.
"sliding"	string	This is typically used for hierarchical lists. This allows user to view one level at a time.

Default Value:

• none

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 Navigation List with the drill-mode attribute specified:

 <oj-navigation-list drill-mode='collapsible'> ... </oj-navigation-list>
 

Set drillMode property:

myNavList.drillMode = "collapsible";

Get the drillMode property:

// getter
var drillMode = myNavList.drillMode;

edge :string

The position of the Navigation List. Valid Values: top and start.

NOTE: when value is top,"none" is the only supported drillMode and it also does't support hierarchical items.

Supported Values:

Name	Type	Description
"start"	string	This renders list items vertically.
"top"	string	This renders list items horizontally.

Default Value:

• start

Names

Item	Name
Property	edge
Property change event	edgeChanged
Property change listener attribute (must be of type function)	on-edge-changed

Examples

Initialize the Navigation List with the edge attribute specified:

 <oj-navigation-list edge='top'> ... </oj-navigation-list>
 

Get the edge:

var edge = myNavList.edge;

Set the edge on the Navigation List:

myNavList.edge = "top";

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 NavigationList with specific items expanded:

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

Initialize the NavigationList with all items expanded:

myNavList.expanded = new ExpandAllKeySet();

hierarchy-menu-threshold :number

Specifies the level at which user can see hiearchical menu button.This is only valid when drillMode set to sliding. Default value is 0, shows hiearchical menu always. If value is -1, then it will never be shown.

The default value for hierarchyMenuThreshold varies by theme. Each theme can set its default by setting $navigationListHierarchyMenuDisplayThresholdLevelOptionDefault as seen in the example below.

Default Value:

• 0

Names

Item	Name
Property	hierarchyMenuThreshold
Property change event	hierarchyMenuThresholdChanged
Property change listener attribute (must be of type function)	on-hierarchy-menu-threshold-changed

Examples

Initialize the Navigation List with the hierarchy-menu-threshold attribute specified:

 <oj-navigation-list hierarchy-menu-threshold='4'> ... </oj-navigation-list>
 

Get or set the hierarchyMenuThreshold property:

// getter
var hierarchyMenuThreshold = myNavList.hierarchyMenuThreshold;

// setter
myNavList.hierarchyMenuThreshold = "4";

Set the default in the theme (SCSS) :

$navigationListHierarchyMenuDisplayThresholdLevelOptionDefault: -1 !default;

item :Object

The item property contains a subset of properties 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.renderer :(((context: oj.ojNavigationList.ItemContext) => void)|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 item element directly, the function should return undefined.

If no renderer is specified, Navigation List will treat the data as a String.

Default Value:

• null

Names

Item	Name
Property	item.renderer

Examples

Initialize the Navigation List with the item.renderer attribute specified:

 <oj-navigation-list item.renderer="{{oj.KnockoutTemplateUtils.getRenderer('template', true)}}"> ... </oj-navigation-list>
 

Get or set the renderer property:

// set the renderer function
myNavList.item.renderer = rendererFn;

// get the renderer function
var rendererFn = myNavList.item.renderer;

(nullable) item.selectable :(((context: oj.ojNavigationList.ItemContext) => boolean)|boolean)

Whether the item is selectable. See itemContext in the introduction to see the object passed into the selectable function.

Default Value:

• true

Names

Item	Name
Property	item.selectable

Example

Initialize the NavigationList such that the first 3 items are not selectable:

 
 
 var skipFirstThreeElementsFn = function(itemContext) {
                                     return itemContext['index'] > 3; 
                                }

overflow :string

Specifies the overflow behaviour. NOTE: This is only applicable when edge attribute set to top

Supported Values:

Name	Type	Description
"hidden"	string	overflow is clipped, and the rest of the content will be invisible.
"popup"	string	popup menu will be shown with overflowed items. NOTE: Setting overflow to popup can trigger browser reflow, so only set it when it is actually required.

Default Value:

• hidden

Since:

• 3.0.0

Names

Item	Name
Property	overflow
Property change event	overflowChanged
Property change listener attribute (must be of type function)	on-overflow-changed

Examples

Initialize the Navigation List with the overflow attribute specified:

 <oj-navigation-list overflow='popup'> ... </oj-navigation-list>

Get or set the overflow property:

// getter
var overflow = myNavList.overflow;

// setter
myNavList.overflow = "hidden";

(nullable) root-label :string

Label for top level list items.

NOTE: This is needed only for sliding navigation list where this will be used as title for the top level list elements.

Default Value:

• Navigation List

Names

Item	Name
Property	rootLabel
Property change event	rootLabelChanged
Property change listener attribute (must be of type function)	on-root-label-changed

Examples

Initialize the Navigation List with the root-label attribute specified:

 <oj-navigation-list root-label='Global Navigation'> ... </oj-navigation-list>
 

Get or set the rootLabel property:

// getter
var rootLabel = myNavList.rootLabel;

// setter
myNavList.rootLabel = "4";

selection :any

Item Key of currently selected list item. If the value is modified by an application, navigation list UI is modified to match the new value and the event.detail of the selectionChanged event will contain the following additional properties:

Name	Type	Description
item	Element	Selected Item element

Default Value:

• null

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 Navigation List with the selection attribute specified:

 <oj-navigation-list selection='settings'> ... </oj-navigation-list>
 

Get the selection:

var selection = myNavList.selection;

Set the selection on the Navigation List:

myNavList.selection = "settings";

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'
};

(nullable) translations.default-root-label :string

Provides properties to customize the title text used by Sliding Navigation List for root node.

See the translations attribute for usage examples.

Default Value:

• "Navigation List"

Since:

• 1.1.0

Names

Item	Name
Property	translations.defaultRootLabel

(nullable) translations.hier-menu-btn-label :string

Provides properties to customize the hover message text used by Sliding Navigation List as label for Hierarchical Menu button.

See the translations attribute for usage examples.

Default Value:

• "Hierarchical Menu button"

Since:

• 1.1.0

Names

Item	Name
Property	translations.hierMenuBtnLabel

(nullable) translations.previous-icon :string

Provides properties to customize the hover message text used by Sliding Navigation List for previous button.

See the translations attribute for usage examples.

Default Value:

• "Previous"

Since:

• 1.1.0

Names

Item	Name
Property	translations.previousIcon

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.

Following are the valid subIds:

oj-navigationlist-item

Context for the oj-navigation-list component's items.

Properties:

Name	Type	Description
index	number	the zero based item index relative to its parent
key	Object | string	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-navigation-list on-oj-animate-end='[[listener]]'></oj-navigation-list>

Specify an ojAnimateEnd listener via the JavaScript property:

myNavigationList.onOjAnimateEnd = listener;

Add an ojAnimateEnd listener via the addEventListener API:

myNavigationList.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-navigation-list on-oj-animate-start='[[listener]]'></oj-navigation-list>

Specify an ojAnimateStart listener via the JavaScript property:

myNavigationList.onOjAnimateStart = listener;

Add an ojAnimateStart listener via the addEventListener API:

myNavigationList.addEventListener('ojAnimateStart', listener);

ojBeforeCollapse

Triggered before an item is collapse via the expanded property, the collapse method, or via the UI. To prevent the item being collapsed, invoke event.preventDefault().

Properties:

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

Name	Type	Description
key	any	the Key of the item to be collapse
item	Element	the item to be collapse

Examples

Specify an ojBeforeCollapse listener via the DOM attribute:

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

Specify an ojBeforeCollapse listener via the JavaScript property:

myNavigationList.onOjBeforeCollapse = listener;

Add an ojBeforeCollapse listener via the addEventListener API:

myNavigationList.addEventListener('ojBeforeCollapse', listener);

ojBeforeCurrentItem

Triggered before the current item is changed via the currentItem property or via the UI. To prevent the item being focused, invoke event.preventDefault().

Properties:

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

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

Examples

Specify an ojBeforeCurrentItem listener via the DOM attribute:

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

Specify an ojBeforeCurrentItem listener via the JavaScript property:

myNavigationList.onOjBeforeCurrentItem = listener;

Add an ojBeforeCurrentItem listener via the addEventListener API:

myNavigationList.addEventListener('ojBeforeCurrentItem', listener);

ojBeforeExpand

Triggered before an item is expand via the expanded property, the expand method, or via the UI. To prevent the item being expanded, invoke event.preventDefault().

Properties:

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

Name	Type	Description
key	any	the Key of the item to be expand
item	Element	the item to be expand

Examples

Specify an ojBeforeExpand listener via the DOM attribute:

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

Specify an ojBeforeExpand listener via the JavaScript property:

myNavigationList.onOjBeforeExpand = listener;

Add an ojBeforeExpand listener via the addEventListener API:

myNavigationList.addEventListener('ojBeforeExpand', listener);

ojBeforeSelect

Triggered before this list item is selected. To prevent the item selection, invoke event.preventDefault().

Properties:

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

Name	Type	Description
key	any	Selected list item Key.
item	Element	Selected list item.

Examples

Specify an ojBeforeSelect listener via the DOM attribute:

<oj-navigation-list on-oj-before-select='[[listener]]'></oj-navigation-list>

Specify an ojBeforeSelect listener via the JavaScript property:

myNavigationList.onOjBeforeSelect = listener;

Add an ojBeforeSelect listener via the addEventListener API:

myNavigationList.addEventListener('ojBeforeSelect', listener);

ojCollapse

Triggered after an item has been collapsed via the expanded property, 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	any	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-navigation-list on-oj-collapse='[[listener]]'></oj-navigation-list>

Specify an ojCollapse listener via the JavaScript property:

myNavigationList.onOjCollapse = listener;

Add an ojCollapse listener via the addEventListener API:

myNavigationList.addEventListener('ojCollapse', listener);

ojExpand

Triggered after an item has been expanded via the expanded property, 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	any	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-navigation-list on-oj-expand='[[listener]]'></oj-navigation-list>

Specify an ojExpand listener via the JavaScript property:

myNavigationList.onOjExpand = listener;

Add an ojExpand listener via the addEventListener API:

myNavigationList.addEventListener('ojExpand', listener);

Methods

getContextByNode(node) → {(oj.ojNavigationList.NodeContext.<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.ojNavigationList.NodeContext.<K>|null)

Example

// Returns {'subId': 'oj-some-sub-id', 'componentSpecificProperty': someValue, ...}
var context = myComponent.getContextByNode(nodeInsideElement);

getProperty(property) → {any}

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

any

Example

Get a single subproperty of a complex property:

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

refresh() → {void}

Refreshes the visual state of the Navigation List. JET components require a refresh() after the DOM is programmatically changed underneath the component.

This method does not accept any arguments.

Returns:

Type

void

Example

Invoke the refresh method:

 myNavList.refresh();

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

ItemContext

Properties:

Name	Type	Argument	Description
componentElement	Element		oj-navigation-list element
datasource	oj.DataProvider.<K, D>	<optional>	A reference to the data source object. (Not available for static content)
index	number		The index of the item, where 0 is the index of the first item.
key	any		The Key of the item.
data	any		The data object for the item.
parentElement	Element		The list item element. The renderer can use this to directly append content.

NodeContext

Properties:

Name	Type	Argument	Description
subId	string		Sub-id string to identify a particular dom node.
index	number		The index of the item, where 0 is the index of the first item.
key	K		The Key of the item.
group	boolean		whether the item is a group.
parent	Element	<optional>	the parent group item. Only available if item has a parent.