Class: ojTabs

Oracle® Fusion Middleware Oracle JavaScript Extension Toolkit (JET)
12c (12.1.4)
E54107-01

QuickNav

Options

Events

Methods


Non-public methods (internal use only)

oj. ojTabs extends oj.baseComponent

JET Tabs Component

Description: Themeable, WAI-ARIA-compliant tabs with mouse and keyboard interactions for navigation.

A JET Tabs can be created from any valid markup as long as the root element has one or more child elements and each child element must have at least two children: the first element for the title and the rest of the element(s) for the content. 


<div id="tabs">
  <div id ="tab-1">
    <span>Tab 1</span>
    <p>Tab 1 content</p>
    <p>Tab 1 more content</p>
  </div>
  <div id ="tab-2">
    <span>Tab 2</span>
    <p>Tab 2 content</p>
  </div>
  <div id ="tab-3">
    <span>Tab 3</span>
    <p>Tab 3 content</p>
  </div>
</div>

Keyboard interaction

When the focus is on the tab bar

Key Use
Tab Only the selected tab is in the tab order.
UpArrow or LeftArrow (RightArrow in RTL) Move focus to the previous tab and select it.
DownArrow or RightArrow (LeftArrow in RTL) Move focus to the next tab and select it.
Home Move focus to the first tabs item.
End Move focus to the last tabs item.
Delete If deletion is allowed, will delete the current tab.

When the focus is on anywhere within the tab content

Key Use
Shift+Tab move focus to the tab for that panel.

Disabled items can receive keyboard focus, but do not allow any other interaction.

Reading direction

As with any JET component, in the unusual case that the directionality (LTR or RTL) changes post-init, the tabs must be refresh()ed.

Pseudo-selectors

The :oj-tabs pseudo-selector can be used in jQuery expressions to select JET Tabs. For example: 

$( ":oj-tabs" ) // selects all JET Tabs on the page
$myEventTarget.closest( ":oj-tabs" ) // selects the closest ancestor that is a JET Tabs

JET for jQuery UI developers

    • JQUI Tabs expects the tabs titles either in an ordered or unordered list followed by their content elements. Each tab must have an anchor with the href points to its content element. 
          
      <div id="tabs">
        <ul>
          <li><a href="#tabs-1">Tab 1 Title</a></li>
          <li><a href="#tabs-2">Tab 2 Title</a></li>
        </ul>
        <div id="tabs-1">
          <p>Tab 1 content.</p>
        </div>
        <div id="tabs-2">
          <p>Tab 2 content.</p>
          <p>More Tab 2 content.</p>
        </div
      </div>
    • JET Tabs requires a simplier DOM structures. Like the JQuery Accordion, the tabs is a list of tab where each tab contains its own title and content. It requires no anchors and pointers to the contents. 
          
      <div id="tabs">
        <div id="tabs-1">
          <span>Tab 1 Title</span>
          <p>Tab 1 content.</p>
        </div>
        <div id="tabs-2">
          <span>Tab 2 Title</span>
          <p>Tab 2 content.</p>
          <p>More Tab 2 content.</p>
        </div
      </div>
  1. All JQUI and JET components inherit disable() and enable() methods from the base class. This API duplicates the functionality of the disabled option. In JET, to keep the API as lean as possible, we have chosen not to document these methods outside of this section.
  2. JET Tabs supports orientation option: to be placed horizontal (default) or vertical
  3. JET Tabs supports removable option by adding a close icon to each tab which when clicked remove the tab from the DOM.
  4. JET Tabs supports reorderable option allow the tab to be reordered by drag and drop within the Tab bar

Also, event names for all JET components are prefixed with "oj", instead of component-specific prefixes like "tabs". E.g. the JQUI tabscreate event is ojcreate in JET, as shown in the doc for that event. Reason: This makes the API more powerful. It allows apps to listen to "foo" events from all JET components via: 

$( ".selector" ).on( "ojfoo", myFunc);
or to "foo" events only from JET Tabs (the JQUI functionality) via: 
$( ".selector" ).on( "ojfoo", ":oj-tabs", myFunc);

Initializer

.ojTabs()

Creates a JET Tabs.
Source:
Examples

Initialize the tabs with no options specified:

$( ".selector" ).ojTabs();

Initialize the tabs with some options and callbacks specified:

$( ".selector" ).ojTabs( { "disabled": true, "create": function( event, ui ) {} } );

