Class: ojButtonset

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. ojButtonset extends oj.baseComponent

JET Buttonset Component

Description: Themeable, WAI-ARIA-compliant visual and semantic grouping container for JET Buttons.

The JET Buttonset component can be used to group related buttons, such as a group of radios or checkboxes. Buttonset provides visual and semantic grouping and WAI-ARIA-compliant focus management.

When a Buttonset is created or refreshed, it creates JET Buttons out of all contained DOM elements supported by JET Button that are not already Buttons, by calling .ojButton() on them.

A buttonset that contains radios should contain all radios in the radio group. Checkboxes and radios in the buttonset should specify the value attribute, since the checked option refers to that attribute.

Keyboard interaction and Focus management

JET Buttonset manages its own focus. It maintains a single tabstop, with arrow-key navigation within the buttonset. This navigation skips disabled buttons, wraps around at the end, and adjusts correctly in RTL.

When tabbing back into the buttonset, focus goes to the most recently focused button. (To address a browser limitation, if that button is an unchecked radio having a checked groupmate, the latter is focused instead.)

As with any JET Button, buttons in a buttonset are activated with Enter or Spacebar.

The application should not do anything to interfere with the focus management. E.g. it should not set the tabindex of the buttons, or do anything that prevents enabled buttons from being a tabstop. Also, enabled buttons should remain user-visible, without which arrow-key navigation to the button would cause the focus to seemingly disappear.

The buttonset's focus management should be turned off when placing the buttonset in a JET Toolbar. See the focusManagement option.

Accessibility

JET Buttonset takes care of focus management, as noted above, and setting role="group" on the buttonset element.

In addition, as shown in the online demos, the application is responsible for applying aria-label and/or aria-controls attributes like the following to the buttonset element, if applicable per the instructions that follow: 

aria-label="Choose only one beverage.  Use left and right arrow keys to navigate."
aria-controls="myTextEditor"

A sentence like the first is appropriate for a buttonset consisting of a radio group, in order to convey the "select one" semantics to AT users. It should be omitted for checkboxes and push buttons.

The second sentence lets the user know how to navigate. It should be omitted if the buttonset's focus management is turned off via the focusManagement option.

The aria-controls attribute is appropriate if the buttonset is controlling something else on the page, e.g. bold/italic/underline buttons controlling a rich text editor.

Reading direction

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

Pseudo-selectors

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

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

Declarative Binding

For components like Buttonset and Menu that contain a number of like items, applications may wish to use a foreach Knockout binding to stamp out the contents. This binding cannot live on the same node as the JET ojComponent binding, and must instead live on a nested virtual element as follows: 

<div id="drinkset" data-bind="ojComponent: {component: 'ojButtonset', checked: drink}"
     aria-label="Choose only one beverage.  Use left and right arrow keys to navigate.">
    <!-- ko foreach: drinkRadios -->
        <label data-bind="attr: {for: id}, text: label"></label>
        <input type="radio" name="beverage"
               data-bind="value: id, attr: {id: id}"/>
    <!-- /ko -->
</div>

JET for jQuery UI developers

  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. JQUI Buttonset has an undocumented items option allowing apps to get and set the selector used by Buttonset to find all its buttonizable descendants. This option has been removed in JET, as we do not want this to be settable.
  3. The focus management functionality is new in JET.

Also, event names for all JET components are prefixed with "oj", instead of component-specific prefixes like "buttonset" or "menu". E.g. the JQUI buttonsetcreate 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 Buttonsets (the JQUI functionality) via: 
$( ".selector" ).on( "ojfoo", ":oj-buttonset", myFunc);

Initializer

.ojButtonset(options)

Creates a JET Buttonset. If called after the buttonset is already created, is equivalent to the "set many options" overload of option().
Parameters:
Name Type Argument Description
options Object <optional>
 a map of option-value pairs to set on the component
Source:
Examples

Initialize the buttonset with no options specified:

$( ".selector" ).ojButtonset();

Initialize the buttonset with some options and callbacks specified:

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

Initialize the buttonset via the JET ojComponent binding:

<div id="beverages" data-bind="ojComponent: { component: 'ojButtonset', 
                                              disabled: true, 
                                              create: setupButtonset }">

Options

#checked :string|Array.<string>|undefined

The checked option indicates which radio or checkboxes in the Buttonset are selected. It corresponds to the value attribute of those elements, which should always be set.

If this Buttonset consists of a single radio group, and no other buttons, then checked is a string equal to the value attribute of the checked radio. The option is null if and only if no radio is selected. Thus, an n-radio group has n+1 valid checked values: the n radio values, and null .

If this Buttonset consists of one or more checkboxes, and no other buttons, then checked is a possibly empty, non-null string array containing the value attributes of the checked checkboxes. This array has "set", not "list", semantics; i.e. order is neither important nor guaranteed. Thus, an n-checkbox set has 2^n valid checked values: the 2^n possible subsets of n checkboxes.

In all other cases, checked is null.

After create time, the checked state should be set via this API, not by setting the underlying DOM attribute.

