Class: ojButton

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

E54107-01

QuickNav

oj. ojButton extends oj.baseComponent

JET Button Component

Description: Themeable, WAI-ARIA-compliant push buttons and toggle buttons, with appropriate styles for hover, active, checked, and disabled.

There are two types of JET Buttons: push buttons and toggle buttons.

Push Buttons

Push buttons are ordinary buttons that do not stay pressed in when clicked. Push buttons are created from buttons, anchors, and inputs of type button, submit, and reset. Button elements are typically a good general-purpose choice.

Toggle Buttons

Toggle buttons are buttons that toggle between a selected state and an unselected state when clicked. Toggle buttons are created from radio buttons and checkboxes (inputs of type radio and checkbox).

For toggle buttons, the input must have a label, which must be a sibling of the input that precedes the input. The label's for attribute must refer to the input's id attribute.

A new wrapper element is created around the label and input, so that the component has a single root, while avoiding the accessibility problems caused by nesting the input inside the label.

The label-precedes-input requirement ensures compatibility with the JET ojComponent binding on the input element, which expects all relevant DOM elements, including label, to be already available with all their attributes resolved.

The wrapper and label are styled to appear as the button, while the underlying input is updated on click.

Note that a given radio button must not be both checked and disabled, unless all radios in the group are disabled, since this removes the entire radio group from the tab order in mainstream browsers. This issue applies to native radios and is not unique to JET.

Buttonsets and Toolbars

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. See the Buttonset API doc for more information.

Also, buttons and buttonsets can be placed in a JET Toolbar. Like Buttonset, Toolbar is themable and provides WAI-ARIA-compliant focus management. See the Toolbar API doc for more information.

Keyboard interaction

Per WAI-ARIA requirements for role="button", all flavors of JET Button support invocation via both Enter and Spacebar, even when the underlying DOM element does not.

Event Handling

It's most reliable to register click handlers directly on the button, rather than on an ancestor. For example, if any of the button's DOM is swapped out in a click handler (e.g. alternating the text and icon between "Play" and "Pause"), the bubbling will stop if the click target was part of the content that was removed in the swap.

In lieu of a shared listener on an ancestor, syntax like $( "#ancestor :oj-button" ).click( myFunc ); can be used to set a handler on many buttons at once.

Pseudo-selectors

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

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

Setting Component State

In JET, when setting component state after create time, the correct approach depends on whether the component has a JS API for that state.

State with a JS API, such as Button's disabled state, checked state, and label, should be set after creation via that API (which in those examples is option()), not by directly manipulating the DOM after creation. This can be done by calling that JS API directly, or by binding a component option like disabled to an observable using the ojComponent binding.

Built-in KO bindings, like KO's disable binding, should not be used in this case, since that is tatamount to updating the DOM directly. The component option should be bound instead, via JET's ojComponent binding.

If a button's checked state needs to be set programmatically, then it should be wrapped in a Buttonset so that its checked option can be used.

State with no JS API should be set by manipulating the DOM directly in an allowable way, and then calling refresh() on the affected component(s). E.g. the reading direction (LTR / RTL) is changed by by setting the "dir" attribute on the <html> node and calling refresh().

When using a built-in Knockout binding (as opposed to the ojComponent binding), keep in mind that those bindings do not execute the necessary refresh() call after updating the DOM. Updates that flow from the component to the observable, as a result of user interaction, are not problematic. But updates in the other direction, that programmatically update the DOM because the observable changed, will not be picked up until the next refresh().

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 Button has a Boolean text option indicating whether to hide the label when icons are present. In JET, we prefer to avoid Booleans for future flexibility, so JET Button instead has an expandable display option accepting the values "all" and "icons".
  3. In JQUI Button, the icons option accepts keys named "primary" and "secondary". For clarity, these options have been renamed in JET Button to "start" and "end", our standard directionality-neutral terms for (in LTR) "left" and "right".

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

Initializer

.ojButton(options)

Creates a JET Button. If called after the button is already created, it 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 button with no options specified:

$( ".selector" ).ojButton();

Initialize the button with some options and callbacks specified:

$( ".selector" ).ojButton( { "label": "Copy", "create": function( event, ui ) {} } );

Initialize a push button via the JET ojComponent binding:

