Class: ojRadioset

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

E54107-01

QuickNav

oj. ojRadioset extends oj.editableValue

The JET Radioset component (ojRadioset) enhances a group of input type="radio" elements. It manages the selected value of the group and it adds required validation. It also adds and removes the correct oj-* styles to the dom elements so it has the JET styling and is themable.

To use an ojRadioset, group all the inputs and their labels within a container dom element, e.g., div. For accessibility, set aria-labelledby on this container dom element. Also set each input's id attribute, and refer to that in the input's label's for attribute. Then create the ojRadioset on this container dom element.

Radioset is used by selecting a container element which contains the radio input elements and calling ojRadioset(). You can enable and disable a radio set, which will enable and disable all contained radios.

Keyboard interaction

The radioset does not add any extra keyboard navigation to the input radios. The keyboard interaction comes from the native browser.

Accessibility

JET Radioset takes care of setting role="radiogroup" on the radioset element.

As shown in the online demos, the application is responsible for applying aria-labelledby to point to the main label element for the group of radios.

JET for jQuery UI developers

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.

Initializer

.ojRadioset(options)

Creates a JET Radioset. For JET Radioset, if the DOM changes (for example, you add/remove a radio), you should refresh().
Parameters:
Name Type Argument Description
options Object <optional>
a map of option-value pairs to set on the component
Source:
Examples

Initialize the radioset with no options specified:

$(".selector").ojRadioset();

Initialize the radioset with some options and callbacks specified:

$( ".selector" ).ojRadioset( { "value": "copy", "valuechange": 
function( event, ui ) {alert("valuechanged from " + ui.previousValue + " to " + ui.value);} } );             

Initialize component using widget API

<label id="grouplabel">Greetings</label>
<div id="radioset" aria-labelledby="grouplabel">
  <input id="helloid" value="hello" type="radio" name="greetings"/>
  <label for="helloid"/>Hello</label>
  <input id="bonjourid" value="bonjour" type="radio" name="greetings"/>
  <label for="bonjourid"/>Bonjour</label>
  <input id="ciaoid" value="ciao" type="radio" name="greetings"/>
  <label for="ciaoid"/>Ciao</label>
<div>

// set the value to "ciao". (The 'ciao' radio will be checked) $("#radioset").ojRadioset({'option', 'value', 'ciao'});

Initialize a radioset via the JET ojComponent binding:

<label id="grouplabel">Time</label>
<div id="radioset" data-bind="ojComponent: {component: 'ojRadioset', value: 'night'} 
  aria-labelledby="grouplabel" >
  <input id="morningid" value="morning" type="radio" name="time"/>
  <label for="morningid"/>Morning</label>
  <input id="nightid" value="night" type="radio" name="time"/>
  <label for="nightid"/>Night</label>
<div>

Using knockout, value bind to observable:

<label id="grouplabel">Time</label>
<div id="radioset" data-bind="ojComponent: {component: 'ojRadioset', 
value: currentTime} 
  aria-labelledby="grouplabel" >
  <input id="morningid" value="morning" type="radio" name="time"/>
  <label for="morningid"/>Morning</label>
  <input id="nightid" value="night" type="radio" name="time"/>
  <label for="nightid"/>Night</label>
<div>

// in the model, make the currentTime variable a knockout observable. // The model and the component's value option will stay in sync. Change the // component's value option and the model will change. Change the model, // and the component's value option will change. Click on a radio, and both // will change. self.currentTime = ko.observable("night");

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

#converter :string|Object|undefined

a converter instance, where each instance duck types oj.Converter, or an converter object literal containing the following name value pair.
  • type: the string conveter type registered with the ConverterFactory. Supported types are 'number' and 'datetime'
  • options: an optional Object literal of options that the converter expects.
If the converter option changes after the component has been initialized then
- if the component is valid, the value option is formatted using the new converter instance and the display updated with the new value.
- otoh, if the component is invalid when the converter option changed, it is the responsibility of the page author to clear messages on the component and reset the value if needed.
Inherited From:
Source:
Examples

Initialize the component with converter object literal:

$(".selector").ojInputText({
  value: 25000,
  converter: {
    type: 'number', 
    options : {
      style: 'currency', 
      currency: 'USD', 
      maximumFractionDigits: 0
    }
  }
});

Initialize the component with a number converter instance:

