Element: <oj-input-number>

Oracle® JavaScript Extension Toolkit (JET)
5.0.0

E90577-01

QuickNav

Attributes

JET Custom Elements

JET components are implemented as custom HTML elements. In addition to the component attributes documented in this page, JET components also support standard HTML global attributes like id and aria-label.

The JET data binding syntax can be used to define both component and global attributes through the use of dynamically evaluated expressions. All attributes (component and global) support attribute-level binding by prefixing the attribute name with ":" (e.g. :id="[...]"). When using attribute-level binding, all expression values are treated as strings. Additionally, component attributes support property-level binding by using the attribute name directly with no ":" prefix. When using property-level binding, the expressions should evaluate to the types documented by the corresponding attributes. Property-level binding is strongly recommended over attribute-level binding for component attributes.

A detailed description of working with custom HTML elements can be found in: JET Custom Element Usage.


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

Version:
  • 5.0.0
Since:
  • 0.6
Module:
  • ojinputnumber

JET InputNumber Component

Description: The oj-input-number component enhances a browser input element into one that holds numbers and it has a spinbox to quickly increment or decrement the number. The value attribute must be a number and must be within the min and max range.

A step mismatch is when the value is not a multiple of step, starting at the min else initial vlaue if no min is set, else 0. A step mismatch will not be flagged as a validation error by default, but the step up and step down feature will change the value to be a step match if it isn't already.

Validation and Messaging

An editable component runs validation (normal or deferred) based on the action performed on it (either by end-user or page author), and the state it was in when the action occurred. Examples of actions are - creating a component, user changing the value of the component by interacting with it, the app setting a value programmatically, the app calling the validate() method etc. At the time the action occurs, the component could already be showing errors, or can have a deferred error or have no errors.

These factors also determine whether validation errors/messages get shown to the user immediately or get deferred. The following sections highlight the kinds of validation that are run and how messages get handled.

Normal Validation

Normal validation is run in the following cases on the display value, using the converter and validators set on the component, and validation errors are reported to user immediately.
  • When value changes as a result of user interaction all messages are cleared, including custom messages added by the app, and full validation is run on the UI value. The steps performed are outlined below.
    1. All messages are cleared and messagesCustom property is cleared
    2. If no converter is present then processing continues to next step. If a converter is present, the UI value is first converted (i.e., parsed). If there is a parse error then the messages are shown and processing returns.
    3. If there are no validators setup for the component then the value is set on the component. Otherwise all validators are run in sequence using the parsed value from the previous step. The implicit required is run first if the component is marked required. When a validation error is encountered it is remembered and the next validator in the sequence is run.
      • NOTE: The value is trimmed before required validation is run
    4. At the end of the validation run if there are errors, the messages are shown and processing returns. If there are no errors, then the value property is updated and the formatted value displayed on the UI.
  • When the validate method is called by app, all messages are cleared and full validation run using the display value. See validate method on the sub-classes for details. Note: JET validation is designed to catch user input errors, and not invalid data passed from the server; this should be caught on the server.
  • When certain properties change through programmatic intervention by app, the component determines whether it needs to run normal validation based on the state the component is in. Refer to the Mixed Validation section below for details.

Deferred Validation

Deferred validation is run in the following cases on the component value using the implicit required validator if required is true, and validation errors are deferred, i.e., not shown to user immediately. Refer to the Showing Deferred Messages section to understand how deferred messages can be shown.
  • When a component is created and it is required deferred validation is run and no messages are cleared prior to running validation. Refer to the Validators Participating in Deferred Validation section for details.
  • When the value property changes due to programmatic intervention deferred validation is run, after all messages and messagesCustom property are cleared.
  • When the reset method is called, deferred validation is run after all messages and messagesCustom property are cleared.
  • When certain properties change through programmatic intervention by app, the component determines whether it needs to run deferred validation based on the state the component is in. Refer to the Mixed Validation section below for details.

Mixed Validation

