Element: <oj-tab-bar>

Oracle® JavaScript Extension Toolkit (JET)
4.2.0

E91398-01

QuickNav

Attributes


Context Objects

PREVIEW: This is a preview API. Preview APIs are production quality, but can be changed on a major version without a deprecation path.

Version:
  • 4.2.0
Since:
  • 4.0.0

JET Custom Elements

JET components are implemented as custom HTML elements. A detailed description of working with these elements can be found in: JET Custom Element Usage.

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

The JET Tab Bar gets its data in following ways.

  • Using table datasource. There are several types of TableDataSource that are available out of the box like oj.ArrayTableDataSource,oj.CollectionTableDataSource.

    NOTE: oj.PagingTableDataSource is not supported by tab bar.

  • Using static content . The structure of the content should be flat as shown below.

Example of flat static content


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

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

  • 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-tabbar-item-icon class, as follows:

<oj-tab-bar>
  <ul>    
    <li id="foo"><a href="#"><span class="oj-tabbar-item-icon demo-icon-font-24 demo-palette-icon-24"></span>Foo</a></li>
  </ul>
 </oj-tab-bar>

Styling

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

Class Description Example
oj-tabbar-stack-icon-label Displays horizontal Tab Bar with icon and label stacked. Applicable only when edge is top.
<oj-tab-bar class="oj-tabbar-stack-icon-label" >
 <ul>    
   <li id="foo">
     <a href="#">
       <span class="oj-tabbar-item-icon demo-icon-font-24 demo-palette-icon-24">
       </span>
       Foo
     </a>
   </li>
 </ul>
</oj-tab-bar>
oj-tabbar-category-divider Use this class to add horizontal divider line between two categories of items.
<oj-tab-bar>
 <ul>
   <li ...> </li>
   <li class="oj-tabbar-category-divider"> </li>    
   <li id="foo">
     <a href="#">
       <span class="oj-tabbar-item-icon demo-icon-font-24 demo-palette-icon-24">
       </span>
       Foo
     </a>
   </li>
   <li ...> </li>
 </ul>
</oj-tab-bar>
oj-tabbar-item-icon Use this class to add icon to list item.
<oj-tab-bar>
 <ul>    
   <li id="foo">
     <a href="#">
       <span class="oj-tabbar-item-icon demo-icon-font-24 demo-palette-icon-24">
       </span>
       Foo
     </a>
   </li>
 </ul>
</oj-tab-bar>
oj-tabbar-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-tabbar-item-title">Play</span>
    <button>Button</button>
  </div>
</li>
oj-tabbar-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-tab-bar class="oj-tabbar-item-text-wrap" >
 <ul>    
   <li id="foo">
     <a href="#">
       <span class="oj-tabbar-item-icon demo-icon-font-24 demo-palette-icon-24">
       </span>
       Foo
     </a>
   </li>
 </ul>
</oj-tab-bar>
oj-tabbar-item-dividers Use this class to show dividers between horizontal tab bar items.
<oj-tab-bar class="oj-tabbar-item-dividers" >
 <ul>    
   <li id="foo">
      <a href="#">
        <span class="oj-tabbar-item-icon demo-icon-font-24 demo-palette-icon-24"></span>
        Foo
      </a>
   </li>
 </ul>
</oj-tab-bar>
oj-sm-condense Use this class to condense horizontal tab bar items on small screens and larger.
<oj-tab-bar class="oj-sm-condense" >
 <ul>    
   <li id="foo">
     <a href="#">
       <span class="oj-tabbar-item-icon demo-icon-font-24 demo-palette-icon-24"></span>
       Foo
     </a>
   </li>
 </ul>
</oj-tab-bar>
oj-md-condense Use this class to condense horizontal tab bar items on medium screens and larger.
oj-lg-condense Use this class to condense horizontal tab bar items on large screens and larger.
oj-xl-condense Use this class to condense horizontal tab bar items on extra large screens and larger.
oj-tabbar-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 tasks before browser triggers navigation.
<oj-tab-bar class="oj-tabbar-nofollow-link" >
 <ul>    
   <li id="foo"><a href="folder/foo.html">
     <span 
       class="oj-tabbar-item-icon demo-icon-font-24 demo-palette-icon-24"></span>
     Foo</a>
   </li>
 </ul>