// Initialize converter instance using currency options
var options = {style: 'currency', 'currency': 'USD', maximumFractionDigits: 0};
var numberConverterFactory = oj.Validation.converterFactory("number");
var salaryConverter = numberConverterFactory.createConverter(options);
// set converter instance using converter option $(".selector").ojInputText({ value: 25000, converter: salaryConverter });

#disabled :boolean|undefined

whether the component is disabled.

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. The element's disabled property is used as its initial value if it exists, when the option is not explicitly set. When neither is set, disabled defaults to false.
Inherited From:
Source:
Example

Initialize component with disabled option:

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

#help :Object.<string, string>

The help information that goes on the label. When help is set on the input component, then help information is added to the input's label. The help options are:
  • definition - this is the help definition text. It is what shows up when the user hovers over the label or the help icon.
  • source - this is the help source url. If present, a help icon will render next to the label and the anchor's target is this source.
Default Value:
  • { "definition":"some help definition, "source":"some external url" }
Inherited From:
Source:
Examples

Initialize the input with the help definition and external url information:

$( ".selector" ).ojRadioset({ "help": {"definition":"some help definition, "source":"some external url" } });

Set the help option, after initialization:

// setter
$( ".selector" ).ojRadioset( "option", "help", {"definition":"fill out the name", "source":"http:\\www.oracle.com" } );

#messages :Array|undefined

an array of messages for this component, each instance of type oj.Message or an object that duck types it.
Default Value:
  • initializes to an empty array when no option is set.
Inherited From:
Source:
Examples

Get the current set of messages for the component:

var messages = $(".selector").ojInputText("option", "messages");

Clear all messages set on the component:

$(".selector").ojInputText("option", "messages", []);

Add a message (of default error severity) to the component using the messages option:

var msgs = [];
msgs.push({'summary': 'Error Summary', 'detail': 'Error Detail'}); 
$(".selector").ojInputText("option", "messages", msgs);

Set a oj.Message instance to the component:

var message = new oj.Message("summary text", "detail text");
var messagesArr = [message];
$(".selector").ojInputText("option", "messages", messagesArr);

#messagingDisplayOptions :Object|undefined

an Object literal containing the following property-value pairs, that allows a widget to specify how it wants various 'messaging artifacts' to be displayed in relation to itself.
Accepted values for the key is a string type of the messaging artifact and they include 'messages', 'converterHint', 'validatorHint', 'title'.
The value is either an array of display options or a string display option. When an array of display options is specified the first display option is used first and then the second as fallback and so on. NOTE: In the future we plan to support additional display options like 'inline'.
Properties:
Name Type Argument Description
converterHint string <optional>
supported values are 'placeholder', 'notewindow', 'none'. E.g. {'converterHint': ['placeholder', 'notewindow']}
validatorHint string <optional>
supported values are 'notewindow', 'none'. E.g. {'validatorHint': ['notewindow']}
messages string <optional>
supported values are 'notewindow', 'none'. E.g. {'messages': 'notewindow'}
title string <optional>
supported values are 'notewindow', 'none'. E.g. {'title': 'notewindow'}
Default Value:
  • { 'messages': ['notewindow'], 'converterHint': ['placeholder', 'notewindow'], 'validatorHint': ['notewindow'], 'title': ['notewindow'] }
Inherited From:
Source:
Example

Initialize component and override default for converterHint using messagingDisplayOptions:

// Only messages will get shown in the notewindow associated to this component
$(".selector").ojInputText("option", "messagingDisplayOptions", {
  'converterHint': ['notewindow'] // the default is ['placeholder', 'notewindow']
});

#placeholder :string|undefined

This option allows setting HTML5's placeholder attribute. Though it is possible to set placeholder attribute on the element itself, the component will only read the value during creation time; meaning any subsequent changes to the element's placeholder attribute will not be picked up.
Default Value:
  • when the option is not set, the element's placeholder attribute is used if it exists. If the attribute is not set then the default can be a converter hint. See messagingDisplayOptions for details.
Inherited From:
Source:
Examples

Initialize the component with the placeholder option:

<input id="userId" data-bind="ojComponent: {component: 'ojInputText', placeholder: 'User Name'}" />

Initialize placeholder option from html attribute:

<input id="userId" data-bind="ojComponent: {component: 'ojInputText'}" placeholder="User Name" />

// reading the placeholder option will return "User Name"
$(".selector").ojInputText("option", "placeholder");

#required :string|undefined

whether the component is required. Allowed values for required are 'required' and 'optional', 'optional' being the default.
When required option is set, the input's label will render a required icon.
When required option is set, a required validator - (@link oj.RequiredValidator) - is implicitly used. If an explicit required validator is set using the validators option then that gets used instead.
Default Value:
  • when the option is not set, the element's required property is used as its initial value if it exists.
Inherited From:
Source:
Examples

Initialize the component with the required option:

$(".selector").ojInputNumber({required: 'required'});

Initialize required otpion from html attribute 'required':

<input type="text" value= "foobar" required/>
// reading the required option will return "required" $(".selector").ojInputNumber("option", "required");

Using required option and setting an explicit required validator:

<input type="text" value="foobar" required data-bind="ojComponent: {
  component: 'ojInputText', 
  value: password, 
  validators: [{type: 'required', options : {
                               messageSummary: '\'{label}\' Required', 
                               messageDetail: 'A value is required for this field'}}]}"/>

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

#title :string|undefined

represents advisory information for the component, such as would be appropriate for a tooltip.
Default Value:
  • when the option is not set, the element's title attribute is used as its initial value if it exists.
Inherited From:
Source:
Examples

Initialize the component with the title option:

<input id="username" type="text" data-bind="
   ojComponent: {component: 'ojInputText', title : 'enter at least 3 alphanumeric characters', 
                 pattern: '[a-zA-Z0-9]{3,}', value: ''}"/>

Initialize title option from html attribute 'title':

<input id="username" type="text" value= "foobar" title="enter at least 3 alphanumeric characters" 
          pattern="[a-zA-Z0-9]{3,}"/>
$("#username").ojInputText({}); // reading the title option will return "enter at least 3 alphanumeric characters" $("#username").ojInputText("option", "title");

#validators :Array|undefined

an array of validator instances, where each instance duck types oj.Validator, or an array of validator object literals where each object contains the following name value pairs.
  • type: a string validator type that is registered with the oj.ValidatorFactory. An instance is created using the factory method on @link oj.ValidatorFactory.
  • options: an optional Object literal of options that the validator expects.
After the component has been initialized with validators, changing the validators on the component can present issues that need to addressed appropriately
- if the component is valid, the current value that passed validations before may now start failing. E.g, if value was below a certain max value but a new validator lowered the max value, invalidating the current value. In such cases the page author has the option of calling the validate() method to re-run validators against the current value. In some cases it may be necessary to re-initialize the component.
- if the component was invalid when the validators changed, again it may be necessary to for the page author to clear messages on the component, or in some cases re-initialize the component might be necessary.
Inherited From:
Source:
Examples

Initialize the component with validator object literal:

$(".selector").ojInputNumber({
  validators: [{
    type: 'numberRange', 
    options : {
      hint: {hintMinimum: 'Enter a value greater than '{min}'}, 
      min: 100
    }
  }],
});
NOTE: oj.Validation.validatorFactory('numberRange') returns the validator factory that is used 
to instantiate a numberRange validator.

Initialize the component with multiple validator instances:

var validator1 = new MyCustomValidator({'foo': 'A'}); 
var validator2 = new MyCustomValidator({'foo': 'B'});
$(".selector").ojInputNumber({
  value: 10, 
  validators: [validator1, validator2]
});

#value :Object|undefined

The value of the editable component.
Default Value:
  • When the option is not set, the element's value property is used as its initial value if it exists. The type of value is as defined by the component that extends this class. Refer to specific components for defaults.
Inherited From:
Source:
Examples

Initialize the component with the value option specified:

$(".selector").ojInputNumber({'value': 10});

Get or set the value option, after initialization:

// Getter: returns 10
$(".selector").ojInputNumber("option", "value");
// Setter: sets 20
$(".selector").ojInputNumber("option", "value", 20);

Events

#optionChange

Triggered when the following component options change.
  • messages: a component's validity changes when its messages changes. For example -
    • when it goes from valid with no messages, to invalid with messages (of severity fatal or error), or to valid with messages (of severity warning, info or confirmation).
    • when it goes from valid with messages, to valid with a new set of messages, or to valid with no messages, or to invalid with messages
    • when it goes from invalid with messages, to invalid with new set of messages, or to valid with no messages, or to valid with messages (of severity warning or lower).
  • value: when the component's value changes.

The event payload has the following properties -

Properties:
Name Type Description
event Event jQuery event object
data Object event payload
Properties
Name Type Description
option string the name of the option that changed, i.e. "messages" or "value"
previousValue Object an Object holding the previous value of the option
value Object an Object holding the current value of the option
optionMetadata Object an Object literal that provides metadata for the option.
Inherited From:
Source:
Examples

Initialize the ojInputText component with the optionChange callback to be notified of changes to the component's validity

$(".selector").ojInputText({
  'optionChange': function (event, data) {} 
});

Bind an event listener to the ojoptionchange event

$(".selector").on({
  'ojoptionchange': function (event, data) {
      window.console.log("option changing is: " + data['option']);
  };
});

Methods

#getNodeBySubId(locator) → {Element|null}

Return the subcomponent node represented by the documented locator attribute values. Test authors should target spinner sub elements using the following names:
  • oj-radioset-inputs: the radioset's input elements
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

#isValid() → {boolean}

whether the component is currently valid.
Inherited From:
Source:
Returns:
Type
boolean
Example

Check whether the component is valid:

var value = $(".selector").ojInputText("isValid");

option(key, value)

Reacts to changes to the 'value' or 'messages' option by triggering a 'optionChange' event if the value changes from its previous value. Refer to the optionChange event for details.
Parameters:
Name Type Argument Description
key String | Object | string <optional>
a single string representing a key or an object representing a group of options
value Object <optional>
of the key
Inherited From:
Source:
Fires:
Returns:
When called via the public jQuery syntax, this method returns the object on which it was called, to facilitate method chaining.

#refresh()

Refreshes the radioset

A refresh() is required when a radioset is programatically changed, like in the following circumstances:

  • After radios are added or removed or modified (without using ojRadioset) in the DOM.
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" ).ojRadioset( "refresh" );

#validate(requiredOnly)

A convenience method to validate the option value after it is set programmatically using the option setter.
When the value property is set, it's expected to be of the correct type as defined by the component. To run the value through the validators, this method can be called. When there are no validators setup for the component this method is a no-op and returns true. When there is at least one validator the first one that fails, updates the component validity, adds messages and triggers the optionChange event.
Callers should explicitly clear messages when calling this method.
Parameters:
Name Type Description
requiredOnly boolean If true only runs the required-ness check.
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.
Example

Validate the value option.

// set value
$(.selector).ojInputDate('option', 'value', new Date());
// clear current messages on component
$(.selector).ojInputText('option', 'messages', []);
// validate value. validation errors are displayed if any based on the messagingDisplayOptions.
$(.selector).ojInputText('validate');

#widget() → {jQuery}

Returns a jQuery object containing the element visually representing the radioset.

This method does not accept any arguments.

Source:
Returns:
the radio
Type
jQuery

Non-public Methods

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

<protected, static> _GetContentElement()

Returns a jquery object of the elements representing the content nodes (input type=radio). This is used in EditableValue to add aria-describedby to the input when there is a help icon, to add aria-required and aria-invalid
Source:
Returns:
When called via the public jQuery syntax, this method returns the object on which it was called, to facilitate method chaining.

<protected, static> _GetDefaultStyleClass() → {string}

Returns the default styleclass for the component. Currently this is used to pass to the _ojLabel component, which will append -label and add the style class onto the label. This way we can style the label specific to the input component. For example, for inline labels, the radioset/checkboxset components need to have margin-top:0, whereas all the other inputs need it to be .5em. So we'll have a special margin-top style for .oj-label-inline.oj-radioset-label All input components must override
Source:
Returns:
Type
string

<protected, static> _GetDisplayValue(value)

Returns the display value that is ready to be passed to the converter.
Parameters:
Name Type Description
value Object the stored value if available that needs to be formatted for display
Source:
Returns:
When called via the public jQuery syntax, this method returns the object on which it was called, to facilitate method chaining.

<protected, static> _GetElementValue()

Returns the element's value. Normally, this is a call to this.element.val(), but in the case of ojRadioset, the element's value is really the value of the checked radio in the set.
Source:
Returns:
When called via the public jQuery syntax, this method returns the object on which it was called, to facilitate method chaining.

<protected, static> _HandleChangeEvent(event)

Parameters:
Name Type Description
event Event DOM event
Source:
Returns:
When called via the public jQuery syntax, this method returns the object on which it was called, to facilitate method chaining.

<protected, static> _SetDisplayValue(displayValue)

Called when the display value on the element needs to be updated as a result of a value change. ojRadioset stores a String value, and this value matches the value of the currently checked radio. So, if we need to set the display value, what this means is we need to 'check' the radio whose value matches the displayValue.
Parameters:
Name Type Description
displayValue String of the new string to be displayed
Source:
Returns:
When called via the public jQuery syntax, this method returns the object on which it was called, to facilitate method chaining.

<protected> #_AfterCreate()

The value option alone is initialized here since it requires the component to be fully created. Calling this.options.value before this method does not guarantee the correct value to be returned.
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> #_CanSetValue()

Whether the a value can be set on the component. If the component is disabled then setting value on component is a no-op.
Inherited From:
Source:
See:
Returns:
When called via the public jQuery syntax, this method returns the object on which it was called, to facilitate method chaining.

<protected> #_ComponentCreate()

Initializes options defined by this base class.
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> #_destroy()

Detaches the widget from the element and restores element exactly like it was before the widget was attached.
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> #_GetAllValidators() → {Array}

Returns an array of all validators built by merging the validators option set on the component and the default validators setup by the component.
This does not include the default required validator. Components can override to add to this array of validators.
Inherited From:
Source:
Returns:
of validators
Type
Array

<protected> #_GetContentElement() → {Object}

Returns a jquery object of the element representing the content node. This could be a jQuery object of the element the widget was invoked on - typically this is an input or select or textarea element for which a value can be set.
Inherited From:
Source:
Returns:
the jquery element that represents the editable content. E.g., an input
Type
Object

<protected> #_GetConverter() → {Object}

Returns the normalized converter instance.
Inherited From:
Source:
Returns:
a converter instance or null
Type
Object

<protected> #_GetDefaultStyleClass() → {string}

Returns the default styleclass for the component. Currently this is used to pass to the _ojLabel component, which will append -label and add the style class onto the label. This way we can style the label specific to the input component. For example, for inline labels, the radioset/checkboxset components need to have margin-top:0, whereas all the other inputs need it to be .5em. So we'll have a special margin-top style for .oj-label-inline.oj-radioset-label All input components must override
Inherited From:
Source:
Returns:
Type
string

<protected> #_GetDefaultValidators() → {Object}

Returns an array of default validators used by component. The list of default validators are for the internal use of the component and are not a part of this.options.validators. E.g., if the pattern attribute or option is set, a RegExpValidator instance is automatically created and added to this list. RequiredValidtor is tracked separately from the default validators.
Inherited From:
Source:
Returns:
a map of string name to the validator instance.
Type
Object

<protected> #_GetDisplayValue(value) → {string}

Returns the display value that is ready to be passed to the converter.
Parameters:
Name Type Description
value Object the stored value if available that needs to be formatted for display
Inherited From:
Source:
Returns:
usually a string display value
Type
string

<protected> #_GetElementValue()

Returns the element's value. Normally, this is a call to this.element.val(), but for some components, it could be something else. E.g., for ojRadioset the element's value is really the value of the selected radio in the set.
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> #_GetLabelElement() → {Object}

Returns a jquery object of the element representing the primary label node for the input component. First we look for the aria-labelledby attribute on the input. If that's not found, we look for the label with 'for' attribute pointing to input. If that's not found, we walk up the dom looking for aria-labelledby.
Inherited From:
Source:
Returns:
the jquery element that represents the input component's label. return null if it can't find anything.
Type
Object

<protected> #_GetMessagingLauncherElement() → {Object}

Returns a jquery object of the element that triggers messaging behavior. The trigger element is usually an input or select or textarea element for which a value can be set/retrieved and validated.
Inherited From:
Source:
Returns:
jquery object
Type
Object

<protected> #_GetMessagingLauncherElement() → {Object}

Returns a jquery object of the element that triggers messaging behavior. The trigger element is usually an input or select or textarea element for which a value can be set/retrieved and validated.
Inherited From:
Source:
Returns:
jquery object
Type
Object

<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> #_HandleChangeEvent(event)

Convenience handler for the DOM 'change' event. Subclasses are expected to wire up event handlers for DOM events that they wish to handle.
The implementation retrieves the display value for the component by calling _GetDisplayValue() and calls _SetValue(), with full validation.
Parameters:
Name Type Description
event Event DOM event
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> #_InitOptions()

Overridden to set the default value for options.value when it's null or undefined.
Source:
Returns:
When called via the public jQuery syntax, this method returns the object on which it was called, to facilitate method chaining.

<protected> #_IsRequired() → {boolean}

Whether the component is required.
Inherited From:
Source:
Returns:
true if required; false
Type
boolean

<protected> #_Refresh(name, value, fullRefresh)

Called in response to a change in the options set for this component, this method refreshes the component display value. Subclasses can override to provide custom refresh behavior.
Parameters:
Name Type Argument Description
name String <optional>
the name of the option that was changed
value Object <optional>
the current value of the option
fullRefresh boolean <optional>
false is the default; true means always refresh component display 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.

<protected> #_RefreshAriaRequired(value)

Called when a aria-required attribute needs to be set or removed. Most inputs/selects need aria-required on the input element (aka 'content') But it is not legal to have aria-required on radio/checkboxes. Subclasses can override to put aria-required where they want.
Parameters:
Name Type Argument Description
value Object <optional>
the current value of the required option
Source:
Returns:
When called via the public jQuery syntax, this method returns the object on which it was called, to facilitate method chaining.

<protected> #_ResetAllValidators()

EditableValue caches the validators to be run within this.__allValidators variable. This is great; however when the default validators need to be reset [i.e. min + max changing] then the cached this.__allValidators needs to be cleared out. This method also updates the messaging strategies as hints associated with validators could have changed.
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> #_SetDisplayValue(displayValue)

Called when the display value on the element needs to be updated. This method updates the (content) element value. Widgets can override this method to update the element appropriately.
Parameters:
Name Type Description
displayValue String of the new string to be displayed
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> #_setOption(name, value)

Called (by the widget factory) when the option changes, this method responds to the change by refreshing the component if needed. This method is not called for the options passed in during the creation of the widget.
Parameters:
Name Type Description
name string of the option
value Object | string
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> #_SetPlaceholder(value)

Sets the placeholder text on the content element by default. It sets the placeholder attribute on the element. Component subclasses can override this method to control where placeholder text gets set.
Parameters:
Name Type Description
value string
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.

<protected> #_SetValue(newValue, event, options) → {boolean}

Sets the value on the component after clearing existing messages on the component. This method is typically called when a component needs to write a user value into the component.
Parameters:
Name Type Argument Description
newValue Object the value to be set.
event Object <optional>
an optional event if this was a result of ui interaction. For user initiated actions that trigger a DOM event, passing this event is required. E.g., if user action causes a 'blur' event.
When _SetValue is called as a result of a programmatic update, such as calling a method on a component, then the event can be undefined. E.g., ojInputNumber.stepUp()
options {validationMode:number} <optional>
an Object literal that callers pass in to determine how validation gets run. Keys and values to pass in options are as follows: 'validationMode': {number} Accepted values (defined in _VALIDATION_MODE) are -
  • FULL - the default and runs both the converter and all validators.
  • VALIDATORS_ONLY - runs all validators including the required validator is run.
  • REQUIRED_VALIDATOR_ONLY - runs just the required validator.
  • NONE - runs no validation and write the value to the options.
NOTE: All options expect NONE will clear current messages.
  • If validation is to be run, then the newValue is compared with the last element value. If it's the same then validation is skipped. If not the same validation continues.
  • When there is a validation error, value option not set and the method returns false.
  • If all validations pass, and the new parsed value is the same as the options.value then the value option is not written, the component display is refreshed and the method returns true. But if the new value is different then it's written to the options and the component refreshed
Inherited From:
Source:
Returns:
false if value was not set due to validation error.
Type
boolean

<protected> #_TriggerOptionChange(option, previousValue, originalEvent)

Triggers a 'optionChange' event on the component. The payload is the previous and current values for the option that changed. Currently supported options that trigger this event are value and messages.
Parameters:
Name Type Argument Description
option string name of the option that changed
previousValue string | number | Object an array of the previous
originalEvent Event <optional>
the original dom event that triggered the validation. If this is set then writeback happens.
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> #_ValueEquals(value1, value2) → {boolean}

Compares 2 values for equality and returns true if they are equal; false otherwise. Calls oj.Object.innerEquals() which works for most Javascript data types.
Parameters:
Name Type Description
value1 Object | string | undefined first value
value2 Object | string | undefined another value
Inherited From:
Source:
Returns:
Type
boolean