<button id="paste" data-bind="ojComponent: { component: 'ojButton', 
                                             label: 'Paste', 
                                             create: setupButton }">

Initialize a toggle button via the JET ojComponent binding:

<label for="check">Toggle</label>
<input type="checkbox" id="check" data-bind="ojComponent: {component: 'ojButton'}"/>

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

Disables the button if set to true.

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

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

Default Value:
  • false
Source:
Examples

Initialize the button with the disabled option specified:

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

Get or set the disabled option, after initialization:

// getter
var disabled = $( ".selector" ).ojButton( "option", "disabled" );

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

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

The display option will be ignored if no icons are specified via the icons option.

Supported Values:
Name Type Description
"all" string Display both the label and icons.
"icons" string Display only the icons.
Default Value:
  • "all"
Source:
Examples

Initialize the button with the display option specified:

$( ".selector" ).ojButton( { "display": "icons" } );

Get or set the display option, after initialization:

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

// setter
$( ".selector" ).ojButton( "option", "display", "icons" );

#icons :Object

Icons to display in the button. Support is as follows:
  • Any combination of start and end icons can be specified, with or without the label (see display option).
  • Icons are supported for push buttons created from buttons and anchors, and for toggle buttons (radios and checkboxes).
  • Icons are not supported for push buttons created from inputs of type button, submit, and reset.

The start icon is displayed before the label text (on the left in LTR), and the end icon is displayed after the label (on the right in LTR). In RTL, the positions are reversed.

The value for the start and end properties should be one or more style class names (as seen in the examples) or null (the default).

Default Value:
  • { start: null, end: null }
Source:
Examples

Initialize the button, specifying only one icon:

$( ".selector" ).ojButton({ "icons": { start:'demo-icon-sprite demo-icon-locked' } });

Get or set the icons option, after initialization:

// getter
var icons = $( ".selector" ).ojButton( "option", "icons" );

// setter, specifying both icons:
$( ".selector" ).ojButton( "option", "icons", { start: 'demo-icon-sprite demo-icon-gear', 
                                                end: 'demo-icon-sprite demo-icon-triangle-1-s'} );

#label :string

Text to show in the button.

When not specified (null) at create time, the element's HTML content is used, or its value attribute if the element is an input element of type button, submit, or reset, or the HTML content of the associated label element if the element is an input of type radio or checkbox.

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

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

Default Value:
  • null
Source:
Examples

Initialize the button with the label option specified:

$( ".selector" ).ojButton( { "label": "custom label" } );

Get or set the label option, after initialization:

// getter
var label = $( ".selector" ).ojButton( "option", "label" );

// setter
$( ".selector" ).ojButton( "option", "label", "custom label" );
JQ selector identifying the JET Menu that the button should launch. If specified, the button is a WAI-ARIA-compliant menu button.

By default, menu buttons have a downward pointing "dropdown" arrow for their end icon. See the icons option for details.

Menu button functionality is supported for Buttons based on button or anchor tags. (Buttons based on input tags either do not support the dropdown icon, or do not make sense for use as a menu button, or both.)

The JET Menu should be initialized before the JET Button that launches it.

Default Value:
  • null
Source:
Examples

Initialize a menu button:

$( ".selector" ).ojButton({ "menu": "#myMenu" });

Get or set the menu option, after initialization:

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

// setter
$( ".selector" ).ojButton( "option", "menu", ".my-marker-class" );

#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 button 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 button with the create callback specified:

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

Bind an event listener to the ojcreate event:

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

Methods

#destroy()

Removes the button functionality completely. 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" ).ojButton( "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 button. JET components require a refresh() after a supported DOM change is made that affects the component, of which the component would otherwise be unaware.

This method calls baseComponent.refresh(), but doesn't currently do anything Button-specific. Note that anything having a JS API, such as the Button's label, disabled state, and checked state, must be set via the API, not by mutating the DOM and calling refresh(). (For the checked state, see Buttonset's checked option.)

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

#widget() → {jQuery}

Returns a jQuery object containing the element visually representing the button. For checkboxes and radios, this is the label, not the input.

This method does not accept any arguments.

Source:
Returns:
the button
Type
jQuery
Example

Invoke the widget method:

var widget = $( ".selector" ).ojButton( "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.