</oj-tab-bar>
oj-removable Use this class to make an item removable.
<oj-tab-bar >
 <ul>    
   <li id="foo" class="oj-removable" ><a href="folder/foo.html">
     <span 
       class="oj-tabbar-item-icon demo-icon-font-24 demo-palette-icon-24"></span>
     Foo</a>
   </li>
 </ul>
</oj-tab-bar>
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
Overflow Menu button Tap Open menu. Refer menu button touch documentation. Note: This is applicable only for Horizontal Tab Bar when overflow is set to popup.

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 tab bar,focus will be moved to next visible item.
LeftArrow (RightArrow in RTL) For horizontal tab bar,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.
Ctrl+X Marks the current item to move if reorderable is enabled.
Ctrl+V Paste the item that are marked to directly before the current item
DELETE Delete the current item.
Overflow Menu button Enter or Space Open menu. Refer menu button touch documentation. Note: This is applicable only for Horizontal Tab Bar when overflow is set to popup.

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

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 Tab Bar makes it hard for user to find what they are looking for, but affects the load time.

Item Content

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

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 tab bar must be refresh()ed, or the page must be reloaded.

Animation

Applications can customize animations triggered by actions in Tab Bar 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 $tabBarHorizontalAddAnimation When a new item is added to the oj.TableDataSource associated with Horizontal Tab Bar.
$tabBarAddAnimation When a new item is added to the oj.TableDataSource associated with Vertical Tab Bar.
remove $tabBarHorizontalRemoveAnimation When an existing item is removed from the oj.TableDataSource associated with Horizontal Tab Bar.
$tabBarRemoveAnimation When an existing item is removed from the oj.TableDataSource associated with Vertical Tab Bar.
update $tabBarUpdateAnimation When an existing item is updated in the oj.TableDataSource associated with TabBar.
pointerUp $tabBarPointerUpAnimation When user finish pressing an item (on touch).

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

Slots

JET elements can have up to two types of child content:

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

contextMenu

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

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

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

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

Example

Initialize the component with a context menu:

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

Attributes

current-item :*

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.
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 Tab Bar with the current-item attribute specified:

 <oj-tab-bar current-item='settings'> ... </oj-tab-bar>

Get the current item:

var currentItem = myTabBar.currentItem;

Set the current item on the tabbar:

myTabBar.currentItem = "newItem";

data :oj.TableDataSource

The data source for the Tab Bar accepts either a oj.TableDataSource. 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 Tab Bar with the data attribute specified:

 <oj-tab-bar data='[[tableDataSource]]'> ... </oj-tab-bar>

Get the data:

var dataSource = myTabBar.data;

Set the data attribute using one-dimensional array:

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

Set the data attribute using oj.Collection:

myTabBar.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 tab bar 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 Tab Bar with the display attribute specified:

 <oj-tab-bar display='icons'> ... </oj-tab-bar>
 

Get or set the display property:

// getter
var display = myTabBar.display;

// setter
myTabBar.display = "icons";

edge :string

The position of the Tab Bar. Valid Values: top, bottom, start and end.
Supported Values:
Name Type Description
"bottom" string This renders list items horizontally. Generally used when tab bar placed on bottom of content section.
"end" string This renders list items vertically. Generally used when tab bar placed on right/end of content section.
"start" string This renders list items vertically. Generally used when tab bar placed on left/start of content section.
"top" string This renders list items horizontally. Generally used when tab bar placed on top of content section.
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 Tab Bar with the edge attribute specified:

 <oj-tab-bar edge='top'> ... </oj-tab-bar>

Get the edge:

var edge = myTabBar.edge;

Set the edge on the tabbar:

myTabBar.edge = "top";

item

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

item.renderer :function(Object)|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, Tab Bar will treat the data as a String.
Default Value:
  • null
Names
Item Name
Property item.renderer
Examples

Initialize the Tab Bar with the item.renderer attribute specified:

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

Get or set the renderer property:

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

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

item.selectable :function(Object)|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 Tab bar such that the first 3 items are not selectable:

 <oj-tab-bar item.selectable="[[skipFirstThreeElementsFn]]"></oj-tab-bar>
 
 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
Names
Item Name
Property overflow
Property change event overflowChanged
Property change listener attribute (must be of type function) on-overflow-changed
Examples

Initialize the Tab Bar with the overflow attribute specified:

 <oj-tab-bar overflow='popup'> ... </oj-tab-bar>

Get or set the overflow property:

