Element: <oj-navigation-list>

Oracle® JavaScript Extension Toolkit (JET)
8.0.0
F18189-01

Signature:

class ojNavigationList<K, D>

QuickNav

Slots

Attributes


Context Objects

Events

Methods

Type Definitions

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.



Version:
  • 8.0.0
Since:
  • 1.1.0
Module:
  • ojnavigationlist

Module usage

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

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

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

JET In Typescript

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


Description: JET Navigation List enhances a HTML list element into a themable, WAI-ARIA compliant, mobile friendly component with advance interactive features.

Data

The JET NavigationList 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.ArrayDataProvider - Use this when the underlying data is an array object or an observableArray. In the observableArray case, Navigation List 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 Navigation List will automatically react to model event from the underlying oj.Collection. See the documentation for oj.CollectionTableDataSource for more details on the available options.

NOTE: oj.PagingTableDataSource is not supported by Navigation List.

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

  • oj.ArrayTreeDataProvider
  • oj.CollectionTreeDataSource

oj.ArrayTreeDataProvider - Use this when the underlying data is an array object or an observableArray. In the observableArray case, NavigationList will automatically react when items are added or removed from the array. See the documentation of oj.ArrayTreeDataProvider for more details on the available options.

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

Finally, Navigation List also supports static HTML content as data. The structure of the content can be either flat or hierarhical. Note: data attribute should not be set when static HTML content is used.

Example of flat static content


<oj-navigation-list>
 <ul>
  <li><a href="#">Item 1</a></li>
  <li><a href="#">Item 2</a></li>
  <li><a href="#">Item 3</a></li>
 </ul>
</oj-navigation-list>

Example of hierarchical static content


<oj-navigation-list>
 <ul >
  <li><a href="#">Item 1</a></li>
  <li><a href="#">Item 2</a></li>
  <li><a href="#">Item 3</a>
    <ul>
      <li><a href="#">Item 3-1</a></li>
      <li><a href="#">Item 3-2</a></li>
      <li><a href="#">Item 3-3</a></li>
      <li><a href="#">Item 3-4</a></li>
      <li><a href="#">Item 3-5</a></li>
    </ul>
  </li>
  <li><a href="#">Item 4</a></li>
  <li><a href="#">Item 5</a></li>
 </ul>
</oj-navigation-list>

JSON Tree Node Format


Each node object typically have an attr property. This attr value will be provided as itemContext.data to renderer function. See itemContext section. Any node can be defined as a parent by supplying a children property, which is an array of one or more node definitions. (Note: lazy-loading is not supported in navigation list so children property should be a non empty array)

Example: Basic JSON Tree definition 


[
  {
    "attr": {
              "id": "home",
              "title": "Home"
            },
  },
  {
    "attr": {
              "id": "news",
              "title": "News"
            }
  },
  {
     "attr": {
               "id": "blogs",
               "title": "Blogs"
             },
     "children": [ {

                      "attr": {
                                  "id": "today",
                                  "title": "Today"
                              }
                   },
                   {
                      "attr": {
                                  "id": "yesterday",
                                  "title": "Yesterday"
                              }
                   }
                 ]
  }
]


Any list item can be disabled by adding the oj-disabled class to that element. As with any DOM change, doing so post-init requires a refresh() of the element.

Key

Key is an identifier which uniquely identifies an item in Navigation List.

  • When static html is used, it will be the id attribute of <li>. If no id is specified then component will generate an id and will use it as key.
  • When data source is used, it will be the id attribute of item's data object.

Icons

Sublist icons are inserted automatically. To add other icons to list items, include them in the markup and include the oj-navigationlist-item-icon class, as follows: 

<oj-navigation-list>
  <ul>
    <li id="foo"><a href="#"><span class="oj-navigationlist-item-icon demo-icon-font-24 demo-palette-icon-24"></span>Foo</a></li>
  </ul>
 </oj-navigation-list>

Styling

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

Class Description Example
oj-navigationlist-stack-icon-label Displays horizontal Navigation List with icon and label stacked. Applicable only when edge is top. 
<oj-navigation-list class="oj-navigationlist-stack-icon-label" >
 <ul>
   <li id="foo">
     <a href="#">
       <span class="oj-navigationlist-item-icon demo-icon-font-24 demo-palette-icon-24">
       </span>
       Foo
     </a>
   </li>
 </ul>
</oj-navigation-list>
oj-navigationlist-category-divider Use this class to add horizontal divider line between two categories of items. 
<oj-navigation-list>
 <ul>
   <li ...> </li>
   <li class="oj-navigationlist-category-divider"> </li>
   <li id="foo">
     <a href="#">
       <span class="oj-navigationlist-item-icon demo-icon-font-24 demo-palette-icon-24">
       </span>
       Foo
     </a>
   </li>
   <li ...> </li>
 </ul>
</oj-navigation-list>
oj-navigationlist-item-icon Use this class to add icon to list item. 
<oj-navigation-list>
 <ul>
   <li id="foo">
     <a href="#">
       <span class="oj-navigationlist-item-icon demo-icon-font-24 demo-palette-icon-24">
       </span>
       Foo
     </a>
   </li>
 </ul>
