Element: <oj-slider>

Oracle® JavaScript Extension Toolkit (JET)
4.2.0

E91398-01

QuickNav

Attributes

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

Version:
  • 4.2.0
Since:
  • 0.7

JET Custom Elements

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

JET Slider Component

Description: The oj-slider component enhances an HTML input element into an interactive slider.

The numerical value attribute determines the current value of the slider, and thus affects the position of the slider thumb. The value should be between the min and max attribute values.

The step attribute of the slider specifies the interval between thumb stops. For example, if min is set to 0 and max is set to 10, a step value of 2 would allow the thumb to be positioned at 0, 2, 4, 6, 8, and 10.

The orientation attribute defaults to "horizontal". Set orientation to "vertical" for a vertical slider (one where the thumb travels along the vertical axis).

The type attribute is used to effect the rendered style of the slider. The type attribute defaults to "fromMin", which will style the value bar from the minimum value to the slider thumb. The type attribute to either "single" or "fromMax" - this will alter the rendered style of the slider's bar value.

Set the disabled attribute true to display a slider that displays a value but does not allow interaction.

Use style attributes on the oj-slider element to set a horizontal slider's width or a vertical slider's height.

Note that the range value for the type attribute is not part of the initial (4.0) release of the custom element slider. In addition, the raw-value attribute is also not part of the initial release of the custom element slider. We anticipate that these features will be included in the next dot release (4.1).

Touch End User Information

Target Gesture Action
Slider Bar Tap Reposition the thumb.
Slider Thumb Swipe Reposition the thumb.

Keyboard End User Information

The JET slider supports keyboard actions for thumb movement:

Target Key Use
Slider Tab Places focus on the slider component. If hints, title or messages exist in a notewindow, pop up the notewindow.
Slider RightArrow Scrolls right on a horizontal slider, scrolls up on a vertical slider.
Slider LeftArrow Scrolls left on a horizontal slider, scrolls down on a vertical slider.
Slider UpArrow Scrolls right on a horizontal slider, scrolls up on a vertical slider.
Slider DownArrow Scrolls left on a horizontal slider, scrolls down on a vertical slider.
Slider PageUp Scrolls one page right on a horizontal slider, scrolls one page up on a vertical slider.
A page is defined as 20% of the range of the slider.
Slider PageDown Scrolls one page left on a horizontal slider, scrolls one page down on a vertical slider.
Slider End Scrolls to the right end on a horizontal slider, scrolls to the bottom on a vertical slider.
Slider Home Scrolls to the left end on a horizontal slider, scrolls to the top on a vertical slider.

Accessibility

The slider component is accessible - it sets and maintains the appropriate aria- attributes, including aria-valuenow, aria-valuemax, aria-valuemin and aria-orientation.

Label and Slider

It is up to the application developer to associate the oj-label to the oj-slider element. For accessibility, you should associate a oj-label element with the oj-slider element by putting an id on the oj-slider element, and then setting the for attribute on the oj-label to be the slider element's id.

In addition, the slider thumb element can be accessed programmatically. This approach may be necessary to ensure accessibility conformance. For example, if the slider controls another element that is in a remote area of the page, then the aria-controls attribute for the slider thumb should be set.

Consider an example where you may need to set additional attributes for accessibility reasons. Suppose there is another component that is in a remote area of the page that controlled by the slider. Assume that the id of the remote element is "idOfRemoteElement". Below we show how to access the thumb element in order to set the aria-controls attribute of the thumb to point to the the id ("idOfRemoteElement") of the remote html element:


    var thumb0 = myComponent.querySelectorAll('.oj-slider-thumb')[0];
    thumb0.setAttribute(aria-controls, "idOfRemoteElement");

See also the oj-focus-highlight discussion.

Styling

Several CSS classes are defined to implement the slider's style. The key classes are the following:

Class Description
oj-slider Top level slider class.
oj-slider-thumb Styles the slider thumb.
oj-slider-bar Styles the slider bar. The slider bar spans the full width of a horizontal slider.
oj-slider-bar-value Styles the slider bar value. The slider bar value is the colored (blue by default) part of the slider bar.
oj-slider-horizontal This class is present when the slider is oriented horizontally.
oj-slider-vertical This class is present when the slider is oriented vertically.
oj-focus-highlight Under normal circumstances this class is applied automatically. It is documented here for the rare cases that an app developer needs per-instance control.