Either deferred or normal validation is run in the following cases based on the state the component is in and any validation errors encountered are either hidden or shown to user.
  • when disabled property changes. See disabled property for details.
  • when refresh method is called. See refresh method for details.
  • when converter property changes. Not all EditableValue components have the converter property. See the sub-classes that have the converter property for details, e.g., oj.inputBase#converter.
  • when required property changes. Not all EditableValue components have the required property. See the sub-classes that have the required property for details, e.g., oj.inputBase#required.
  • when validators property changes. Not all EditableValue components have the validators property. See the sub-classes that have the validators property for details, e.g., oj.inputBase#validators.

Showing Deferred Messages

Deferred validation messages are displayed only when page author requests for it explicitly in one of the following ways:

Validators Participating in Deferred Validation

The required validator is the only validator type that participates in deferred validation. The required property needs to be set to true for the required validator to run.

Touch End User Information

Target Gesture Action
Up Button Tap Increment the number.
Down Button Tap Decrement the number.
Input Tap Set focus to the input. If hints, help.instruction or messages exists in a notewindow, pop up the notewindow.
Elsewhere on Page Touch Submit the value you typed in the input field.

Keyboard End User Information

Target Key Action
Input Enter or Tab Submit the value you typed in the input field.
Tab In Set focus to input. If hints, help.instruction or messages exist in a notewindow, pop up the notewindow.
UpArrow Increment the number.
DownArrow Decrement the number.

Accessibility

The component is accessible; it sets and maintains the appropriate aria- attributes, like aria-valuenow, aria-valuemax, aria-valuemin and aria-valuetext.

Disabled content: JET supports an accessible luminosity contrast ratio, as specified in WCAG 2.0 - Section 1.4.3 "Contrast", in the themes that are accessible. (See the "Theming" chapter of the JET Developer Guide for more information on which themes are accessible.) Note that Section 1.4.3 says that text or images of text that are part of an inactive user interface component have no contrast requirement. Because disabled content may not meet the minimum contrast ratio required of enabled content, it cannot be used to convey meaningful information.

Styling

The following CSS classes can be applied by the page author as needed.

Class Description
oj-form-control-text-align-right Aligns the text to the right regardless of the reading direction, this is normally used for right aligning numbers

Label and InputNumber

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

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-input-number component with no attributes specified:

<oj-input-number></oj-input-number>

Initialize the component with some attributes:

<oj-input-number id="numberId" max="100" min="0" step="2"></oj-input-number>

Initialize a component attribute via component binding:

<oj-input-number id="numberId" value="{{currentValue}}"></oj-input-number>

Slots

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

  • Any child element with a slot attribute will be moved into that named slot, e.g. <span slot='startIcon'>...</span>. All supported named slots are documented below. Child elements with unsupported named slots will be removed from the DOM.
  • Any child element lacking a slot attribute will be moved to the default slot, also known as a regular child.

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

autocomplete :string|undefined

Dictates component's autocomplete state. This attribute indicates whether the value of the control can be automatically completed by the browser.
Supported Values:
Name Type Description
"off" string disable autofill
"on" string enable autofill
Default Value:
  • "off"
Names
Item Name
Property autocomplete
Property change event autocompleteChanged
Property change listener attribute (must be of type function) on-autocomplete-changed
Examples

Initialize component with autocomplete attribute:

<oj-input-number autocomplete = "on"></oj-input-number>

Get or set the autocomplete property after initialization:

// getter
var ro = myComp.autocomplete;

// setter
myComp.autocomplete = "on";

autofocus :boolean

Autofocus is a Boolean that reflects the autofocus attribute, If it is set to true then the associated component will get input focus when the page is loaded. Setting this property doesn't set the focus to the component: it tells the browser to focus to it when the element is inserted in the document.
Default Value:
  • false
Names
Item Name
Property autofocus
Property change event autofocusChanged
Property change listener attribute (must be of type function) on-autofocus-changed
Examples

Initialize component with autofocus attribute:

<oj-input-number autofocus></oj-input-number>

Get or set the autofocus property after initialization:

// getter
var ro = myComp.autofocus;

// setter
myComp.autofocus = false;

converter :Object

A number converter instance that duck types oj.NumberConverter. Or an object literal containing the properties listed below. When no converter is specified, the default converter will be used, and default option of "numeric" is used.

