Element: <oj-c-input-time-mask>

CORE PACK

Oracle® JavaScript Extension Toolkit (JET)
19.0.0
G25385-01

Since:
  • 19.0.0
Module:
  • input-time-mask

QuickNav

Attributes

Methods

Type Definitions

Documentation-only Types

Other Topics


JET Input Time Mask Component

Description: A JET Input Time Mask allows a user to individually edit, step, or spin the values of the hour, minute, second, and millisecond fields of a time.

<oj-c-input-time-mask label-hint="Time"></oj-c-input-time-mask>

Validation and Messaging

For components that support validators, any invalid values entered by the user are not pushed into the value if validation fails: the valid property will change but the original value will remain unchanged. The same thing applies to required validation: if required is set to true and the user clears the field, valid will change, but empty values will not be pushed so the original value remains unchanged.

Use <oj-validation-group> to handle tracking valid across multiple components.

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 (this includes async-validators) set on the component (for components that support these properties), 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 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.
      • 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 async-validators, those errors are shown as soon as they come in, and not until all validators, sync and async validators, are complete, does processing return, that is, value and valid are updated. 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 is 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 converter property (if available) changes.
  • when required property changes. See required property for details.
  • when validators property changes (for components that support validators). See validators property for details.

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.

User Assistance Text

User assistive text provides guidance to help the user understand what data to enter or select.

By default all user assistance text shows inline. For input components, it shows when the field takes focus. In other components it shows all the time. See the user-assistance-density property for other ways the user assistance text can render, like in 'compact' mode, it will render as an icon on the label which when clicked will show the user assistance text in a notewindow.

The JET form component properties that are used for user assistance text are help.instruction, validator and converter hints (for components that support these properties), and help-hints. In the Redwood theme for clarity only one user assistance text shows to the user. The precedence rules are:

  • help.instruction shows;
  • if no help.instruction, then validator hint shows;
  • if no help.instruction or validator hint, then help-hints.definition shows;
  • if no help.instruction, validator hint, or help-hints.definition, then converter hint shows.
  • help-hints.source always shows along side the above.

For components that support validators or converters, sometimes a hint shows that you do not want to show. To not show it, set the display-options.validator-hint and/or display-options.converter-hint property to 'none'.

required property can be used to guide the user. In Redwood, a required field shows the word Required under the field when the field is empty and does not have focus. The mask placeholder is shown when the field is empty and has focus. The mask placeholder is not configurable.

Touch End User Information

Target Gesture Action
Field (Not a Segment) Tap Sets focus to first segment. Show user assistance text.
Segment Tap Sets focus to segment. Show user assistance text.
Segment Double Tap If the time is complete, selects the entire time. Hitting backspace clears it.
Day Period Segment Tap Sets focus to the day period segment. Type the first letter of the desired day period to select it. The 'AM'/'PM' string is localized to the user's locale. For example, in locale 'en-US', 'A' sets the day period segment to 'AM' and 'P' sets the day period segment to 'PM'. If the localized 'AM'/'PM' strings start with the same letter, then typing the first letter will toggle between them.

Keyboard End User Information

Target Key Action
Field Tab In Sets focus to first segment. Show user assistance text.
Field Ctrl + A or Command + A If the time is complete, selects the entire time. Double clicking on the field also selects the time.
Field with time selected Backspace/Delete Backspace or delete key clears the time. The mask placeholders will be shown again and focus will be on the first segment.
Time Segment Backspace/Delete Clears the time segment. Focus remains on the time segment.
Time Segment RightArrow Moves focus to the segment on the right. If focus is on the rightmost segment, the focus does not move.
Time Segment LeftArrow Moves focus to the segment on the left. If focus is on the leftmost segment, the focus does not move.
Hour Segment UpArrow/DownArrow

Increments or decrements the number by one in the segment. The value wraps around when it reaches the minimum or maximum allowed for the segment.