// getter
var overflow = myTabBar.overflow;

// setter
myTabBar.overflow = "popup";

reorderable :string

PREVIEW: This is a preview API. Preview APIs are production quality, but can be changed on a major version without a deprecation path.

Specifies if the tabs can be reordered within the tab bar by drag-and-drop.
Supported Values:
Name Type Description
"disabled" string Disables reordering of items in tabbar.
"enabled" string Enables reordering of items in tabbar.
Default Value:
  • disabled
Since:
  • 4.1.0
Names
Item Name
Property reorderable
Property change event reorderableChanged
Property change listener attribute (must be of type function) on-reorderable-changed
Examples

Initialize the Tab Bar with the reorderable attribute specified:

 <oj-tab-bar reorderable='enabled'> ... </oj-tab-bar>

Get the reorderable:

var reorderable = myTabBar.reorderable;

Set the edge on the tabbar:

myTabBar.reorderable = "enabled";

selection :*

Item Key of currently selected list item. If the value is modified by an application, tab bar UI is modified to match the new value.
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 Tab Bar with the selection attribute specified:

 <oj-tab-bar selection='settings'> ... </oj-tab-bar>
 

Get the selection:

var selection = myTabBar.selection;

Set the selection on the tabbar:

myTabBar.selection = "settings";

translations :Object

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 this component has translations, their documentation immediately follows this doc entry.

Default Value:
  • an object containing all resources relevant to the component, or null if none
Names
Item Name
Property translations
Property change event translationsChanged
Property change listener attribute (must be of type function) on-translations-changed
Examples

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

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

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

Get or set the translations property after initialization:

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

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

// Get all
var values = myComponent.translations;

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

translations.accessible-reorder-after-item :Object

Provides properties to customize the screen reader text when the tentative drop target is after a certain item.

Default Value:
  • After {item}
Since:
  • 4.1.0
Names
Item Name
Property translations.accessibleReorderAfterItem

translations.accessible-reorder-before-item :Object

Provides properties to customize the screen reader text when the tentative drop target is before a certain item.

Default Value:
  • Before {item}
Since:
  • 4.1.0
Names
Item Name
Property translations.accessibleReorderBeforeItem

translations.accessible-reorder-touch-instruction-text :Object

Provides properties to customize the screen reader touch instructional text for reordering items.

Default Value:
  • Double tap and hold. Wait for the sound then drag to rearrange.
Since:
  • 4.1.0
Names
Item Name
Property translations.accessibleReorderTouchInstructionText

translations.label-cut :Object

Provides properties to customize the context menu cut label.

See the translations attribute for usage examples.

Default Value:
  • Cut
Since:
  • 4.1.0
Names
Item Name
Property translations.labelCut

translations.label-paste-after :Object

Provides properties to customize the context menu paste after label.

See the translations attribute for usage examples.

Default Value:
  • Paste After
Since:
  • 4.1.0
Names
Item Name
Property translations.labelPasteAfter

translations.label-paste-before :Object

Provides properties to customize the context menu paste before label.

See the translations attribute for usage examples.

Default Value:
  • Paste Before
Since:
  • 4.1.0
Names
Item Name
Property translations.labelPasteBefore

translations.label-remove :Object

Provides properties to customize the context menu remove label.

See the translations attribute for usage examples.

Default Value:
  • Remove
Since:
  • 4.1.0
Names
Item Name
Property translations.labelRemove

translations.msg-fetching-data :string

Provides properties to customize the message text used by Tab Bar when waiting for data.

See the translations attribute for usage examples.

Default Value:
  • Fetching Data...
Since:
  • 4.0.0
Names
Item Name
Property translations.msgFetchingData

translations.msg-no-data :string

Provides properties to customize the message text used by Tab Bar when there are no items.

See the translations attribute for usage examples.

Default Value:
  • No items to display.
Since:
  • 4.0.0
Names
Item Name
Property translations.msgNoData

translations.overflow-item-label :string

Label for overflow menu button.

See the translations attribute for usage examples.

Default Value:
  • More
Since:
  • 4.0.0
Names
Item Name
Property translations.overflowItemLabel

translations.remove-cue-text :string

Text cue for the removable tab, used as the aria-label for the close icon.

Default Value:
  • Removable
Since:
  • 4.1.0
Names
Item Name
Property translations.removeCueText

translations.selected-label :string

Provides text to read to screen reader when an item is selected.