When converter property changes due to programmatic intervention, the component performs various tasks based on the current state it is in.
When initialized with no options, the default options for the current locale are assumed.

Steps Performed Always

  • Any cached converter instance is cleared and new converter created. The converter hint is pushed to messaging. E.g., notewindow displays the new hint(s).

Running Validation

  • if component is valid when converter property changes, the display value is refreshed.
  • if component is invalid and is showing messages when converter property changes, then all messages generated by the component are cleared and full validation run using its current display value.
    • if there are validation errors, then value property is not updated, and the errors are shown. The display value is not refreshed in this case.
    • if no errors result from the validation, value property is updated; page author can listen to the valueChanged event to clear custom errors. The display value is refreshed with the formatted value provided by converter.
  • if component is invalid and has deferred messages when converter property changes, then the display value is refreshed with the formatted value provided by converter.

Clearing Messages

  • messages created by the component are cleared.
  • messagesCustom property is not cleared. Page authors can choose to clear it explicitly when setting the converter property.

Properties:
Name Type Argument Description
type string the converter type registered with the oj.ConverterFactory. Usually 'number'. See oj.NumberConverterFactory for details.
E.g., {converter: {type: 'number'}
options Object <optional>
optional Object literal of options that the converter expects. See oj.IntlNumberConverter for options supported by the jet number converter. E.g., {converter: {type: 'number', options: {style: 'decimal'}}
Default Value:
  • oj.Validation.converterFactory(oj.ConverterFactory.CONVERTER_TYPE_NUMBER).createConverter()
Names
Item Name
Property converter
Property change event converterChanged
Property change listener attribute (must be of type function) on-converter-changed
Examples

Initialize component to use default converter

<oj-input-number value="25000"></oj-input-number>

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 attribute <oj-input-number value="25000" converter="[[salaryConverter]]"></oj-input-number>

Initialize the component with converter object literal:

<oj-input-number value="25000" converter='
  {
    "type": "number",
    "options" : {
      "style": "currency",
      "currency": "USD",
      "maximumFractionDigits": "0"
    }
  }'></oj-input-number>

Get or set the converter property after initialization:

// Getter
var convtr = myComponent.converter;

// Setter
myComponent.converter = salaryConverter;

(nullable) 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 default is false.

When the disabled property changes due to programmatic intervention, the component may clear messages and run validation in some cases.

  • when a required component is initialized as disabled value="{{currentValue}}" required disabled, deferred validation is skipped.
  • when a disabled component is enabled,
    • if component is invalid and showing messages then all component messages are cleared, and full validation run using the display value.
      • if there are validation errors, they are shown.
      • if no errors result from the validation, the value property is updated. Page authors can listen to the onValueChanged event to clear custom errors.
    • if component is valid and has no errors then deferred validation is run.
      • if there is a deferred validation error, then the valid property is updated.
    • if component is invalid and deferred errors then component messages are cleared and deferred validation re-run.
      • if there is a deferred validation error, then the valid property is updated.
  • when enabled component is disabled then no validation is run and the component appears disabled.

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 component with disabled attribute:

<oj-some-element disabled></oj-some-element>

Get or set the disabled property after initialization:

// getter
var disabled = myComp.disabled;

// setter
myComp.disabled = false;

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.<('placeholder'|'notewindow'|'none')> | 'placeholder' | 'notewindow' | 'none' <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.<('notewindow'|'none')> | 'notewindow' | 'none' <optional>
supported values are 'notewindow', 'none'. To change the default value you can do this -
{'displayOptions: {'validatorHint': ['none']}}
messages Array.<('inline'|'notewindow'|'none')> | 'inline' | 'notewindow' | 'none' <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.<('notewindow'|'none')> | 'notewindow' | 'none' <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

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.instruction="<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:
  • ""
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'

(nullable) max :number

The maximum allowed value. This number is used in the range validator; if the value is greater than the max, then the range validator flags an error to the user. The up arrow is disabled when the maximum value is reached.

Max must be a number or null; null indicates no maximum.

The max must not be less than the min, else an Error is thrown during initialization.

Default Value:
  • null
Names
Item Name
Property max
Property change event maxChanged
Property change listener attribute (must be of type function) on-max-changed
Examples

Initialize the inputNumber with the max attribute specified:

<oj-input-number max="100"></oj-input-number>

Change the max property to a float:

myComponent.max = 100.5;

To remove the maximum range restriction from inputNumber:

myComponent.max =  null;

Get or set the max property after initialization:

// Getter
var max = myComponent.max;

// Setter
myComponent.max = 100;

messages-custom :Array.<Object>

List of messages an app would add to the component when it has business/custom validation errors that it wants the component to show. This allows the app to perform further validation before sending data to the server. 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

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
}

(nullable) min :number

The minimum allowed value. This number is used in the range validator; if the value is less than the min, then the range validator flags an error to the user. The down arrow is disabled when the minimum value is reached.

Min must be a number or null; null indicates no minimum.

The max must not be less than the min, else an Error is thrown during initialization.

Default Value:
  • null
Names
Item Name
Property min
Property change event minChanged
Property change listener attribute (must be of type function) on-min-changed
Examples

Initialize the inputNumber with the min attribute specified:

<oj-input-number min="0"></oj-input-number>

Get or set the min property after initialization:

// Getter
var min = myComponent.min;

// Setter
myComponent.min = 0;

Change the min property to a float:

myComponent.min = 10.5;

To remove the minimum range restriction from inputNumber:

myComponent.min =  null;

name :string

It indicates the name of the component.
Default Value:
  • ""
Names
Item Name
Property name
Property change event nameChanged
Property change listener attribute (must be of type function) on-name-changed
Examples

Initialize component with name attribute:

<oj-input-number name="myName"></oj-input-number>

Get or set the name property after initialization:

// getter
var ro = myComp.name;

// setter
myComp.name = "myName";

placeholder :string|null

The placeholder text to set on the element.
Default Value:
  • ""
Names
Item Name
Property placeholder
Property change event placeholderChanged
Property change listener attribute (must be of type function) on-placeholder-changed
Examples

Initialize the component with the placeholder attribute:

<oj-input-number placeholder="Enter a number"></oj-input-number>

Get or set the placeholder property after initialization:

// Getter
var placeholder = myComponent.placeholder;

// Setter
myComponent.placeholder = "Address";

If the attribute is not set then the default can be a converter hint. See display-options for
details.

(readonly) raw-value :string|undefined

The rawValue is the read-only property for retrieving the current value from the input field in string form. The main consumer of rawValue is a converter.

The rawValue updates on the 'input' javascript event, so the rawValue changes as the value of the input is changed. If the user types in '1,200' into the field, the rawValue will be '1', then '1,', then '1,2', ..., and finally '1,200'. Then when the user blurs or presses Enter the value property gets updated.

This is a read-only property so page authors cannot set or change it directly.

Supports writeback:
  • true
Since:
  • 1.2.0
Names
Item Name
Property rawValue
Property change event rawValueChanged
Property change listener attribute (must be of type function) on-raw-value-changed

(nullable) readonly :boolean

Whether the component is readonly.
Default Value:
  • false
Names
Item Name
Property readonly
Property change event readonlyChanged
Property change listener attribute (must be of type function) on-readonly-changed
Examples

Initialize component with readonly attribute:

<oj-input-number readonly></oj-input-number>

Get or set the readonly property after initialization:

// Getter
var readonly = myComponent.readonly;

// Setter
myComponent.readonly = false;

required :boolean

Whether the component is required or optional. When required is set to true, an implicit required validator is created using the validator factory - oj.Validation.validatorFactory(oj.ValidatorFactory.VALIDATOR_TYPE_REQUIRED).createValidator(). Translations specified using the translations.required attribute and the label associated with the component, are passed through to the options parameter of the createValidator method.

When required property changes due to programmatic intervention, the component may clear messages and run validation, based on the current state it's in.

Running Validation

  • if component is valid when required is set to true, then it runs deferred validation on the value property. This is to ensure errors are not flagged unnecessarily.
  • if component is invalid and has deferred messages when required is set to false, then component messages are cleared but no deferred validation is run.
  • if component is invalid and currently showing invalid messages when required is set, then component messages are cleared and normal validation is run using the current display value.
    • if there are validation errors, then value property is not updated and the error is shown.
    • if no errors result from the validation, the value property is updated; page author can listen to the valueChanged event on the component to clear custom errors.

Clearing Messages

  • Only messages created by the component are cleared.
  • messagesCustom property is not cleared.

Supported Values:
Name Type Description
false boolean implies a value is not required to be provided by the user. This is the default.
true boolean implies a value is required to be provided by user and the input's label will render a required icon. Additionally a required validator - oj.RequiredValidator - is implicitly used if no explicit required validator is set. An explicit required validator can be set by page authors using the validators attribute.
Default Value:
  • false
Since:
  • 0.7
See:
Names
Item Name
Property required
Property change event requiredChanged
Property change listener attribute (must be of type function) on-required-changed
Examples

Initialize the component with the required attribute:

<oj-input-number required></oj-input-number>

Customize messages and hints used by implicit required validator when required attribute is set:

<oj-input-number required translations='{"required": {
                "hint": "custom: enter at least 3 alphabets",
                "messageSummary": "custom: \'{label}\' is Required", 
                "messageDetail": "custom: please enter a valid value for \'{label}\'"}}'>
