Usage
Signature:
interface CInputDateTextElement
Typescript Import Format
//To typecheck the element APIs, import as below.
import { CInputDateTextElement } from "oj-c/input-date-text";
//For the transpiled javascript to load the element's module, import as below
import "oj-c/input-date-text";
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.
Global Attributes
Note: In addition to the component's custom attributes, the following global attributes are also supported by this component (note the differences in data binding syntax between component and global attributes described here)
-
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.
Names
Item Name Property autofocus
Property change event autofocusChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-autofocus-changed
Attributes
-
autocomplete :string
-
Dictates component's autocomplete state. This attribute indicates whether the value of the control can be automatically completed by the browser. The common values are 'on' and 'off'. Since this attribute passes through to the input element unchanged, you can look at the html specs for detailed information for how browsers behave and what values besides 'on' and 'off' you can set. The html spec says the default is 'on', so when autocomplete is not explicitly set, the browsers treat it as 'on'.
- Default Value:
"on"
Names
Item Name Property autocomplete
Property change event autocompleteChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-autocomplete-changed
-
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
-
converter :(oj-c.InputDateText.DateConverter|null)
-
If no converter is specified, the default is to use
new LocalDateConverter({ dateStyle: 'short' })
.When
converter
property changes due to programmatic intervention, the element performs various tasks based on the current state it is in.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 element is valid when
converter
property changes, the display value is refreshed. - if element is invalid and is showing messages when
converter
property changes then all element messages are cleared and full validation run using the current display value on the element.- if there are validation errors, then
value
property is not updated, and the error is shown. The display value is not refreshed in this case. - if no errors result from the validation, the
value
property is updated; page author can listen to thevalueChanged
event to clear custom errors. The display value is refreshed with the formatted value provided by converter.
- if there are validation errors, then
- if element is invalid and has deferred messages when converter property changes, the display value is again refreshed with the formatted value provided by converter.
Clearing Messages
- Only messages created by the element are cleared.
messagesCustom
property is not cleared. Page authors can choose to clear it explicitly when setting the converter option.
During validation, the converter takes the input value which is a string and parses it into the type of the component's value property (e.g. a number) before it passes it to the validator. It then takes the validated value property and formats it into a string to be displayed and puts it into the input. If the converter's format or parse functions throw an error, it will be displayed to the user inline on the field.
The hint exposed by the converter is shown inline by default in the Redwood theme when the field has focus. You can turn off showing converter hints by using the 'converterHint' 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.
The default converter is an instance of LocalDateConverter(). LocalDateConverter has a dateStyle option which can be set to 'short', 'medium', 'long', or 'full'.
- Default Value:
null
Names
Item Name Property converter
Property change event converterChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-converter-changed
-
date-range-overflow-message-detail :string
-
The component-specific message detail when the date range validation fails when the input value is greater than the max. If the component needs a date range validation error message for overflow that is different from the default, set this property. It should be a translated string.
Tokens:
{value} - value entered by the user
{max} - the maximum allowed valueUsage:
The date must be less than or equal to {max}.Names
Item Name Property dateRangeOverflowMessageDetail
Property change event dateRangeOverflowMessageDetailChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-date-range-overflow-message-detail-changed
-
date-range-underflow-message-detail :string
-
The component-specific message detail when the date range validation fails when the input value is less than the min. If the component needs a date range validation error message for underflow that is different from the default, set this property. It should be a translated string.
Tokens:
{value} - value entered by the user
{min} - the minimum allowed valueUsage:
The date must be greater than or equal to {min}.Names
Item Name Property dateRangeUnderflowMessageDetail
Property change event dateRangeUnderflowMessageDetailChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-date-range-underflow-message-detail-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 thevalueChanged
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.
- if component is invalid and showing messages then all component messages are cleared,
and full validation run using the display value.
- 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
- when a required component is initialized as disabled
-
display-options :oj-c.InputDateText.DisplayOptions
-
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
-
help :oj-c.InputDateText.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.InputDateText.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
-
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.
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
-
max :(string|null)
-
The maximum selectable date, in date only ISO string format. The date the user enters must be less than or equal to the max date, otherwise the user will see an error. This must be a date only ISO string with no time, 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
-
messages-custom :Array.<oj-c.InputDateText.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 date, in date only ISO string format. The date the user enters must be greater than or equal to the min date, otherwise the user will see an error. This must be a date only ISO string with no time, 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 :string
-
The
rawValue
is the read-only property for retrieving the current value from the input field in string form. The main consumer ofrawValue
is a converter.The
rawValue
updates on the 'input' javascript event, so therawValue
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'. When the user blurs or presses Enter therawValue
property gets parsed into an date only ISO string (an error is thrown if the date is not complete), and the date only ISO string gets validated. If valid, thevalue
property gets updated.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
-
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 totrue
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 thevalueChanged
event on the component to clear custom errors.
- if there are validation errors, then
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
-
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.
- Supports writeback:
true
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 convert/validate process. valid
The component is valid 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 and the implicit component validators when performing validation. Each item is either an instance that duck types oj.Validator or oj.AsyncValidator.
Implicit validators are created by the element when certain attributes are present. For example, if the
required
attribute is set, an implicit oj.RequiredValidator is created. If the min and/or max attribute is set, an implicit oj.LocalDateRangeValidator is created. At runtime when the component runs validation, it combines all the implicit validators with all the validators specified through thisvalidators
attribute and theasync-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
orasync-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 thevalueChanged
event to clear custom errors.
- if there are validation errors, then
- 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 date (no time) ISO string such as '2021-03-14', otherwise the component will throw an error.
If needed, use IntlConverterUtils.dateToLocalIsoDateString to convert a Date to a local ISO string that contains only the date to set as the initial value. IntlConverterUtils.dateToLocalIsoDateString(new Date(2014, 1, 1)));
When
value
property changes due to programmatic intervention, the component always clears all messages includingmessagesCustom
, 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 tonull
.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
- component always runs deferred validation; the
Methods
-
getProperty(property) : {any}
-
Retrieves the value of a property or a subproperty.
Parameters:
Name Type Description property
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
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
The property name to set. Supports dot notation for subproperty access. value
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 converter and all validators registered on the component and updates the value option by performing the following steps.
- All messages are cleared, including custom messages added by the app.
- If the UI display value is empty, then the component normalizes the value to null.
- If no converter is present, or 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 then the messages are shown and processing stops.
- If required is true, the implicit required validator is run. If the required validator throws an error, the message is shown.
- If there are no other validators registered on the component, or if the UI display value is empty, the value option is updated using the display value (an empty field's display value is null). 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.
- 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
-
ComponentMessageItem
-
A type for a single component message
Properties:
Name Type Argument detail
string <optional>
severity
"error" | "confirmation" | "info" | "warning" <optional>
summary
string <optional>
-
DateConverter
-
This converter object has two fields:
format
is a function of type(value: DateISOString) => string
parse
is a function of type(value: string) => DateISOString
Properties:
Name Type format
(value: V): string parse
(value: string): V -
DisplayOptions
-
Display options for auxiliary content that determines whether or not it should be displayed.
Properties:
Name Type Argument Default Description converterHint
"none" | "display" <optional>
"display" Display options for auxiliary converter hint text. 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.