The oj-focus-highlight class applies focus styling that may not be desirable when the focus results from pointer interaction (touch or mouse), but which is needed for accessibility when the focus occurs by a non-pointer mechanism, for example keyboard or initial page load.

The application-level behavior for this component is controlled in the theme by the $focusHighlightPolicy SASS variable; however, note that this same variable controls the focus highlight policy of many components and patterns. The values for the variable are:

  • nonPointer: oj-focus-highlight is applied only when focus is not the result of pointer interaction. Most themes default to this value.
  • all: oj-focus-highlight is applied regardless of the focus mechanism.
  • none: oj-focus-highlight is never applied. This behavior is not accessible, and is intended for use when the application wishes to use its own event listener to precisely control when the class is applied (see below). The application must ensure the accessibility of the result.

To change the behavior on a per-instance basis, the application can set the SASS variable as desired and then use event listeners to toggle this class as needed.

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

Examples

Declare the oj-slider component with no attributes specified:

<oj-slider></oj-slider>

Initialize the slider with a few attributes:

<oj-slider value=10 max=100 min=0 step=2></oj-slider>

Initialize a component attribute via component binding:

<oj-slider value="{{currentValue}}"></oj-slider>

Slots

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

contextMenu

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

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

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

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

Example

Initialize the component with a context menu:

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

Attributes

described-by :string

It is used to establish a relationship between this component and another element. Typically this is not used by the application developer, but by the oj-label custom element's code. One use case is where the oj-label custom element code writes described-by on its form component for accessibility reasons. To facilitate correct screen reader behavior, the described-by attribute is copied to the aria-describedby attribute on the component's dom element.
Since:
  • 4.0.0
Names
Item Name
Property describedBy
Property change event describedByChanged
Property change listener attribute (must be of type function) on-described-by-changed
Examples

Initialize component with the described-by attribute specified:

<oj-some-element described-by="someId"></oj-some-element>

Get or set the describedBy property after initialization:

// getter
var descById = myComp.describedBy;

// setter
myComp.describedBy = "someId";

disabled :boolean

Whether the component is disabled. The disabled attribute is used as its initial value if it exists, when the attribute is not explicitly set. When neither is set, disabled defaults to false.
Default Value:
  • false
Since:
  • 0.7
Names
Item Name
Property disabled
Property change event disabledChanged
Property change listener attribute (must be of type function) on-disabled-changed
Examples

Initialize the slider with disabled attribute:

<oj-slider disabled="true"></oj-slider>

Get or set the disabled property after initialization:

// Getter
var disabled = myComponent.disabled;

// Setter
myComponent.disabled = true;

display-options :Object|undefined

Display options for auxilliary content that determines where it should be displayed in relation to the component.

The types of messaging content for which display options can be configured include messages, converterHint, validatorHint and helpInstruction.
The display options for each type is specified either as an array of strings or a string. When an array is specified the first display option takes precedence over the second and so on.

JET editable components set defaults that apply to the entire app/page. It is possible to override the defaults on a per instance basis as explained in the examples below or change defaults for the entire application using oj.Components#setDefaultOptions method. It is much easier to change the defaults using setDefaultOptions once rather than putting the displayOptions option on every component instance.

When display-options changes due to programmatic intervention, the component updates its display to reflect the updated choices. For example, if 'help.instruction' property goes from 'notewindow' to 'none' then it no longer shows in the notewindow.

A side note: help.instruction and message detail text can include formatted HTML text, whereas hints and message summary text cannot. If you use formatted text, it should be accessible and make sense to the user if formatting wasn't there. To format the help.instruction, you could do this:

<html>Enter <b>at least</b> 6 characters</html>