</oj-input-number>

Get or set the required property after initialization:

// getter
var rq = myComp.required;

// setter
myComp.required = false;

(nullable) step :number

The size of the step to take when spinning via buttons or via the stepUp()/stepDown() methods. Step must be a number greater than 0, otherwise an exception is thrown. It defaults to 1.

The step up and step down feature will change the value to be a step match if it isn't already. A step match is when the value is a multiple of step, starting at the min, and if min is not set, then starting at the initial value, and if neither min or initial value are set, then starting at 0. For example, if the value is 5, min is 0, and step is 100, stepUp will change value to be 100. Now if the value is 5, min is -20, and step is 100, stepUp will change the value to be 80. If the min is not set, and the initial value is 5 and the step is 100, then the stepUp will change the value to be 105.

A value can be a step mismatch; if the value is set to be a step mismatch, it will not be flagged as a validation error.

Default Value:
  • 1
Names
Item Name
Property step
Property change event stepChanged
Property change listener attribute (must be of type function) on-step-changed
Examples

Initialize the inputNumber with the step attribute specified:

<oj-input-number step="2"></oj-input-number>

Get or set the step property after initialization:

// Getter
var step = myComponent.step;

// Setter
myComponent.step = 5;

translations :Object|null

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 the component does not contain any translatable resource, the default value of this attribute will be null. If not, an object containing all resources relevant to the component.

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

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