Initialize the tabs via the JET ojComponent binding:

<div id="tabs" data-bind="ojComponent: { component: 'ojTabs', 
                                            disabled: [1], 
                                            reorderable: true }">

Options

#contextMenu :Object

JQ selector identifying the JET Menu that the component should launch as a context menu on right-click or Shift-F10. If specified, the browser's native context menu will be replaced by the specified JET Menu.

To specify a JET context menu on a DOM element that is not a JET component, see the ojContextMenu binding.

To make the page semantically accurate from the outset, applications are encouraged to specify the context menu via the standard HTML5 syntax shown in the below example. When the component is initialized, the context menu thus specified will be set on the component.

The JET Menu should be initialized before any component using it as a context menu.

Default Value:
  • null
Inherited From:
Source:
Examples

Initialize a JET component with a context menu:

// via recommended HTML5 syntax:
<div id="myComponent" contextmenu="myMenu" data-bind="ojComponent: { ... }>

// via JET initializer (less preferred) :
$( ".selector" ).ojFoo({ "contextMenu": "#myMenu" });

Get or set the contextMenu option, after initialization:

// getter
var menu = $( ".selector" ).ojFoo( "option", "contextMenu" );

// setter
$( ".selector" ).ojFoo( "option", "contextMenu", ".my-marker-class" );

Set a JET context menu on an ordinary HTML element:

<a href="#" id="myAnchor" contextmenu="myMenu" data-bind="ojContextMenu: {}">Some text

#disabled :{boolean|Array} Boolean: Enable or disable all tabs. Array: An array containing the zero-based indexes of the tabs that should be disabled.

Which tabs are disabled.
Default Value:
  • false
Source:
Example
 [ 0, 2 ] would disable the first and third tab.

#orientation :string

The orientation of the tab bar. Valid Values: horizontal and vertical
Default Value:
  • "horizontal"
Source:

#removable :boolean

Specifies if the tabs can be closed (removed)
Default Value:
  • false
Source:

#removeCueText :string

This text is used to provide audible feedback for screen reader users
Default Value:
  • Tab is removable
Source:

#reorderable :boolean

Specifies if the tabs can be reordered within the tab bar by drag-and-drop
Default Value:
  • false
Source:

#rootAttributes :Object|undefined

Attributes specified here will be set on the component's root DOM element at creation time. This is particularly useful for components like Dialog that wrap themselves in a root element at creation time.

The specified class and style are appended to the current class and style, respectively. All other attributes overwrite any existing value.

Setting this option after component creation has no effect.

Default Value:
  • undefined
Inherited From:
Source:
Example

Initialize a JET component, specifying a set of attributes to be set on the component's root DOM element:

$( ".selector" ).ojFoo({ "rootAttributes": {
  'id': 'myId', 
  'style': 'max-width:100%; color:blue;', 
  'class': 'my-class'
}});

#selected :number

The zero-based index of the panel that is selected (open).
Default Value:
  • 0
Source:

#selectOn :string

The type of event to select the tab. To select a tab on hover, use "mouseover".
Default Value:
  • "click"
Source:

#truncation :string

Truncation option applies to the tab titles when there is not enough room to display all tabs. Valid Values: none, progressive and auto.
  • none - tabs always take up the space needed by the label texts. When there is not enough room, the conveyorBelt's navigation arrows are displayed to allow the label texts be scrolled within the conveyor.
  • progressive - If not enough space is available to display all of the tabs, then the width of each tab label is restricted just enough to allow all tabs to fit. All tab labels that are truncated are displayed with ellipses. However the width of each tab will not be truncated below tabLabelMinWidth. If after all truncation has been applied, there still is not enough room, then the conveyorBelt's navigation arrows will appear. When the container of the tabs is resized the truncation will be reevaluated.
  • auto - same as "progressive".
Default Value:
  • auto
Source:

Events

#afterDeselect

Triggered after a tab has been deselected. The afterDeselect can be cancelled by calling event.preventDefault().
Properties:
Name Type Description
event Event jQuery event object
ui Object Parameters
Properties
Name Type Description
newHeader jQuery The tab that was just deselected.
newContent jQuery The panel that was just deselected.
oldHeader jQuery The tab that was just selected.
oldContent jQuery The panel that was just selected.
Source:
Examples