</oj-navigation-list>
oj-navigationlist-item-title When arbitrary content is placed inside item's content area, it's title text can be marked using this style class. This helps component in identifying the Item's label. 
<li>
  <div>
    <span class="oj-navigationlist-item-title">Play</span>
    <button>Button</button>
  </div>
</li>
oj-navigationlist-item-text-wrap Use this class to wrap item label text. Note: On IE11, this is not supported when overflow attribute is set to popup. 
<oj-navigation-list class="oj-navigationlist-item-text-wrap" >
 <ul>
   <li id="foo">
     <a href="#">
       <span class="oj-navigationlist-item-icon demo-icon-font-24 demo-palette-icon-24">
       </span>
       Foo
     </a>
   </li>
 </ul>
</oj-navigation-list>
oj-navigationlist-item-dividers Use this class to show dividers between horizontal navigation list items. 
<oj-navigation-list class="oj-navigationlist-item-dividers" >
 <ul>
   <li id="foo">
      <a href="#">
        <span class="oj-navigationlist-item-icon demo-icon-font-24 demo-palette-icon-24"></span>
        Foo
      </a>
   </li>
 </ul>
</oj-navigation-list>
oj-sm-condense Use this class to condense horizontal navigation list items on small screens and larger. 
<oj-navigation-list class="oj-sm-condense" >
 <ul>
   <li id="foo">
     <a href="#">
       <span class="oj-navigationlist-item-icon demo-icon-font-24 demo-palette-icon-24"></span>
       Foo
     </a>
   </li>
 </ul>
</oj-navigation-list>
oj-md-condense Use this class to condense horizontal navigation list items on medium screens and larger.
oj-lg-condense Use this class to condense horizontal navigation list items on large screens and larger.
oj-xl-condense Use this class to condense horizontal navigation list items on extra large screens and larger.
oj-navigationlist-nofollow-link Use this class to prevent automatic navigation to the url specified on <a> tag's href attribute. In this case, navigation can be handled programmatically by using selectionChanged event. This is useful to execute some custom logic before browser triggers navigation. 
<oj-navigation-list class="oj-navigationlist-nofollow-link" >
 <ul>
   <li id="foo"><a href="folder/foo.html">
     <span
       class="oj-navigationlist-item-icon demo-icon-font-24 demo-palette-icon-24"></span>
     Foo</a>
   </li>
 </ul>
</oj-navigation-list>
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.

Touch End User Information

Target Gesture Action
List Item Tap Selects the item.
Press & Hold Display context menu
Group Item Tap Expand or collapse the group item if drillMode is set to collapsible. When drillMode is set to sliding, sublist will silde in. When drillMode is set to none, group item will be selecetd.
Press & Hold Display context menu
Hierarchical Menu button Tap Open menu. Refer menu button touch documentation. Note: This is applicable only for Sliding Navigation List.
Overflow Menu button Tap Open menu. Refer menu button touch documentation. Note: This is applicable only for Horizontal Navigation List when overflow is set to popup.
Previous Icon or List Header Tap Collapses the sublist and slides to parent list. Note: This is applicable only for Sliding Navigation List.

Keyboard End User Information

Target Key Action
List Item Enter or Space Selects list item.
UpArrow Moves focus to the previous visible list item.
DownArrow Moves focus to the next visible list item
RightArrow (LeftArrow in RTL) For horizontal navigation list,focus will be moved to next visible item.
LeftArrow (RightArrow in RTL) For horizontal navigation list,focus will be moved to previous visible item.
Home Moves focus to the first visible list item.
End Moves focus to the last visible list item.
F2 If focus is on a list item, pressing F2 will make its contents accessible using TAB.
Esc When F2 mode is enabled, press Esc to exit F2 mode.
Shift+Tab Move fous to hierarchical menu button.Only applicable for sliding navigation list and when hierarchial menu button is enabled.
Group Item RightArrow (LeftArrow in RTL) If focus is on collapsed node, expands the sub list.
LeftArrow (RightArrow in RTL) If focus is on expanded node, collapses the sub list.
List Item in sublist Esc Applicable only for sliding navigation list. If focus is in a sub list, closes the sublist and moves focus to the parent list item.
Hierarchical Menu button Enter Open menu. Refer menu button keyboard documentation. Note: This target is visible only for Sliding Navigation List.
Tab Moves focus to current list item. Note: This target is visible only for Sliding Navigation List.
Shift + Tab Moves focus to Previous Icon. Note: This target is visible only for Sliding Navigation List.
Overflow Menu button Enter or Space Open menu. Refer menu button touch documentation. Note: This is applicable only for Horizontal Navigation List when overflow is set to popup.
Previous Icon or List Header Enter Collapses the sublist and slides to parent list.Note: This target is visible only for Sliding Navigation List.
Tab Moves focus to Hierarchical Menu button. Note: This target is visible only for Sliding Navigation List.

Disabled items will not receive keyboard focus and do not allow any interaction.

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 oj-navigation-list element.
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.

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 Navigation List makes it hard for user to find what they are looking for, but affects the load time. If displaying large number of items is neccessary, it is recommended to group the items in to hierarchial navigation list.