(nullable) translations.number-range :Object

Provides properties to customize the hint and message text used by the implicit number range validator associated to the inputNumber component.

See the translations attribute for usage examples.

Since:
  • 0.7
Names
Item Name
Property translations.numberRange

(nullable) translations.number-range.hint :Object

Provides properties to customize the hint text used by the implicit number range validator associated to the inputNumber component.

See the translations attribute for usage examples.

Since:
  • 0.7
Names
Item Name
Property translations.numberRange.hint

(nullable) translations.number-range.hint.exact :string

Hint text used by the number range validator associated to the inputNumber component. hint.exact is shown when both min and max are set and are equal to each other. This hint is used to tell the user to enter that particular number.

See the translations attribute for usage examples.

Default Value:
  • ""
Since:
  • 3.0
See:
Names
Item Name
Property translations.numberRange.hint.exact

(nullable) translations.number-range.hint.in-range :string

Hint text used by the number range validator associated to the inputNumber component. hint.inRange is shown when both min and max are set, and is used to tell the user the allowed number range.

See the translations attribute for usage examples.

Default Value:
  • ""
Since:
  • 0.7
See:
Names
Item Name
Property translations.numberRange.hint.inRange

(nullable) translations.number-range.hint.max :string

Hint text used by the number range validator associated to the inputNumber component. hint.max is shown when max is set and min is not set, and is used to tell the user the allowed maximum.