The 2-way checked binding offered by the ojComponent binding should be used instead of Knockout's built-in checked binding, as the former sets the API, while the latter sets the underlying DOM attribute.

An optionChange event is fired whenever this option changes, whether due to user interaction or programmatic intervention. If the value is the same as the previous value (using order-independent "set" equality for checkboxes), no event will be fired.

Often there is no need to listen for this event, since the ojComponent checked binding, discussed above, will update the bound observable whenever the checked state changes.

Default Value:
  • If not initially set, is initialized to reflect the initial DOM state
Source:
Examples

Initialize a buttonset with the checked option specified:

// radio
$( ".selector" ).ojButtonset( { "checked": "tea" } );

// checkbox
$( ".selector" ).ojButtonset( { "checked": ["bold", "italic"] } );

Get or set the checked option, after initialization:

// getter
var display = $( ".selector" ).ojButtonset( "option", "checked" );

// radio setter
$( ".selector" ).ojButtonset( "option", "checked", "tea" );

// checkbox setter
$( ".selector" ).ojButtonset( "option", "checked", ["bold", "italic"] );

#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

If the disabled option is set to true at create time, then all its buttons will be disabled. If it is false at create time, then each button's disabled status will be set from the button's API and DOM in the same way as a standalone JET Button.

Setting the disabled option after creation will enable or disable all contained buttons. Enabling or disabling the individual buttons will not update the value of Buttonset's disabled option.

Default Value:
  • false
Source:
Examples

Initialize the buttonset with the disabled option specified:

$( ".selector" ).ojButtonset( { "disabled": true } );

Get or set the disabled option, after initialization:

// getter (does not reflect changes made directly to the buttons)
var disabled = $( ".selector" ).ojButtonset( "option", "disabled" );

// setter
$( ".selector" ).ojButtonset( "option", "disabled", true );

#focusManagement :string

The focusManagement option should be set to "none" when the Buttonset is placed in a JET Toolbar. This allows the Toolbar to manage the focus with no interference from the Buttonset, so that arrow keys move within the entire Toolbar, not just within the Buttonset.
Supported Values:
Name Type Description
"oneTabstop" string Focus management is enabled. The Buttonset is a single tabstop with arrow-key navigation.
"none" string Focus management is disabled, to avoid interfering with the focus management of a containing component.
Default Value:
  • "oneTabstop"
Source:
Examples

Initialize the buttonset with the focusManagement option specified:

$( ".selector" ).ojButtonset( { "focusManagement": "none" } );

Get or set the focusManagement option, after initialization:

// getter
var display = $( ".selector" ).ojButtonset( "option", "focusManagement" );

// setter
$( ".selector" ).ojButtonset( "option", "focusManagement", "none" );

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

Events

#create

Triggered when the buttonset is created.
Properties:
Name Type Description
event Event jQuery event object
ui Object Empty object included for consistency with other events
Source:
Examples

Initialize the buttonset with the create callback specified:

$( ".selector" ).ojButtonset({
    "create": function( event, ui ) {}
});

Bind an event listener to the ojcreate event:

$( ".selector" ).on( "ojcreate", 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, checked. Additional options may be supported in the future, so listeners should verify which option is changing before taking any action.

Often there is no need to listen for this event, since the 2-way checked binding offered by the ojComponent binding will update the bound observable whenever the checked state changes.

Properties:
Name Type Description
event Event jQuery event object
ui Object Parameters
Properties
Name Type Argument Description
option string the name of the option that is changing
previousValue string | Array.<string> <nullable>
 the previous value of the option. null iff the previous value was null.
value string | Array.<string> <nullable>
 the current value of the option. null iff the current value is null.
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:
Examples

Initialize the buttonset with the optionChange callback specified:

$( ".selector" ).ojButtonset({
    "optionChange": function( event, ui ) {}
});

Bind an event listener to the ojoptionchange event:

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

Methods

#destroy()

Removes the buttonset functionality completely, including focus management, and recursively destroy()s the contained buttons. This will return the element back to its pre-init state.

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 destroy method:

$( ".selector" ).ojButtonset( "destroy" );

#getNodeBySubId(locator) → {Element|null}

Return the subcomponent node represented by the documented locator attribute values.
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 component name - 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.
Inherited From:
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 buttonset, including the following:
  • Creates JET Buttons out of all contained DOM elements supported by JET Button that are not already Buttons, by calling .ojButton() on them.
  • Re-applies focus management / keyboard navigation.
  • Applies special styles to the first and last button of the buttonset (e.g. for rounded corners, depending on theming).
  • Rechecks the reading direction (LTR vs. RTL).

A refresh() is required in the following circumstances:

  • After buttons are added to or removed from the buttonset.
  • After a change to the disabled status of any of the buttons in the buttonset.
  • After the reading direction (LTR vs. RTL) changes.

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" ).ojButtonset( "refresh" );

#widget() → {jQuery}

Returns a jQuery object containing the buttonset element.

This method does not accept any arguments.

Source:
Returns:
the buttonset element
Type
jQuery
Example

Invoke the widget method:

var widget = $( ".selector" ).ojButtonset( "widget" );

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.