Initialize the tabs with the afterDeselect callback specified:

$( ".deselector" ).ojTabs({
    "afterDeselect": function( event, ui ) {}
});

Bind an event listener to the ojafterdeselect event:

$( ".deselector" ).on( "ojafterdeselect", function( event, ui ) {} );

#afterRemove

Triggered after a tab has been removed.
Properties:
Name Type Description
event Event jQuery event object
ui Object Parameters
Properties
Name Type Description
header jQuery The tab that was just removed.
content jQuery The panel that was just removed.
Source:
Examples

Initialize the tabs with the afterRemove callback specified:

$( ".selector" ).ojTabs({
    "afterRemove": function( event, ui ) {}
});

Bind an event listener to the ojafterremove event:

$( ".selector" ).on( "ojafterremove", function( event, ui ) {} );

#afterSelect

Triggered after a tab has been selected. The afterSelect can be cancelled by calling event.preventDefault().
Properties:
Name Type Description
event Event jQuery event object
ui Object Parameters
Properties
Name Type Description
newHeader jQuery The tab that was just selected.
newContent jQuery The panel that was just selected.
oldHeader jQuery The tab that was just deselected.
oldContent jQuery The panel that was just deselected.
Source:
Examples

Initialize the tabs with the afterSelect callback specified:

$( ".selector" ).ojTabs({
    "afterSelect": function( event, ui ) {}
});

Bind an event listener to the ojafterselect event:

$( ".selector" ).on( "ojafterselect", function( event, ui ) {} );

#beforeDeselect

Triggered immediately before a tab is deselected. The beforeDeselect can be cancelled by calling event.preventDefault().
Properties:
Name Type Description
event Event jQuery event object
ui Object Parameters
Properties
Name Type Description
newHeader jQuery The tab that is about to be deselected.
newContent jQuery The panel that is about to be deselected.
oldHeader jQuery The tab that is about to be selected.
oldContent jQuery The panel that is about to be selected.
Source:
Examples

Initialize the tabs with the beforeDeselect callback specified:

$( ".deselector" ).ojTabs({
    "beforeDeselect": function( event, ui ) {}
});

Bind an event listener to the ojbeforedeselect event:

$( ".deselector" ).on( "ojbeforedeselect", function( event, ui ) {} );

#beforeRemove

Triggered immediately before a tab is removed. The beforeRemove can be cancelled by calling event.preventDefault().
Properties:
Name Type Description
event Event jQuery event object
ui Object Parameters
Properties
Name Type Description
header jQuery The tab that is about to be removed.
content jQuery The panel that is about to be removed.
Source:
Examples

Initialize the tabs with the beforeRemove callback specified:

$( ".selector" ).ojTabs({
    "beforeRemove": function( event, ui ) {}
});

Bind an event listener to the ojbeforeremove event:

$( ".selector" ).on( "ojbeforeremove", function( event, ui ) {} );

#beforeSelect

Triggered immediately before a tab is selected. The beforeSelect can be cancelled by calling event.preventDefault().
Properties:
Name Type Description
event Event jQuery event object
ui Object Parameters
Properties
Name Type Description
newHeader jQuery The tab that is about to be selected.
newContent jQuery The panel that is about to be selected.
oldHeader jQuery The tab that is about to be deselected.
oldContent jQuery The panel that is about to be deselected.
Source:
Examples

Initialize the tabs with the beforeSelect callback specified:

$( ".selector" ).ojTabs({
    "beforeSelect": function( event, ui ) {}
});

Bind an event listener to the ojbeforeselect event:

$( ".selector" ).on( "ojbeforeselect", function( event, ui ) {} );

#optionChange

Fired whenever a supported component option changes, whether due to user interaction or programmatic intervention. If the new value is the same as the previous value, no event will be fired. Currently there is one supported option, "selected". Additional options may be supported in the future, so listeners should verify which option is changing before taking any action.
Properties:
Name Type Description
event Event jQuery event object
ui Object Parameters
Properties
Name Type Description
option string the name of the option that is changing
previousValue Object the previous value of the option
value Object the current value of the option
optionMetadata Object information about the option that is changing
Properties
Name Type Description
writeback string "shouldWrite" or "shouldNotWrite". For use by the JET writeback mechanism.
Source:

Methods

#addTab(newTab)