See the translations attribute for usage examples.

Default Value:
  • ""
Since:
  • 0.7
See:
Names
Item Name
Property translations.numberRange.hint.max

(nullable) translations.number-range.hint.min :string

Hint text used by the number range validator associated to the inputNumber component. hint.min is shown when min is set and max is not set, and is used to tell the user the allowed minimum.

See the translations attribute for usage examples.

Default Value:
  • ""
Since:
  • 0.7
See:
Names
Item Name
Property translations.numberRange.hint.min

(nullable) translations.number-range.message-detail :Object

Provides properties to customize the error message text used by the implicit number range validator associated to the inputNumber component.

See the translations attribute for usage examples.

Since:
  • 0.7
Names
Item Name
Property translations.numberRange.messageDetail

(nullable) translations.number-range.message-detail.exact :string

Error message text used by the number range validator associated to the inputNumber component. messageDetail.exact is shown when min and max are both set and are equal to each other, and the value is not equal to the min/max.

See the translations attribute for usage examples.

Default Value:
  • ""
Since:
  • 3.0
See:
Names
Item Name
Property translations.numberRange.messageDetail.exact

(nullable) translations.number-range.message-detail.range-overflow :string

Error message text used by the number range validator associated to the inputNumber component. messageDetail.rangeOverflow is shown when max is set, and the value is greater than the maximum.

See the translations attribute for usage examples.

Default Value:
  • ""
Since:
  • 0.7
See:
Names
Item Name
Property translations.numberRange.messageDetail.rangeOverflow

(nullable) translations.number-range.message-detail.range-underflow :string

Error message text used by the number range validator associated to the inputNumber component. messageDetail.rangeUnderflow is shown when min is set, and the value is less than the minimum.

See the translations attribute for usage examples.

Default Value:
  • ""
Since:
  • 0.7
See:
Names
Item Name
Property translations.numberRange.messageDetail.rangeUnderflow

(nullable) translations.number-range.message-summary :Object

Provides properties to customize the error message summary text used by the implicit number range validator associated to the inputNumber component.

See the translations attribute for usage examples.

Since:
  • 0.7
Names
Item Name
Property translations.numberRange.messageSummary

(nullable) translations.number-range.message-summary.range-overflow :string

Error message summary text used by the number range validator associated to the inputNumber component. messageSummary.rangeOverflow is shown when max is set, and the value is greater than the maximum.

See the translations attribute for usage examples.

Default Value:
  • ""
Since:
  • 0.7
See:
Names
Item Name
Property translations.numberRange.messageSummary.rangeOverflow

(nullable) translations.number-range.message-summary.range-underflow :string

Error message summary text used by the number range validator associated to the inputNumber component. messageSummary.rangeUnderflow is shown when min is set, and the value is less than the minimum.

See the translations attribute for usage examples.

Default Value:
  • ""
Since:
  • 0.7
See:
Names
Item Name
Property translations.numberRange.messageSummary.rangeUnderflow

(nullable) translations.required :Object

Provides properties to customize the summary, detail and hint text used by the implicit required validator associated to any editable component that supports the required option.

See the translations attribute and required option for usage examples.

Since:
  • 0.7
Names
Item Name
Property translations.required

(nullable) translations.required.hint :string

Hint text used by required validation error.

See the translations attribute for usage examples.

Default Value:
  • ""
Since:
  • 0.7
See:
Names
Item Name
Property translations.required.hint

(nullable) translations.required.message-detail :string

Message text that describes the details of the required validation error.

See the translations attribute for usage examples.

Default Value:
  • ""
Since:
  • 0.7
See:
Names
Item Name
Property translations.required.messageDetail

(nullable) translations.required.message-summary :string

Message text for summarizing a required validation error.

See the translations attribute for usage examples.

Default Value:
  • ""
Since:
  • 0.7
See:
Names
Item Name
Property translations.required.messageSummary

(nullable) translations.tooltip-decrement :string

Tooltip text for the inputNumber's Down arrow.