See the translations attribute for usage examples.

Default Value:
  • selected
Since:
  • 4.0.0
Names
Item Name
Property translations.selectedLabel

truncation :string

PREVIEW: This is a preview API. Preview APIs are production quality, but can be changed on a major version without a deprecation path.

Truncation applies to the tab titles when there is not enough room to display all tabs.
Supported Values:
Name Type Description
"none" string tabs always take up the space needed by the title texts.
"progressive" string If not enough space is available to display all of the tabs, then the width of each tab title is restricted just enough to allow all tabs to fit. All tab titles that are truncated are displayed with ellipses. However the width of each tab title will not be truncated below $tabBarTruncatedLabelMinWidth.
Default Value:
  • none
Since:
  • 4.1.0
Names
Item Name
Property truncation
Property change event truncationChanged
Property change listener attribute (must be of type function) on-truncation-changed
Examples

Initialize the Tab Bar with the truncation attribute specified:

 <oj-tab-bar truncation='progressive'> ... </oj-tab-bar>

Get the truncation property:

var truncation = myTabBar.truncation;

Set the truncation on the tabbar:

myTabBar.truncation = "progressive";

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

Context for the oj-tab-bar component's items.

Properties:
Name Type Description
index number the zero based item index
key Object | string the Key of the item

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 Object the action that started the animation. See animation section for a list of actions.
element Object the target of animation.
Examples

Specify an ojAnimateEnd listener via the DOM attribute:

<oj-tab-bar on-oj-animate-end='[[listener]]'></oj-tab-bar>

Specify an ojAnimateEnd listener via the JavaScript property:

myTabBar.onOjAnimateEnd = listener;

Add an ojAnimateEnd listener via the addEventListener API:

myTabBar.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 Object the action that starts the animation. See animation section for a list of actions.
element Object the target of animation.
endCallback function 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-tab-bar on-oj-animate-start='[[listener]]'></oj-tab-bar>

Specify an ojAnimateStart listener via the JavaScript property:

myTabBar.onOjAnimateStart = listener;

Add an ojAnimateStart listener via the addEventListener API:

myTabBar.addEventListener('ojAnimateStart', listener);

ojBeforeCurrentItem

Triggered before the current item is changed via the currentItem property or via the UI. To prevent the item being focused, return false from event handler or invoke event.preventDefault().
Properties:

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

Name Type Description
previousKey Object | string the Key of the previous item
previousItem Element the previous item
key Object | string the Key of the new current item
item Element the new current item
Examples

Specify an ojBeforeCurrentItem listener via the DOM attribute:

<oj-tab-bar on-oj-before-current-item='[[listener]]'></oj-tab-bar>

Specify an ojBeforeCurrentItem listener via the JavaScript property:

myTabBar.onOjBeforeCurrentItem = listener;

Add an ojBeforeCurrentItem listener via the addEventListener API:

myTabBar.addEventListener('ojBeforeCurrentItem', listener);

ojBeforeDeselect

PREVIEW: This is a preview API. Preview APIs are production quality, but can be changed on a major version without a deprecation path.

Triggered immediately before a tab is deselected. To prevent the item being deselected, return false from event handler or invoke event.preventDefault().
Properties:

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

Name Type Description
fromKey Object the key of the tab item being navigated from
fromItem Element the tab item being navigated from
toKey Object the key of the tab item being navigated to
toItem Element the tab item being navigated to
Since:
  • 4.1.0
Examples

Specify an ojBeforeDeselect listener via the DOM attribute:

<oj-tab-bar on-oj-before-deselect='[[listener]]'></oj-tab-bar>

Specify an ojBeforeDeselect listener via the JavaScript property:

myTabBar.onOjBeforeDeselect = listener;

Add an ojBeforeDeselect listener via the addEventListener API:

myTabBar.addEventListener('ojBeforeDeselect', listener);

ojBeforeRemove

PREVIEW: This is a preview API. Preview APIs are production quality, but can be changed on a major version without a deprecation path.

Triggered before the item is removed via the UI. To prevent the item being removed, return false from event handler or invoke event.preventDefault().
Properties:

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

Name Type Description
item Element Item being removed
key string Key of the item being removed
Since:
  • 4.1.0
Examples

Specify an ojBeforeRemove listener via the DOM attribute:

<oj-tab-bar on-oj-before-remove='[[listener]]'></oj-tab-bar>