Add a tab to the end of the tabs
Parameters:
Name Type Description
newTab jQuery jQuery object of the new tab
Source:
Returns:
When called via the public jQuery syntax, this method returns the object on which it was called, to facilitate method chaining.
Example

Invoke the addTab method:

$( ".selector" ).ojTabs( "addTab", $("<div><h3>New Tab</h3><p>Content of New Tab</p></div>") );

#disable(index)

Disables a tab.
Parameters:
Name Type Description
index number zero-based index of the tabs to disable
Source:
Returns:
When called via the public jQuery syntax, this method returns the object on which it was called, to facilitate method chaining.
Example

Invoke the disable method:

$( ".selector" ).ojTabs( "disable", 1 );

#enable(index)

Enables a tab.
Parameters:
Name Type Description
index number zero-based index of the tabs to enable
Source:
Returns:
When called via the public jQuery syntax, this method returns the object on which it was called, to facilitate method chaining.
Example

Invoke the enable method:

$( ".selector" ).ojTabs( "enable", 1 );

#getNodeBySubId(locator) → {Element|null}

Return the subcomponent node represented by the documented locator attribute values. To lookup a title text the locator object should have the following: subId: 'oj-tabs-title' index: number To lookup a close icon the locator object should have the following: subId: 'oj-tabs-close-icon' index: number To lookup a panel content the locator object should have the following: subId: 'oj-tabs-panel' index: number To lookup the conveyorbelt the locator object should have the following: subId: 'oj-conveyorbelt'
Parameters:
Name Type Description
locator Object An Object containing at minimum a subId property whose value is a string, documented by the component, that allows the component to look up the subcomponent associated with that string. It contains:

component: optional - in the future there may be more than one component contained within a page element

subId: the string, documented by the component, that the component expects in getNodeBySubId to locate a particular subcomponent
Source:
Returns:
the subcomponent located by the subId string passed in locator, if found.

Type
Element | null

#getSubIdByNode(node) → {string|null}

Return the subId string for the given child DOM node
Parameters:
Name Type Description
node Element child DOM node
Inherited From:
Source:
Returns:
- the subId for the DOM node or null when none is found
Type
string | null

#option(optionName, value) → {Object|undefined}

This method has several overloads, which gets and set component options.

The first overload accepts a single optionName param as a string, and returns the current value of that option.

The second overload accepts two params, an optionName string and a new value to which that option will be set.

The third overload accepts no params, and returns a map of key/value pairs representing all the component options and their values.

The fourth overload accepts a single map of option-value pairs to set on the component.

Parameters:
Name Type Argument Description
optionName string | Object <optional>
 the option name (string, first two overloads), or the map (Object, last overload). Omitted in the third overload.
value Object <optional>
 a value to set for the option. Second overload only.
Inherited From:
Source:
Returns:
The getter overloads return the retrieved value(s). When called via the public jQuery syntax, the setter overloads return the object on which they were called, to facilitate method chaining.
Type
Object | undefined
Examples

First overload: get one option:

var isDisabled = $( ".selector" ).ojFoo( "option", "disabled" ); // Foo is Button, Menu, etc.

Second overload: set one option:

$( ".selector" ).ojFoo( "option", "disabled", true ); // Foo is Button, Menu, etc.

Third overload: get all options:

var options = $( ".selector" ).ojFoo( "option" ); // Foo is Button, Menu, etc.

Fourth overload: set one or more options:

$( ".selector" ).ojFoo( "option", { disabled: true } ); // Foo is Button, Menu, etc.

#refresh()

Refreshes the visual state of the tabs. JET components require a refresh() or re-init after the DOM is programmatically changed underneath the component.

This method does not accept any arguments.

Source:
Returns:
When called via the public jQuery syntax, this method returns the object on which it was called, to facilitate method chaining.
Example

Invoke the refresh method:

$( ".selector" ).ojTabs( "refresh" );

Non-public Methods

Note: Extending JET components is not currently supported. Thus, non-public methods are for internal use only.

<protected> #_AfterCreate()

This method is called after _ComponentCreate. The JET base component does tasks here that must happen after the component (subclass) has created itself in its override of _ComponentCreate. Notably, the base component handles the rootAttributes and contextMenu options here, since those options operate on the component root node, which for some components is created in their override of _ComponentCreate.

Subclasses should override this method only if they have tasks that must happen after a superclass's implementation of this method, e.g. tasks that must happen after the context menu is set on the component.