See the translations attribute for usage examples.

Default Value:
  • "Decrement"
Names
Item Name
Property translations.tooltipDecrement

(nullable) translations.tooltip-increment :string

Tooltip text for the inputNumber's Up arrow.

See the translations attribute for usage examples.

Default Value:
  • "Increment"
Names
Item Name
Property translations.tooltipIncrement

(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);;
};

validators :Array.<Object>|undefined

List of validators used by component when performing validation. Each item is either an instance that duck types oj.Validator, or is an Object literal containing the properties listed below. Implicit validators created by a component when certain attributes are present (e.g. required attribute), are separate from validators specified through this attribute. At runtime when the component runs validation, it combines the implicit validators with the list specified through this attribute.

Hints exposed by validators are shown in the notewindow by default, or as determined by the 'validatorHint' property set on the display-options attribute.

When validators property changes due to programmatic intervention, the component may decide to clear messages and run validation, based on the current state it is in.

Steps Performed Always

  • The cached list of validator instances are cleared and new validator hints is pushed to messaging. E.g., notewindow displays the new hint(s).

Running Validation

  • if component is valid when validators changes, component does nothing other than the steps it always performs.
  • if component is invalid and is showing messages when validators changes then all component messages are cleared and full validation run using the display value on the component.
    • if there are validation errors, then value property is not updated and the error is shown.
    • if no errors result from the validation, the value property is updated; page author can listen to the valueChanged event to clear custom errors.
  • if component is invalid and has deferred messages when validators changes, it does nothing other than the steps it performs always.

Clearing Messages

  • Only messages created by the component are cleared.
  • messagesCustom property is not cleared.

Properties:
Name Type Argument Description
type string the validator type that has a oj.ValidatorFactory that can be retrieved using the oj.Validation module. For a list of supported validators refer to oj.ValidatorFactory.
E.g., {validators: [{type: 'regExp'}]}
options Object <optional>
optional Object literal of options that the validator expects.
E.g., {validators: [{type: 'regExp', options: {pattern: '[a-zA-Z0-9]{3,}'}}]}
Names
Item Name
Property validators
Property change event validatorsChanged
Property change listener attribute (must be of type function) on-validators-changed
Examples

Initialize the component with validator object literal:

<oj-input-number validators='[{"type": "regExp", "options": {
                    "pattern": "[a-zA-Z0-9]{3,}", 
                    "messageDetail": "You must enter at least 3 letters or numbers"}}]'>
</oj-input-number>      

NOTE: oj.Validation.validatorFactory('numberRange') returns the validator factory that is used 
to instantiate a range validator for numbers.

Initialize the component with multiple validator instances:

var validator1 = new MyCustomValidator({'foo': 'A'}); 
var validator2 = new MyCustomValidator({'foo': 'B'});
var validators = [validator1,validator2];
... <oj-input-number validators='[[validators]]'> </oj-input-number>

Get or set the validators property after initialization:

// getter
var validators = myComp.validators;

// setter
myComp.validators = myValidators;

(nullable) value :number

The value of the component. Value must be a number or null.

When value property changes due to programmatic intervention, the component always clears all messages including messagesCustom, runs deferred validation, and always refreshes UI display value.

Running Validation

  • component always runs deferred validation; if there is a validation error the valid property is updated.

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

Initialize the component with the value attribute specified:

<oj-input-number value='10'></oj-input-number>

Get or set value attribute, after initialization:

// Getter: returns 10
var val = myComp.value;
// Setter: sets 20
myComp.value = 20;

virtual-keyboard :string

The type of virtual keyboard to display for entering value on mobile browsers. This attribute has no effect on desktop browsers.
Supported Values:
Name Type Description
"auto" string The component will determine the best virtual keyboard to use.

This is always "text" for this release but may change in future releases.

"number" string Use a virtual keyboard for entering number.

Note that on Android and Windows Mobile, the "number" keyboard does not contain the minus sign. This value should not be used on fields that accept negative values.

"text" string Use a virtual keyboard for entering text.
Default Value:
  • "auto"
Since:
  • 5.0.0