If there is no number in the segment, and the time is a 12-hour clock, it initializes the hour segment to 12, and auto-fills any empty segments; minute, second and millisecond to 0, and the dayPeriod segment to AM (the string will be localized to the user's locale).

If there is no number in the segment, and the time is a 24-hour clock, it initializes the hour segment to 0, and auto-fills any empty segments to 0.

Minute, Second, or Millisecond Segment UpArrow/DownArrow Increments or decrements the number by one in the segment. The value wraps around when it reaches the minimum or maximum allowed for the segment. If there is no number in the segment, it initializes the segment to 0.
Day Period Segment UpArrow/DownArrow Toggles the day period. If the day period is empty, it initializes it to AM (the 'AM'/'PM' string is localized to the user's locale).
Hour Segment End

Sets the segment to the maximum number for the segment, and auto-fills the rest of the empty segments; sets minute, second and millisecond segments to 0, and the dayPeriod segment to AM (the 'AM'/'PM' string is localized to the user's locale).

For example, if on the hour segment for a 12-hour clock with granularity="minute", and all segments are empty, this will set the hour to 12, and minute to 0, and day period to AM. If on the hour segment for a 24-hour clock with granularity="minute", and all segments are empty, this will set the hour to 23 and minute to 0.

Minute, Second, or Millisecond Segment End Sets the segment to the maximum number for the segment.
Day Period Segment End Sets the segment to the maximum value for the segment which is PM for the day period segment (the 'AM'/'PM' string is localized to the user's locale).
Hour Segment Home

Sets the segment to the minimum number for the segment, and auto-fills the rest of the empty segments; minute, second and millisecond segments to 0, and the dayPeriod segment to AM (the 'AM'/'PM' string is localized to the user's locale).

For example, if on the hour segment for a 12-hour clock with granularity="minute", and all segments are empty, this will set the hour to 1, and minute to 0, and day period to AM. If on the hour segment for a 24-hour clock with granularity="minute", and all segments are empty, this will set the hour to 0 and minute to 0.

Minute, Second, or Millisecond Segment Home Sets the segment to the minimum number for the segment which is 0 for the minute, second, and millisecond segments.
Day Period Segment Home Sets the segment to the minimum value for the segment which is AM for the day period segment (the 'AM'/'PM' string is localized to the user's locale).
Hour Segment Page Up/Page Down

Increments or decrements the number by two in the hour segment, and auto-fills the rest of the empty segments; minute, second and millisecond segments to 0, and the dayPeriod segment to AM (the 'AM'/'PM' string is localized to the user's locale). The value wraps around when it reaches the minimum or maximum allowed for the segment.

If there is no number in the segment, and the time is a 12-hour clock, it initializes the hour segment to 12, and auto-fills any empty segments; minute, second and millisecond to 0, and the dayPeriod segment to AM (the string will be localized to the user's locale).

If there is no number in the segment, and the time is a 24-hour clock, it initializes the hour segment to 0, and auto-fills any empty segments to 0.

Minute, Second, or Millisecond Segment Page Up/Page Down Increments or decrements the number by 10 in the minute and second segments, or by 100 in the millisecond segment. The value wraps around when it reaches the minimum or maximum allowed for the segment.
Day Period Segment Page Up/Page Down Toggles the day period segment between AM and PM (the 'AM'/'PM' string is localized to the user's locale).

Accessibility

For accessibility, set the label-hint property. If there is no visible label, then to make this accessible to screen reader users, set the label-hint and label-edge='none' which renders an aria-label with the label-hint text.

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.


Usage

Signature:

interface CInputTimeMaskElement

Typescript Import Format
//To typecheck the element APIs, import as below.
import { CInputTimeMaskElement } from "oj-c/input-time-mask";

//For the transpiled javascript to load the element's module, import as below
import "oj-c/input-time-mask";

For additional information visit:

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.


Attributes

column-span :number

Specifies how many columns this component should span. This only takes effect when this component is a child of a form layout that has direction 'row'.
Default Value:
  • 1
Names
Item Name
Property columnSpan
Property change event columnSpanChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-column-span-changed

container-readonly :boolean

Specifies whether an ancestor container, like oj-c-form-layout, is readonly. This affects whether a readonly component renders in full or mixed readonly mode.
Names
Item Name
Property containerReadonly
Property change event containerReadonlyChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-container-readonly-changed

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 valueChanged 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
Names
Item Name
Property disabled
Property change event disabledChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-disabled-changed

display-options :oj-c.InputTimeMask.DisplayOptionsProps

Display options for auxiliary content that determines whether or not it should be displayed.
Names
Item Name
Property displayOptions
Property change event displayOptionsChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-display-options-changed

granularity :"minute"|"second"|"millisecond"

Specifies the smallest time unit that is displayed by the component. If set to minute, only hour and minute are shown. If set to second then hour, minute, and second are shown. If set to millisecond then hour, minute, second and millisecond are shown.
Default Value:
  • "minute"
Names
Item Name
Property granularity
Property change event granularityChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-granularity-changed

help :oj-c.InputTimeMask.Help

Form component help information.
Names
Item Name
Property help
Property change event helpChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-help-changed

help-hints :oj-c.InputTimeMask.HelpHints

The helpHints object contains a definition property and a source property.
Names
Item Name
Property helpHints
Property change event helpHintsChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-help-hints-changed

hour-clock :"12"|"24"|"fromLocale"

Specifies whether to display the time as a 12-hour clock with a day period or a 24-hour clock. By default this is 'fromLocale' which means the hour clock is determined by the user's locale.
Default Value:
  • "fromLocale"
Names
Item Name
Property hourClock
Property change event hourClockChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-hour-clock-changed

label-edge :"inside"|"none"|"start"|"top"

Specifies how the label of the component is positioned when the label-hint attribute is set on the component.
Supported Values:
Value Description
inside The label floats over the input element, but moves up on focus or when the component has a value (default, if unspecified).
none The component will not create a label, but instead set the aria-label property on the input element.
start The label will be placed before the start of the component.
top The label will be placed on top of the component.
Names
Item Name
Property labelEdge
Property change event labelEdgeChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-label-edge-changed

label-hint* :string

Represents a hint for rendering a label on the component. This is used in combination with the label-edge attribute to control how the label should be rendered.
Names
Item Name
Property labelHint
Property change event labelHintChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-label-hint*-changed

label-start-width :(number|string)

The width of the label when labelEdge is 'start'.

This attribute accepts values of type 0 | `--${string}` | `${number}%` | `${number}x` | `calc(${string})`

Names
Item Name
Property labelStartWidth
Property change event labelStartWidthChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-label-start-width-changed

label-wrapping :"truncate"|"wrap"

Should the labels wrap or truncate when there is not enough available space.
Deprecated:
Since Description
19.0.0 Label truncation for 'start' and 'top' aligned labels is no longer recommended by the Redwood Design System. The default for labelWrapping was 'wrap' and that is now the only suggested pattern by UX design for 'start' and 'top' aligned labels. 'inside' aligned labels are always truncated per UX design and are not affected by this property's value.
Supported Values:
Value Description
truncate Label will truncate if needed.
wrap Label will wrap if needed.
Names
Item Name
Property labelWrapping
Property change event labelWrappingChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-label-wrapping-changed

leading-zero-for-hour :"hide"|"show"|"fromLocale"

Specifies whether to always show a leading zero in the hour field when the hour is 1-digit, or to never show a leading zero in the hour field when the hour is 1-digit. By default this is 'fromLocale' which means it is determined by the user's locale.
Default Value:
  • "fromLocale"
Names
Item Name
Property leadingZeroForHour
Property change event leadingZeroForHourChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-leading-zero-for-hour-changed

max :(string|null)

The maximum selectable time in ISO format. The time the user enters must be less than or equal to the max time, otherwise the user will see an error. This must be a time only ISO string with no date, otherwise an error is thrown and the component will not render. When set to null, there is no maximum.
Names
Item Name
Property max
Property change event maxChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-max-changed

max-width :(number|string|"sm"|"md")

Specifies the component's max width. If unset, the default max width is 100%.
Supported Values:
Value
md
sm
Names
Item Name
Property maxWidth
Property change event maxWidthChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-max-width-changed

messages-custom :Array.<oj-c.InputTimeMask.ComponentMessageItem>

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.

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
Names
Item Name
Property messagesCustom
Property change event messagesCustomChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-messages-custom-changed

min :(string|null)

The minimum selectable time in ISO format. The time the user enters must be greater than or equal to the min time, otherwise the user will see an error. This must be a time only ISO string with no date, otherwise an error is thrown and the component will not render. When set to null, there is no minimum.
Names
Item Name
Property min
Property change event minChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-min-changed

(readonly) raw-value :oj-c.InputTimeMask.Time

The rawValue is the read-only property for retrieving the current displayed value from the component.

The rawValue updates when the user types into the field, so the rawValue changes as the value of the field is changed, whether or not it is valid. If the user types '10' into the hour field in an otherwise empty field with granularity='minute', the rawValue will be {hour:1, minute:undefined}, then {hour:10, minute:0}. When the hour is complete, the rest of the segments auto-fill to 0, which is why the minute property is set to 0. When the user blurs or presses Enter the rawValue property gets parsed into an time only ISO string (an error is thrown if the time is not complete), and the time only ISO string gets validated. If valid, the value property gets updated with the time only ISO string.

If the user clears the field, rawValue is undefined.

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

Supports writeback:
  • true
Names
Item Name
Property rawValue
Property change event rawValueChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-raw-value-changed

readonly :boolean

Whether the component is readonly. The readonly property sets or returns whether an element is readonly, or not. A readonly element cannot be modified. However, a user can tab to it, highlight it, focus on it, and copy the text from it. If you want to prevent the user from interacting with the element, use the disabled property instead.

If the property value is not set either directly on the component or inherited from a parent form layout, then the property is treated as if its value were false.

Names
Item Name
Property readonly
Property change event readonlyChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-readonly-changed

readonly-user-assistance-shown :"none"|"confirmationAndInfoMessages"

Specifies which user assistance types should be shown when the component is readonly.

Default Value:
  • "none"
Names
Item Name
Property readonlyUserAssistanceShown
Property change event readonlyUserAssistanceShownChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-readonly-user-assistance-shown-changed

required :boolean

This property set to false implies that a value is not required to be provided by the user. This is the default. This property set to true implies that a value is required to be provided by the user.

In the Redwood theme, by default, a Required text is rendered inline when the field is empty. If user-assistance-density is 'compact', it will show on the label as an icon.

The Required error text is based on Redwood UX designs, and it is not recommended that it be changed. To override the required error message, use the required-message-detail attribute. The component's label text is passed in as a token {label} and can be used in the message detail.

When required is set to true, an implicit required validator is created, i.e., new RequiredValidator(). The required validator is the only validator to run during initial render, and its error is not shown to the user at this time; this is called deferred validation. The required validator also runs during normal validation; this is when the errors are shown to the user. See the Validation and Messaging section for details.

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

Running Validation when required property changes

  • if component is valid when required is set to true, then it runs deferred validation on the value property. If the field is empty, the valid state is invalidHidden. No errors are shown to the user.
  • if component is valid when required is set from true to false, then no validation is run.
  • if component is invalid and has deferred messages (invalidHidden) when required is set to false, then component messages are cleared (messages-custom messages are not cleared) but no deferred validation is run because required is false.
  • if component is invalid and currently showing invalid messages (invalidShown) when required is changed to either true or false, 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 when required property changes

  • Only messages created by the component, like validation messages, are cleared when the required property changes.
  • messagesCustom property is not cleared.

Default Value:
  • false
Names
Item Name
Property required
Property change event requiredChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-required-changed

required-message-detail :string

The component-specific message detail when the required validation fails. If the component needs a required validation error message that is different from the default, set this property. It should be a translated string.

Names
Item Name
Property requiredMessageDetail
Property change event requiredMessageDetailChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-required-message-detail-changed

text-align :"start"|"end"|"right"

Specifies how the text is aligned within the text field
Supported Values:
Value Description
end Aligns text right when reading direction is ltr and left when reading direction is rtl.
right Aligns text right regardless of reading direction, often used for numbers.
start Aligns text left when reading direction is ltr and right when reading direction is rtl (default, if unspecified).
Names
Item Name
Property textAlign
Property change event textAlignChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-text-align-changed

time-range-overflow-message-detail :(p: oj-c.InputTimeMask.OverflowMessageDetailParameters) => string

A callback function that returns a component-specific message detail when the time range validation fails when user's input is greater than the max. If the component needs a validation error message for overflow that is different from the default, set this property. The function should return a translated string.

Usage:
timeRangeOverflowMessageDetail = (p: { value: string; max: string }) => `The time ${p.value} needs to be on or before ${p.max}.`
timeRangeOverflowMessageDetail = (p: {max: string }) => `The time needs to be on or before ${p.max}.`
timeRangeOverflowMessageDetail = () => `The time is out of range.`
Names
Item Name
Property timeRangeOverflowMessageDetail
Property change event timeRangeOverflowMessageDetailChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-time-range-overflow-message-detail-changed

time-range-underflow-message-detail :(p: oj-c.InputTimeMask.UnderflowMessageDetailParameters) => string

A callback function that returns a component-specific message when the time range validation fails when the user's input is less than the min. If the component needs a validation error message for underflow that is different from the default, set this property. The function should return a translated string.

Usage:
timeRangeUnderflowMessageDetail = (p: { value: string; min: string }) => `The time ${p.value} needs to be on or after ${p.min}.`
timeRangeUnderflowMessageDetail = (p: {min: string }) => `The time is too low. Min limit is ${p.min}.`
timeRangeUnderflowMessageDetail = () => `The time is out of range.`
Names
Item Name
Property timeRangeUnderflowMessageDetail
Property change event timeRangeUnderflowMessageDetailChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-time-range-underflow-message-detail-changed

user-assistance-density :"reflow"|"efficient"|"compact"

Specifies the density of the form component's user assistance presentation. It can be shown inline with reserved rows to prevent reflow if a user assistance text shows up, inline without reserved rows that would reflow if a user assistance text shows up, or it can be shown compactly in a popup instead.

If the property value is not set either directly on the component or inherited from a parent form layout, then the property is treated as if its value were "reflow".

Supported Values:
Value Description
compact Messages, help, hints, and required will not be shown inline; they will show in a mode that keeps the screen more compact, like a popup for the messages, and a required icon to indicate Required.
efficient Messages, help, hints, and required are all shown inline under the field with reserved space.
reflow Messages, help, hints, and required are all shown inline under the field with no reserved space.
Names
Item Name
Property userAssistanceDensity
Property change event userAssistanceDensityChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-user-assistance-density-changed

(readonly) valid :"valid"|"pending"|"invalidHidden"|"invalidShown"

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

  • after each validator (validators or async-validators) 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:
Value Description
invalidHidden The component has invalid messages hidden and no invalid messages showing. An invalid message is one with severity 'error'.
invalidShown The component has invalid messages showing. An invalid message is one with severity 'error'.
pending The component is waiting for the validation state to be determined. The 'pending' state is set at the start of the validation process.
valid The component is valid
Supports writeback:
  • true
Names
Item Name
Property valid
Property change event validChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-valid-changed

validators :Array<AsyncValidator<string>|Validator<string>>|null

List of validators, synchronous or asynchronous, used by the component when performing validation. Each item is either an instance that duck types oj.Validator or oj.AsyncValidator.

At runtime when the component runs validation, it combines all the validators specified through this validators attribute and the async-validators attribute, and runs all of them.

Hints exposed by validators are shown inline by default in the Redwood theme when the field has focus. You can turn off showing validator hints by using the 'validatorHint' property set to 'none' on the display-options attribute.

In the Redwood theme, only one hint shows at a time, so the precedence rules are: help.instruction shows; if no help.instruction then validator hints show; if none, then help-hints.definition shows; if none, then converter hint shows. help-hints.source always shows along with the other help or hint.

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.

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 or async-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.

Default Value:
  • []
Names
Item Name
Property validators
Property change event validatorsChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-validators-changed

value :(string|null)

The value of the component.

The value must be a local time (no date) ISO string such as 'T01:45', otherwise the component will throw an error. If needed, use IntlConverterUtils.offsetTimeToLocalIsoTimeString(value, date, timeZone) to convert a time with an offset to a local ISO string that contains only the time to set as the initial value.

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.

When the input field is cleared and the value is committed, the value property is set to null.

Running Validation

  • component always runs deferred validation; the valid property is updated with the result.
Default Value:
  • null
Supports writeback:
  • true
Names
Item Name
Property value
Property change event valueChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-value-changed

width :(number|string|"sm"|"md")

Specifies the component's width. If unset, the default width is 100%. Note that by default max-width is 100%, which will override the width if the container is smaller than the width specified.
Supported Values:
Value
md
sm
Names
Item Name
Property width
Property change event widthChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-width-changed

Methods

getProperty(property) : {any}

Retrieves the value of a property or a subproperty.
Parameters:
Name Type Description
property string The property name to get. Supports dot notation for subproperty access.
Returns:
Type
any

reset : {void}

Resets the component by clearing all messages and messagesCustom attribute and updates the component's display value using the attribute value. User entered values will be erased when this method is called.
Returns:
Type
void

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

setProperty(property, value) : {void}

Sets a property or a single subproperty for complex properties and notifies the component of the change, triggering a corresponding event.
Parameters:
Name Type Description
property string The property name to set. Supports dot notation for subproperty access.
value any The new value to set the property to.
Returns:
Type
void

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

validate : {Promise}

If enabled, validates the component's display value using the component's implicit 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 the UI display value is empty, then the component normalizes the value to null.
  3. If the normalized value is null, then processing continues to next step. Otherwise, the UI value is first converted (i.e., parsed). If there is a parse error (e.g., the field does not contain an hour) then the message is shown and processing stops.
  4. If required is true, the implicit required validator is run. If the required validator throws an error, the message is shown.
  5. If there are no other validators registered on the component, or if the UI display value is empty, the value option is updated. Otherwise all validators are run in sequence using the parsed value from the previous step. When a validation error is encountered it is remembered and the next validator in the sequence is run.
  6. At the end of validation if there are errors, the messages are shown. If there were no errors, then the value option is updated.

If the component is readonly or disabled, returns a Promise that resolves to 'valid' without doing any validation.

Returns:

Promise resolves to "valid" if there were no converter parse errors and the component passed all validations. The Promise resolves to "valid" if the component is disabled or readonly. The Promise resolves to "invalid" if there were converter parse errors or if there were validation errors

Type
Promise

Type Definitions

Documentation-only Types

Note: Type definitions in this section have been provided for documentation purposes and cannot be imported into application code.

ComponentMessageItem

A type for a single component message
Properties:
Name Type Argument
detail string <optional>
severity "error" | "confirmation" | "info" | "warning" <optional>
summary string <optional>

DisplayOptionsProps

Display options for auxiliary content that determines whether or not it should be displayed.
Properties:
Name Type Argument Default Description
messages "none" | "display" <optional>
 "display" Display options for auxiliary message text.
validatorHint "none" | "display" <optional>
 "display" Display options for auxiliary validator hint text.

Help

Form component help information.
Properties:
Name Type Argument Description
instruction string <optional>
 A type of user assistance text. User assistance text is used to provide guidance to help the user understand what data to enter or select.

HelpHints

The helpHints object contains a definition property and a source property.
Properties:
Name Type Argument Description
definition string <optional>
 A type of user assistance text. User assistance text is used to provide guidance to help the user understand what data to enter or select. help-hints could come from a help system.
source string <optional>
 Help source URL associated with the component.
sourceText string <optional>
 Custom text to be used for the source link.

OverflowMessageDetailParameters

Parameters that are passed into the timeRangeOverflowMessageDetail callback function.
Properties:
Name Type Description
max string The maximum allowed value.
value string The value entered by the user.

Time

Properties:
Name Type Argument
hour number <optional>
millisecond number <optional>
minute number <optional>
second number <optional>

UnderflowMessageDetailParameters

Parameters the are passed into the timeRangeUnderflowMessageDetail callback function.
Properties:
Name Type Description
min string The minimum allowed value.
value string The value entered by the user.