Item Content

Navigation List 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 Navigation List.

Expand All

While Navigation List provides a convenient way to initially expand all group items, 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.

Accessibility

See also the oj-focus-highlight discussion.

Disabled content: JET supports an accessible luminosity contrast ratio, as specified in WCAG 2.0 - Section 1.4.3 "Contrast", in the themes that are accessible. (See the "Theming" chapter of the JET Developer Guide for more information on which themes are accessible.) Note that Section 1.4.3 says that text or images of text that are part of an inactive user interface component have no contrast requirement. Because disabled content may not meet the minimum contrast ratio required of enabled content, it cannot be used to convey meaningful information.

Reading direction

The only supported way to set the reading direction (LTR or RTL) is to set the "dir" attribute on the <html> element of the page. As with any JET custom element, in the unusual case that the reading direction is changed post-init, the navigation list must be refresh()ed, or the page must be reloaded.

Animation

Applications can customize animations triggered by actions in Navigation List 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 $navigationListHorizontalAddAnimation When a new item is added to the oj.TableDataSource associated with Horizontal Navigation List.
$navigationListAddAnimation When a new item is added to the oj.TableDataSource associated with Vertical Navigation List.
remove $navigationListHorizontalRemoveAnimation When an existing item is removed from the oj.TableDataSource associated with Horizontal Navigation List.
$navigationListRemoveAnimation When an existing item is removed from the oj.TableDataSource associated with Vertical Navigation List.
update $navigationListUpdateAnimation When an existing item is updated in the oj.TableDataSource associated with Navigation List.
expand $navigationListExpandAnimation When user expands a group item.
$navigationListSliderExpandAnimation When user expands a group item in sliding navigation list.
collapse $navigationListCollapseAnimation When user collapses a group item.
$navigationListSliderCollapseAnimation When user collapses a group item in sliding navigation list.
pointerUp $navigationListPointerUpAnimation When user finish pressing an item (on touch).

Note: Application logic should not interact with the component's properties or invoke its methods until the BusyContext indicates that the component is ready for interaction.

Slots

JET components that allow child content support slots. Please see the slots section of the JET component overview doc for more information on allowed slot content and slot types.

contextMenu

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

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

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

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

itemTemplate

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.ojNavigationList.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-navigation-list> custom element
data Object The data for the current item being rendered
index number The zero-based index of the current item
key any The key of the current item being rendered
depth number The depth of the current item (available when hierarchical data is provided) being rendered. The depth of the first level children under the invisible root is 1.
leaf boolean True if the current item is a leaf node (available when hierarchical data is provided).
parentkey any The key of the parent item (available when hierarchical data is provided). The parent key is null for root nodes.

Attributes

as :string

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

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

data :(oj.TableDataSource|oj.TreeDataSource|oj.DataProvider|null) data :(oj.DataProvider.<K, D>|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, see Events and Listeners for additional information.) on-data-changed

display :"all"|"icons"

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:
Value Description
"all" Display both the label and icons.
"icons" 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, see Events and Listeners for additional information.) on-display-changed

drill-mode :"none"|"collapsible"|"sliding"

Defines style of navigation used to drill down hierarchical list items.
  • none
  • collapsible
  • sliding
Supported Values:
Value Description
"collapsible" Allows user to expand and collapse group items. If there are more than two levels in hierarchy, sliding is preferred drill mode.
"none" All group items are expanded by default and user not allowed to collapse them.
"sliding" 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, see Events and Listeners for additional information.) on-drill-mode-changed

edge :"top"|"start"

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. That means TreeDataProvider/TreeDataSource are not supported as data source.

Supported Values:
Value Description
"start" This renders list items vertically.
"top" 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, see Events and Listeners for additional information.) on-edge-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

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

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

(nullable) item.renderer :(((context: ojNavigationList.ItemContext<K,D>) => 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

(nullable) item.selectable :(((context: ojNavigationList.ItemContext<K,D>) => 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

overflow :"popup"|"hidden"

Specifies the overflow behaviour. NOTE: This is only applicable when edge attribute set to top
Supported Values:
Value Description
"hidden" overflow is clipped, and the rest of the content will be invisible.
"popup" popup menu will be shown with overflowed items.

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

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

selection :K

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

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

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

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

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

ojAnimateStart

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

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

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

ojBeforeCollapse

Triggered before an item is 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. See Events and Listeners for additional information.

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

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

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

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

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

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

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

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

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

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

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

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)

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}

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

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

ItemContext<K,D>

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

ItemTemplateContext

Properties:
Name Type Description
componentElement Element The <oj-navigation-list> custom element
data Object The data for the current item being rendered
index number The zero-based index of the current item
key any The key of the current item being rendered
depth number The depth of the current item (available when hierarchical data is provided) being rendered. The depth of the first level children under the invisible root is 1.
leaf boolean True if the current item is a leaf node (available when hierarchical data is provided).
parentkey any The key of the parent item (available when hierarchical data is provided). The parent key is null for root nodes.

NodeContext<K>

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.