Names
Item Name
Property virtualKeyboard
Property change event virtualKeyboardChanged
Property change listener attribute (must be of type function) on-virtual-keyboard-changed
Examples

Initialize the component with the virtual-keyboard attribute:

<oj-input-number virtual-keyboard="number"></oj-input-number>

Get or set the virtualKeyboard property after initialization:

// Getter
var virtualKeyboard = myComp.virtualKeyboard;

// Setter
myComp.virtualKeyboard = "number";

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-input-number on-oj-animate-end='[[listener]]'></oj-input-number>

Specify an ojAnimateEnd listener via the JavaScript property:

myInputNumber.onOjAnimateEnd = listener;

Add an ojAnimateEnd listener via the addEventListener API:

myInputNumber.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 event.detail.endCallback. event.detail.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 event.detail.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
$messageComponentInlineOpenAnimation: (effect: "expand", startMaxHeight: "#oldHeight") !default;
$messageComponentInlineCloseAnimation: (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():void 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-input-number on-oj-animate-start='[[listener]]'></oj-input-number>

Specify an ojAnimateStart listener via the JavaScript property:

myInputNumber.onOjAnimateStart = listener;

Add an ojAnimateStart listener via the addEventListener API:

myInputNumber.addEventListener('ojAnimateStart', listener);

Methods

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.
Since:
  • 4.0.0
Returns:
Type
*
Example

Get a single subproperty of a complex property:

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

refresh() → {void}

Refreshes the inputNumber component

A refresh() or re-init is required when an inputNumber is changed in a non-option way, like in the following circumstances:

  • Button translations change.

Returns:
Type
void
Example

Invoke the refresh method:

myComp.refresh();

reset() → {void}

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
Returns:
Type
void
Example

Reset component

myComp.reset(); 

setProperties(properties) → {void}

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

Set a batch of properties:

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

setProperty(property, value) → {void}

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.
Since:
  • 4.0.0
Returns:
Type
void
Example

Set a single subproperty of a complex property:

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

showMessages() → {void}

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
Returns:
Type
void
Example

Display all messages including deferred ones.

myComp.showMessages();

stepDown(steps) → {void}

Decrements the value by the specified number of steps. Without the parameter, a single step is decremented.

If the resulting value is above the max, below the min, or results in a step mismatch, the value will be adjusted to the closest valid value.

Parameters:
Name Type Argument Description
steps number <optional>
Number of steps to decrement, defaults to 1.
Returns:
Type
void
Example

Invoke the stepDown method:

myComp.stepDown();

stepUp(steps) → {void}

Increments the value by the specified number of steps. Without the parameter, a single step is incremented.

If the resulting value is above the max, below the min, or results in a step mismatch, the value will be adjusted to the closest valid value.

Parameters:
Name Type Argument Description
steps number <optional>
Number of steps to increment, defaults to 1.
Returns:
Type
void
Example

Invoke the stepUp method:

myComp.stepUp();

validate() → {Promise.<string>}

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

Validates the component's display value using the converter and all validators registered on the component and updates the value option by performing the following steps.

  1. All messages are cleared, including custom messages added by the app.
  2. If no converter is present then processing continues to next step. If a converter is present, the UI value is first converted (i.e., parsed). If there is a parse error then the messages are shown.
  3. If there are no validators setup for the component the value option is updated using the display value. Otherwise all validators are run in sequence using the parsed value from the previous step. The implicit required validator is run first if the component is marked required. When a validation error is encountered it is remembered and the next validator in the sequence is run.
  4. At the end of validation if there are errors, the messages are shown. If there were no errors, then the value option is updated.

Since:
  • 4.0.0
Returns:
Promise resolves to "valid" if there were no converter parse errors and the component passed all validations. The Promise resolves to "invalid" if there were converter parse errors or if there were validation errors.
Type
Promise.<string>
Examples

Validate component using its current value.

// validate display value and shows messages if there are any to be shown.
myComp.validate();

Validate component and use the Promise's resolved state.

myComp.validate().then(
 function(result) {
   if(result === "valid")
   {
     submitForm();
   }
 });