Properties:
Name Type Argument Description
converterHint Array | string <optional>
supported values are 'placeholder', 'notewindow', 'none'. The default value is ['placeholder', 'notewindow']. When there is already a placeholder set on the component, the converter hint falls back to display type of 'notewindow'. To change the default value you can do this -
E.g. {'displayOptions: {'converterHint': ['none']}}
validatorHint Array | string <optional>
supported values are 'notewindow', 'none'. To change the default value you can do this -
{'displayOptions: {'validatorHint': ['none']}}
messages Array | string <optional>
supported values are 'notewindow', 'inline', 'none'. The default is 'inline'. To change the default value you can do this -
E.g. {'displayOptions: {'messages': 'none'}}
helpInstruction Array | string <optional>
supported values are 'notewindow', 'none'. To change the default value you can do this -
E.g. displayOptions='{"helpInstruction": "none"}'
Default Value:
  • {'messages': ['inline'],'converterHint': ['placeholder','notewindow'],'validatorHint': ['notewindow'],'helpInstruction': ['notewindow']}
Since:
  • 0.7
Names
Item Name
Property displayOptions
Property change event displayOptionsChanged
Property change listener attribute (must be of type function) on-display-options-changed
Examples

Override default values for displayOptions for messages for the entire application:

// messages will be shown in the notewindow for the application.
oj.Components.setDefaultOptions({
   'editableValue':
   {
     'displayOptions': 
     {
       'messages': ['notewindow']
     }
   }
});

Override default values for display-options for one component:

// In this example, the display-options are changed from the defaults.
// The 'converterHint' is none, the 'validatorHint' is none and the 'helpInstruction' is none,
// so only the 'messages' will display in its default state.
// For most apps, you will want to change the displayOptions app-wide
// for all EditableValue components, so you should use the
// oj.Components#setDefaultOptions function instead (see previous example).
//
<oj-some-element display-options='{"converterHint": "none",
                                    "validatorHint": "none",
                                    "helpInstruction": "none"}'></oj-some-element>

Get or set the displayOptions property after initialization:

// Get one subproperty
var hint = myComp.displayOptions.converterHint;

// Set one, leaving the others intact. Use the setProperty API for 
// subproperties so that a property change event is fired.
myComp.setProperty("displayOptions.converterHint", "none");

// get all
var options = myComp.displayOptions;

// set all.  Must list every resource key, as those not listed are lost.
myComp.displayOptions = {converterHint: "none", validatorHint: "none", helpInstruction: "none"};

help :Object.<string, string>

Form component help information.

The properties supported on the help option are:

Properties:
Name Type Argument Description
instruction string <optional>
this represents advisory information for the component The default value is null.
Default Value:
  • {'help' : {'instruction': null}}
Since:
  • 0.7
Names
Item Name
Property help
Property change event helpChanged
Property change listener attribute (must be of type function) on-help-changed

help.instruction :string|undefined

Represents advisory information for the component, such as would be appropriate for a tooltip.

When help.instruction is present it is by default displayed in the notewindow, or as determined by the 'helpInstruction' property set on the displayOptions attribute. When the help.instruction property changes the component refreshes to display the updated information.

JET takes the help instruction text and creates a notewindow with the text. The help instruction only shows up as a tooltip on mouse over, not on keyboard and not in a mobile device. So help instruction would only be for text that is not important enough to show all users, or for text that you show the users in another way as well, like in the label. Also you cannot theme the native browser's title window like you can the JET notewindow, so low vision users may have a hard time seeing it. For these reasons, the JET EditableValue components do not use the HTML's title attribute.

To include formatted text in the help.instruction, format the string using html tags. For example the help.instruction might look like:

<oj-some-element help.intruction="<html>Enter <b>at least</b> 6 characters</html>"></oj-some-element>
If you use formatted text, it should be accessible and make sense to the user if formatting wasn't there.

Default Value:
  • null
Since:
  • 4.0.0
Names
Item Name
Property help.instruction
Examples

Initialize the component with the help.instruction sub-attribute:

<oj-some-element help.instruction="some tooltip"></oj-some-element>
 

Get or set the help.instruction property after initialization:

// Get one subproperty
var instr = myComp.help.instruction;

// Set one subproperty, leaving the others intact. Use the setProperty API for 
// subproperties so that a property change event is fired.
myComponent.setProperty('help.instruction', 'some new value');

// Get all
var values = myComponent.help;

// Set all.  Must list every resource key, as those not listed are lost.
myComponent.help = {
  instruction: 'some new value'
};

help-hints :Object.<string, string>

Represents hints for oj-form-layout element to render help information on the label of the editable component.

This is used only if the editable component is added as a direct child to an oj-form-layout element, and the labelHint property is also specified.

The helpHints object contains a definition property and a source property.

  • definition - hint for help definition text.
  • source - hint for help source URL.
Default Value:
  • {'definition': "", 'source': ""}
Since:
  • 4.1.0
Names
Item Name
Property helpHints
Property change event helpHintsChanged
Property change listener attribute (must be of type function) on-help-hints-changed
Examples

Initialize the component with help hints:

<!-- Using dot notation -->
<oj-some-element help-hints.definition='some value' help-hints.source='some-url'></oj-some-element>

<!-- Using JSON notation -->
<oj-some-element help-hints='{"definition":"some value", "source":"some-url"}'></oj-some-element>

Get or set the helpHints property after initialization:

// Get one
var value = myComponent.helpHints.definition;

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

// Get all
var values = myComponent.helpHints;

// Set all.  Must list every subproperty, as those not listed are lost.
myComponent.helpHints = {
    definition: 'some new value',
    source: 'some-new-url'
};

help-hints.definition :string

Hint for help definition text associated with the label.

It is what shows up when the user hovers over the help icon, or tabs into the help icon, or press and holds the help icon on a mobile device. No formatted text is available for help definition attribute.

See the help-hints attribute for usage examples.

Default Value:
  • ""
Since:
  • 4.1.0
Names
Item Name
Property helpHints.definition

help-hints.source :string

Hint for help source URL associated with the label.

If present, a help icon will render next to the label. For security reasons we only support urls with protocol http: or https:. If the url doesn't comply we ignore it and throw an error. Pass in an encoded URL since we do not encode the URL.

See the help-hints attribute for usage examples.

Default Value:
  • ""
Since:
  • 4.1.0
Names
Item Name
Property helpHints.source

label-hint :string

Represents a hint for oj-form-layout element to render a label on the editable component.

This is used only if the editable component is added as a direct child to an oj-form-layout element.

When labelHint is present it gives a hint to the oj-form-layout element to create an oj-label element for the editable component. When the labelHint property changes oj-form-layout element refreshes to display the updated label information.

Default Value:
  • ""
Since:
  • 4.1.0
Names
Item Name
Property labelHint
Property change event labelHintChanged
Property change listener attribute (must be of type function) on-label-hint-changed
Examples

Initialize the component with the label-hint attribute specified:

<oj-some-element label-hint='input label'></oj-some-element>

Get or set the labelHint property after initialization:

// getter
var value = myComponent.labelHint;

// setter
myComponent.labelHint = 'some new value'

max :number

The maximum value of the slider. The max must not be less than the min, or else an Error is thrown during initialization.
Default Value:
  • null
Since:
  • 0.7
Names
Item Name
Property max
Property change event maxChanged
Property change listener attribute (must be of type function) on-max-changed
Examples

Initialize the slider with the max attribute:

<oj-slider max=100></oj-slider>

Get or set the max property after initialization:

// Getter
var max = myComponent.max;

// Setter
myComponent.max = 100;

messages-custom :Array.<Object>|undefined

List of messages an app would add to the component when it has business/custom validation errors that it wants the component to show. When this option is set the message shows to the user right away. To clear the custom message, set messagesCustom back to an empty array.

Each message in the array is an object that duck types oj.Message. See oj.Message for details.

See the Validation and Messages section for details on when the component clears messagesCustom; for example, when full validation is run.

Default Value:
  • []
Supports writeback:
  • true
Since:
  • 0.7
Names
Item Name
Property messagesCustom
Property change event messagesCustomChanged
Property change listener attribute (must be of type function) on-messages-custom-changed
Examples

Initialize component with the messages-custom attribute specified:

<oj-some-element messages-custom='[{"summary":"hello","detail":"detail"}]'></oj-some-element>

Get or set the messagesCustom property after initialization:

// getter
var customMsgs = myComp.messagesCustom;

// setter
myComp.messagesCustom = [{summary:"hello", detail:"detail", severity:oj.Message.SEVERITY_LEVEL.INFO}];

Set messagesCustom when there are cross-validation errors:

--- HTML ---
<oj-some-element messages-custom='{{messagesCustom}}'></oj-some-element> 

--- ViewModel code ---
self.messagesCustom = ko.observableArray([]);

// the app's function that gets called when the user presses the submit button
if (!myValidateCrossValidationFields())
{
  // the app adds a custom messages to the component and it is displayed right away
  var msgs = [];
  msgs.push({'summary':'Cross field error', 'detail':'Field 1 needs to be less than Field 2'});
  self.messagesCustom(msgs);
}
else
{
  // submit data to the server
}

min :number

The minimum value of the slider. The min must not be greater than the max, or else an Error is thrown during initialization.
Default Value:
  • null
Since:
  • 0.7
Names
Item Name
Property min
Property change event minChanged
Property change listener attribute (must be of type function) on-min-changed
Examples

Initialize the slider with the min attribute:

<oj-slider min=0></oj-slider>

Get or set the min property after initialization:

// Getter
var min = myComponent.min;

// Setter
myComponent.min = 0;

orientation :string

Specify the orientation of the slider.
Supported Values:
Name Type Description
"horizontal" string Orient the slider horizontally.
"vertical" string Orient the slider vertically.
Default Value:
  • "horizontal"
Since:
  • 0.7
Names
Item Name
Property orientation
Property change event orientationChanged
Property change listener attribute (must be of type function) on-orientation-changed
Examples

Initialize the slider with the orientation attribute:

<oj-slider orientation="vertical"></oj-slider>

Get or set the orientation property after initialization:

// Getter
var orientation = myComponent.orientation;

// Setter
myComponent.orientation = "vertical";

step :number

Determines the size or amount of each interval or step the slider takes between min and max. The full specified value of the range (max - min) should be divisible by step.
Default Value:
  • 1
Since:
  • 0.7
Names
Item Name
Property step
Property change event stepChanged
Property change listener attribute (must be of type function) on-step-changed
Examples

Initialize the slider with the step attribute:

<oj-slider step=10></oj-slider>

Get or set the step property after initialization:

// Getter
var step = myComponent.step;

// Setter
myComponent.step = 10;

translations :Object

A collection of translated resources from the translation bundle, or null if this component has no resources. Resources may be accessed and overridden individually or collectively, as seen in the examples.

If this component has translations, their documentation immediately follows this doc entry.

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

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

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

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

Get or set the translations property after initialization:

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

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

// Get all
var values = myComponent.translations;

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

translations.invalid-step :string

Invalid step value.

See the translations attribute for usage examples.

Default Value:
  • "Invalid step; step must be > 0"
Since:
  • 1.1.1
Names
Item Name
Property translations.invalidStep

translations.max-min :string

Max is greater than min.

See the translations attribute for usage examples.

Default Value:
  • "Max must not be less than min"
Since:
  • 1.1.1
Names
Item Name
Property translations.maxMin

translations.no-value :string

Missing value exception.

See the translations attribute for usage examples.

Default Value:
  • "ojSlider has no value"
Since:
  • 1.1.1
Names
Item Name
Property translations.noValue

translations.option-num :string

The option is not a number.

See the translations attribute for usage examples.

Default Value:
  • "{option} option is not a number"
Since:
  • 1.1.1
Names
Item Name
Property translations.optionNum

translations.value-range :string

Value outside min to max range.

See the translations attribute for usage examples.

Default Value:
  • "Value must be within min to max range"
Since:
  • 1.1.1
Names
Item Name
Property translations.valueRange

type :string

The slider type determines whether the slider how the value is represented in the UI.
Supported Values:
Name Type Description
"fromMax" string A single-thumb slider where the value bar goes from the slider thumb to the the slider max.
"fromMin" string A single-thumb slider where the value bar goes from the slider min to the the slider thumb.
"single" string A single-thumb slider where the value bar has no additional styling.
Default Value:
  • "fromMin"
Since:
  • 0.7
Names
Item Name
Property type
Property change event typeChanged
Property change listener attribute (must be of type function) on-type-changed
Examples

Initialize component with type attribute set to "fromMax":

<oj-slider type="fromMax"></oj-slider>

Get or set the type property after initialization:

// Getter
var type = myComponent.type;

// Setter
myComponent.type = "fromMax";

<readonly> valid :string

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

The current valid state of the component. It is evaluated on initial render. It is re-evaluated

  • after validation is run (full or deferred)
  • when messagesCustom is updated, since messagesCustom can be added by the app developer any time.
  • when showMessages() is called. Since showMessages() moves the hidden messages into messages shown, if the valid state was "invalidHidden" then it would become "invalidShown".
  • when the required property has changed. If a component is empty and has required set, the valid state may be "invalidHidden" (if no invalid messages are being shown as well). If required property is removed, the valid state would change to "valid".

Note: New valid states may be added to the list of valid values in future releases. Any new values will start with "invalid" if it is an invalid state, "pending" if it is pending state, and "valid" if it is a valid state.

Supported Values:
Name Type Description
"invalidHidden" string The component has invalid messages hidden and no invalid messages showing. An invalid message is one with severity "error" or higher.
"invalidShown" string The component has invalid messages showing. An invalid message is one with severity "error" or higher.
"pending" string The component is waiting for the validation state to be determined. The "pending" state is never set in this release of JET. It will be set in a future release.
"valid" string The component is valid
Supports writeback:
  • true
Since:
  • 4.2.0
Names
Item Name
Property valid
Property change event validChanged
Property change listener attribute (must be of type function) on-valid-changed
Examples

Get valid attribute, after initialization:

// Getter:
var valid = myComp.valid;

Set the on-valid-changed listener so you can do work in the ViewModel based on the valid property:

<oj-some-element id='username' on-valid-changed='[[validChangedListener]]'>
</oj-some-element>
<oj-some-element id='password' on-valid-changed='[[validChangedListener]]'>
</oj-some-element>
<oj-button disabled='[[componentDisabled]]' on-click='[[submit]]'>Submit</oj-button>
-- ViewModel --
self.validChangedListener = function (event) {
  var enableButton;
  var usernameValidState;
  var passwordValidState;
  
  // update the button's disabled state.
  usernameValidState = document.getElementById("username").valid;
  passwordValidState = document.getElementById("password").valid;
  
  // this updates the Submit button's disabled property's observable based
  // on the valid state of two components, username and password.
  // It is up to the application how it wants to handle the “pending” state 
  // but we think that in general buttons don’t need to be 
  // enabled / disabled based on the "pending" state.
  enableButton = 
   (usernameValidState !== "invalidShown") &&
   (passwordValidState !== "invalidShown");
  self.componentDisabled(!enableButton);;
};

value :number

The numerical value of the slider.

Note that the value attribute should be compatible with the type attribute, as described above. A value that is not compatible with the type will be coerced into a compatible value.

Default Value:
  • 0
Supports writeback:
  • true
Since:
  • 0.7
Names
Item Name
Property value
Property change event valueChanged
Property change listener attribute (must be of type function) on-value-changed
Examples

Initialize the slider with the value attribute:

<oj-slider value=55></oj-slider>

Get or set value property after initialization:

// Getter
var value = myComponent.value;

// Setter
myComponent.value = 10;

Events

ojAnimateEnd

Triggered when a default animation has ended.
Properties:

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

Name Type Description
action string The action that triggers the animation. Supported values are:
  • "inline-open" - when an inline message container opens or increases in size
  • "inline-close" - when an inline message container closes or decreases in size
  • "notewindow-open" - when a note window opens
  • "notewindow-close" - when a note window closes
element Element The element being animated.
Since:
  • 4.0.0
Examples

Define an event listener for the ojAnimateEnd event to add any processing after the end of "inline-open" animation:

var listener = function( event )
{
  // Check if this is the end of "inline-open" animation for inline message
  if (event.detail.action == "inline-open") {
    // Add any processing here
  }
};

Specify an ojAnimateEnd listener via the DOM attribute:

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

Specify an ojAnimateEnd listener via the JavaScript property:

mySlider.onOjAnimateEnd = listener;

Add an ojAnimateEnd listener via the addEventListener API:

mySlider.addEventListener('ojAnimateEnd', listener);

ojAnimateStart

Triggered when a default animation is about to start on an element owned by the component.

The default animation can be cancelled by calling event.preventDefault, followed by a call to ui.endCallback. ui.endCallback should be called immediately after event.preventDefault if the application merely wants to cancel animation, or it should be called when the custom animation ends if the application is invoking another animation function. Failure to call ui.endCallback may prevent the component from working properly.

For more information on customizing animations, see the documentation of oj.AnimationUtils.

The default animations are controlled via the theme (SCSS) :

// default animations for "notewindow" display option
$noteWindowOpenAnimation: (effect: "zoomIn", transformOrigin: "#myPosition") !default;
$noteWindowCloseAnimation: (effect: "none") !default;

// default animations for "inline" display option
$messageInlineOpenAnimation: (effect: "expand", startMaxHeight: "#oldHeight") !default;
$messageInlineCloseAnimation: (effect: "collapse", endMaxHeight: "#newHeight") !default;
Properties:

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

Name Type Description
action string The action that triggers the animation. Supported values are:
  • "inline-open" - when an inline message container opens or increases in size
  • "inline-close" - when an inline message container closes or decreases in size
  • "notewindow-open" - when a note window opens
  • "notewindow-close" - when a note window closes
element Element The element being animated.
endCallback function If the event listener calls event.preventDefault to cancel the default animation, it must call the endCallback function when it finishes its own animation handling and any custom animation has ended.
Since:
  • 4.0.0
Examples

Define an event listener for the ojAnimateStart event to override the default "inline-open" animation:

var listener = function( event )
  {
    // Change the "inline-open" animation for inline message
    if (event.detail.action == "inline-open") {
      // Cancel default animation
      event.preventDefault();
      // Invoke new animation and call endCallback when the animation ends
      oj.AnimationUtils.fadeIn(event.detail.element).then(event.detail.endCallback);
    }
  };

Define an event listener for the ojAnimateStart event to cancel the default "notewindow-close" animation:

var listener = function( event )
  {
    // Change the "notewindow-close" animation for note window
    if (ui.action == "notewindow-close") {
      // Cancel default animation
      event.preventDefault();
      // Call endCallback immediately to indicate no more animation
      event.detail.endCallback();
  };

Specify an ojAnimateStart listener via the DOM attribute:

<oj-slider on-oj-animate-start='[[listener]]'></oj-slider>

Specify an ojAnimateStart listener via the JavaScript property:

mySlider.onOjAnimateStart = listener;

Add an ojAnimateStart listener via the addEventListener API:

mySlider.addEventListener('ojAnimateStart', listener);

Methods

blur() → {undefined}

Blurs the element that naturally gets focus. For example, this would be the input element for input type components.
Since:
  • 4.2
Returns:
Type
undefined
Example

Calling blur on a custom element will call blur on the appropriate child element

var elem = document.getElementById("myId");
elem.blur();

focus() → {undefined}

Sets focus on the element that naturally gets focus. For example, this would be the input element for input type components.
Since:
  • 4.2
Returns:
Type
undefined
Example

Calling focus on a custom element will call focus on the appropriate child element

var elem = document.getElementById("myId");
elem.focus();

getProperty(property) → {*}

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

Get a single subproperty of a complex property:

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

refresh()

Called when the DOM underneath the component changes requiring a re-render of the component. An example is when the id for the input changes.

Another time when refresh might be called is when the locale for the page changes. When it changes, attributes used by its converter and validator that are locale specific, its hints, messages and translations will be updated.

When refresh method is called, the component may take various steps such as clearing messages, running validation etc., based on the state it is in.

Steps Performed Always

  • The converter and validators used by the component are reset, and new converter and validator hints is pushed to messaging. E.g., notewindow displays the new hint(s).

Running Validation

  • if component is valid when refresh() is called, the display value is refreshed if component has a converter set.
  • if component is invalid and is showing messages when refresh() is called, then all component messages are cleared and full validation run using the display value on the component.
    • if there are validation errors, then value attribute is not updated and the error is shown.
    • if no errors result from the validation, the value attribute is updated; page author can listen to the onValueChanged event to clear custom errors.
  • if component is invalid and has deferred messages when refresh() is called, then all component messages are cleared and deferred validation is run.

Clearing Messages

  • If clearing messages only those created by the component are cleared.
  • messagesCustom attribute is not cleared.

Since:
  • 0.7
Example

Redraw the component element.

myComp.refresh();

reset()

Resets the component by clearing all messages and messages attributes - messagesCustom - and updates the component's display value using the attribute value. User entered values will be erased when this method is called.
Since:
  • 0.7
Example

Reset component

myComp.reset(); 

setProperties(properties)

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

Set a batch of properties:

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

setProperty(property, value)

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

Set a single subproperty of a complex property:

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

showMessages()

Takes all deferred messages and shows them. It then updates the valid property; e.g., if the valid state was "invalidHidden" before showMessages(), the valid state will become "invalidShown" after showMessages().

If there were no deferred messages this method simply returns.

Since:
  • 0.7
Example

Display all messages including deferred ones.

myComp.showMessages();