Overrides of this method should call this._super first.

Inherited From:
Source:
Returns:
When called via the public jQuery syntax, this method returns the object on which it was called, to facilitate method chaining.

<protected> #_ComponentCreate()

All component create-time initialization lives in this method, except the logic that specifically needs to live in _InitOptions or _AfterCreate, per the documentation for those methods. All DOM creation must happen here, since the intent of _AfterCreate is to contain superclass logic that must run after that DOM is created.

Overrides of this method should call this._super first.

Inherited From:
Source:
Returns:
When called via the public jQuery syntax, this method returns the object on which it was called, to facilitate method chaining.

<protected> #_GetReadingDirection() → {string}

Determines whether the component is LTR or RTL.

Component responsibilities:

  • All components must determine directionality exclusively by calling this protected superclass method. (So that any future updates to the logic can be made in this one place.)
  • Components that need to know the directionality must call this method from _create() and refresh(), and cache the value.
  • Components should not call this at other times, and should instead use the cached value. (This avoids constant DOM queries, and avoids any future issues if directional islands and component reparenting (e.g. popups) should coexist.)

App responsibilities:

  • The app specifies directionality by setting the HTML "dir" attribute on the <html> node. When omitted, the default is "ltr". (Per-component directionality / directional islands are not currently supported due to inadequate CSS support.)
  • As with any DOM change, the app must refresh() the component if the directionality changes dynamically. (This provides a hook for component housekeeping, and allows caching.)
Default Value:
  • "ltr"
Inherited From:
Source:
Returns:
the reading direction, either "ltr" or "rtl"
Type
string

<protected> #_GetSavedAttributes(element) → {Object}

Gets the saved attributes for the provided element. This is usually the original list of attributes set on the element.
Parameters:
Name Type Description
element Object jQuery selection, should be a single entry
Inherited From:
Source:
Returns:
savedAttributes - attributes that were saved for this element.
Type
Object

<protected> #_InitOptions()

This method is called before _ComponentCreate, at which point the component has not yet been rendered. Component options should be initialized in this method, so that their final values are in place when _ComponentCreate is called.

This includes getting option values from the DOM, where applicable, and coercing option values (however derived) to their appropriate data type. No other work should be done in this method. See below for details.

Overrides of this method should call this._super first.

Usage:

  • If the component has an option like disabled that can be set from the DOM at create time, then the "get from DOM" logic should live in this method. E.g. a typical override might say "if the disabled option still has its initial value of undefined (i.e., the option has not been set), then get the DOM property and set it on the option." (See also next bullet.)
  • For attributes that live on the component's root node, keep in mind that anything specified via the rootAttributes option will not be placed on the DOM until _AfterCreate. So when getting attributes from the root node, components must first look in the rootAttributes option, and then, only if the attribute is not found there, look on the component root (if it already exists).
  • For options that, unlike disabled, have no corresponding DOM property, and are not otherwise set from the DOM, there is nothing to do in this method.
  • Do NOT set anything on the DOM in this method (like the resolved disabled value, or any rootAttributes values). The resolved option values should be set on the DOM later, in _ComponentCreate, and the rootAttributes values are set in baseComponent._AfterCreate.
Inherited From:
Source:
Returns:
When called via the public jQuery syntax, this method returns the object on which it was called, to facilitate method chaining.

<protected> #_RestoreAttributes()

Restores the saved element's attributes
Inherited From:
Source:
Returns:
When called via the public jQuery syntax, this method returns the object on which it was called, to facilitate method chaining.

<protected> #_SaveAttributes(element)

Saves the element's attributes within an internal variable to be reset during the destroy function The JSON variable will be held as : [ { "element" : element[i], "attributes" : { attributes[m]["name"] : {"attr": attributes[m]["value"], "prop": $(element[i]).prop(attributes[m]["name"]) } } ]
Parameters:
Name Type Description
element Object jQuery selection to save attributes for
Inherited From:
Source:
Returns:
When called via the public jQuery syntax, this method returns the object on which it was called, to facilitate method chaining.

<protected> #_SetRootAttributes()

Reads the rootAttributes option, and sets the root attributes on the component's root DOM element.

class and style are appended to the current class and style, respectively. All other attributes overwrite any existing value.

Inherited From:
Source:
Returns:
When called via the public jQuery syntax, this method returns the object on which it was called, to facilitate method chaining.