Specify an ojBeforeRemove listener via the JavaScript property:

myTabBar.onOjBeforeRemove = listener;

Add an ojBeforeRemove listener via the addEventListener API:

myTabBar.addEventListener('ojBeforeRemove', listener);

ojBeforeSelect

Triggered before this list item is selected. To prevent the item selection, return false from event handler or invoke event.preventDefault().

The ui.key contains item key which uniquely identifies the item. ui.item payload field contains item element being selected.

Properties:

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

Name Type Description
key Object | string Selected list item Key.
item Element Selected list item.
Examples

Specify an ojBeforeSelect listener via the DOM attribute:

<oj-tab-bar on-oj-before-select='[[listener]]'></oj-tab-bar>

Specify an ojBeforeSelect listener via the JavaScript property:

myTabBar.onOjBeforeSelect = listener;

Add an ojBeforeSelect listener via the addEventListener API:

myTabBar.addEventListener('ojBeforeSelect', listener);

ojDeselect

PREVIEW: This is a preview API. Preview APIs are production quality, but can be changed on a major version without a deprecation path.

Triggered after a tab has been deselected.
Properties:

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

Name Type Description
fromKey Object the key of the tab item being navigated from
fromItem Element the tab item being navigated from
toKey Object the key of the tab item being navigated to
toItem Element the tab item being navigated to
Since:
  • 4.1.0
Examples

Specify an ojDeselect listener via the DOM attribute:

<oj-tab-bar on-oj-deselect='[[listener]]'></oj-tab-bar>

Specify an ojDeselect listener via the JavaScript property:

myTabBar.onOjDeselect = listener;

Add an ojDeselect listener via the addEventListener API:

myTabBar.addEventListener('ojDeselect', listener);

ojRemove

PREVIEW: This is a preview API. Preview APIs are production quality, but can be changed on a major version without a deprecation path.

Triggered immediately after a tab is removed. This should be used to remove item from dom or from data source.
Properties:

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

Name Type Description
item Element Item removed
key string Key of the item removed
Since:
  • 4.1.0
Examples

Specify an ojRemove listener via the DOM attribute:

<oj-tab-bar on-oj-remove='[[listener]]'></oj-tab-bar>

Specify an ojRemove listener via the JavaScript property:

myTabBar.onOjRemove = listener;

Add an ojRemove listener via the addEventListener API:

myTabBar.addEventListener('ojRemove', listener);

ojReorder

PREVIEW: This is a preview API. Preview APIs are production quality, but can be changed on a major version without a deprecation path.

Triggered after reordering items within tabbar via drag and drop or cut and paste. This should be used to reorder item in dom or data source.
Properties:

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

Name Type Description
item Element Item to be moved
position string the drop position relative to the reference item. Possible values are "before" and "after".
reference Element the item where the moved items are drop on.
Since:
  • 4.1.0
Examples

Specify an ojReorder listener via the DOM attribute:

<oj-tab-bar on-oj-reorder='[[listener]]'></oj-tab-bar>

Specify an ojReorder listener via the JavaScript property:

myTabBar.onOjReorder = listener;

Add an ojReorder listener via the addEventListener API:

myTabBar.addEventListener('ojReorder', listener);

Methods

getContextByNode(node) → {Object|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 Description
node Element The child DOM node
Returns:
The context for the DOM node, or null when none is found.
Type
Object | null
Example
 // Returns {'subId': 'oj-some-sub-id', 'componentSpecificProperty': someValue, ...}
var context = myComponent.getContextByNode(nodeInsideElement);

getProperty(property) → {*}

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

Get a single subproperty of a complex property:

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

refresh()

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

This method does not accept any arguments.

Example

Invoke the refresh method:

 myTabBar.refresh();

setProperties(properties)

Performs a batch set of properties.
Parameters:
Name Type Description
properties Object An object containing the property and value pairs to set.
Example

Set a batch of properties:

myComponent.setProperties({"prop1": "value1", "prop2.subprop": "value2", "prop3": "value3"});

setProperty(property, value)

Sets a property or a single subproperty for complex properties and notifies the component of the change, triggering a [property]Changed event.
Parameters:
Name Type Description
property string The property name to set. Supports dot notation for subproperty access.
value * The new value to set the property to.
Example

Set a single subproperty of a complex property:

myComponent.setProperty('complexProperty.subProperty1.subProperty2', "someValue");