Usage
Signature:
interface InputDateTimeElement<SP extends ojInputDateTimeSettableProperties = ojInputDateTimeSettableProperties>
Typescript Import Format
//To typecheck the element APIs, import as below.
import { InputDateTimeElement } from "ojs/ojdatetimepicker";
//For the transpiled javascript to load the element's module, import as below
import "ojs/ojdatetimepicker";
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.
Styling Classes
-
.oj-form-control-full-width
-
Changes the max-width to 100% so that form components will occupy all the available horizontal space.
Example
<oj-input-date-time class="oj-form-control-full-width"> </oj-input-date-time>
-
Category: Max Width
-
Note: This category of style classes is not supported in the following themes:
Alta
In the Redwood theme the default max width of a text field is 100%. These max width convenience classes are available to create a medium or small field.
The class is applied to the root element.Classes:
-
.oj-form-control-max-width-sm
-
.oj-form-control-max-width-md
Example
<oj-input-date-time class="oj-form-control-max-width-md"></oj-input-date-time>
-
-
Category: Width
-
Note: This category of style classes is not supported in the following themes:
Alta
In the Redwood theme the default width of a text field is 100%. These width convenience classes are available to create a medium or small field.
The class is applied to the root element.Classes:
-
.oj-form-control-width-sm
-
.oj-form-control-width-md
Example
<oj-input-date-time class="oj-form-control-width-md"></oj-input-date-time>
-
-
Category: Text Alignment
-
Classes that help align text of the element.
Classes:
-
.oj-form-control-text-align-right
-
.oj-form-control-text-align-start
-
.oj-form-control-text-align-end
Example
<oj-input-date-time class="oj-form-control-text-align-right"> </oj-input-date-time>
-
Slots
JET components that allow child content support slots. Please see the slots section of the JET component overview doc for more information on allowed slot content and slot types.
-
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 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.
- Deprecated:
-
Since Description 13.0.0
This web component no longer supports launching a context menu.
Attributes
-
async-validators :Array.<oj.AsyncValidator.<V>>
-
List of asynchronous validators used by the component when performing validation. Use
async-validators
when you need to perform some validation work on the server. Otherwise, usevalidators
, which are synchronous.Each item in the Array is an instance that duck types oj.AsyncValidator. Implicit validators created by a component when certain attributes are present (e.g.
required
attribute) are separate from validators specified through theasync-validators
attribute and thevalidators
attribute. At runtime when the component runs validation, it combines the implicit validators with the list specified through thevalidators
attribute and also the list specified through theasync-validators
attribute. Error messages are shown as soon as each async validator returns; we do not wait until all the async validators finish to show errors. If the component's valid state changes for the worse, it is also updated as each validator returns so valid will be invalidShown as soon as the first validator has an Error.It is recommended that you show the value you are validating in the error message because if the async operation takes a while, the user could be typing in a new value when the error message comes back and might be confused what value the error is for. However, if the user enters a new value (like presses Enter or Tab), a new validation lifecycle will start and validation errors for the previous value will not be shown to the user. If you need to format the value for the error message, you can use e.g. for number
new NumberConverter.IntlNumberConverter(converterOption)
to get the converter instance, then callconverter.format(value)
.Hints exposed by validators are shown inline by default in the Redwood theme when the field has focus. In the Alta theme, validator hints are shown in a notewindow on focus, or as determined by the 'validatorHint' property set on the
display-options
attribute. In either theme, you can turn off showing validator hints by using the 'validatorHint' property set to 'none' on thedisplay-options
attribute.Since async validators are run asynchronously, you should wait on the BusyContext before you check valid property or the value property. Alternatively you can add a callback to the validChanged or valueChanged events.
The steps performed always, running validation and clearing messages is the same as for the
oj.inputBase#validators
attribute.
- Deprecated:
-
Since Description 8.0.0
Use the validators property instead for either regular Validators or AsyncValidators.
- Default Value:
[]
Names
Item Name Property asyncValidators
Property change event asyncValidatorsChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-async-validators-changed
-
autocomplete :"on"|"off"|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".
- Deprecated:
-
Since Description 17.0.0
The date field contains mask segments instead of a general input, so autocomplete is not supported.
- Default Value:
"off"
- Since:
- 17.0.0
- See:
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
-
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.
- Deprecated:
-
Since Description 17.0.0
This is not recommended for accessibility reasons.
- Default Value:
false
- Since:
- 17.0.0
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
-
converter :(Promise.<oj.Converter.<any>>|oj.Converter.<any>|oj.Validation.RegisteredConverter) converter :oj.Converter.<any>
-
A datetime converter instance or one that duck types oj.DateTimeConverter.
The default options for converter vary by theme. To use different value for options, create a custom converter and set it in this property. For example:
inputDateTime.converter = new DateTimeConverter.IntlDateTimeConverter({formatType: 'datetime',dateFormat: 'short',timeFormat: 'short'});
If the timezone option is provided in the converter, the Today button will highlight the current day based on the timezone specified in the converter.
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.
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.
- Deprecated:
-
Since Value Description 8.0.0
oj.Validation.RegisteredConverter Defining a converter with an object literal with converter type and its options (aka JSON format) has been deprecated and does nothing. If needed, you can make the JSON format work again by importing the deprecated ojvalidation-datetime module. 17.0.0
Promise<oj.Converter<any>> Defining a Promise to a Converter instance has been deprecated. The application should resolve the Promise and then update the converter attribute with the resolved converter instance.
- Default Value:
new DateTimeConverter({ formatType: 'datetime', dateFormat: 'short', timeFormat: 'short' })
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-picker :Object
-
Note that Jet framework prohibits setting subset of properties which are object types.
For example myInputDate.datePicker = {footerLayout: "today"}; is prohibited as it will wipe out all other sub-properties for "datePicker" object.
If one wishes to do this [by above syntax or knockout] one will have to get the "datePicker" object, modify the necessary sub-property and pass it to above syntax.
Default values for the datePicker sub-properties can also be overridden with the theming variable$inputDateTimeDatePickerOptionDefault
, which is merged with other defaults.
Note that all of the datePicker sub-properties except showOn are not available when renderMode is 'native'.
Names
Item Name Property datePicker
Property change event datePickerChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-date-picker-changed
-
(nullable) date-picker.change-month :string
-
Whether the month should be rendered as a button to allow selection instead of text.
See the date-picker attribute for usage examples.
- Default Value:
"select"
Supported Values:
Value Description none
month is rendered as text select
month is rendered as a button Names
Item Name Property datePicker.changeMonth
-
(nullable) date-picker.change-year :string
-
Whether the year should be rendered as a button to allow selection instead of text.
See the date-picker attribute for usage examples.
- Default Value:
"select"
Supported Values:
Value Description none
year is rendered as text select
year is rendered as a button Names
Item Name Property datePicker.changeYear
-
(nullable) date-picker.current-month-pos :number
-
The position in multipe months at which to show the current month (starting at 0).
See the date-picker attribute for usage examples.
- Deprecated:
-
Since Description 17.0.0
This is required when date-picker.number-of-months > 1, which is now deprecated, so this is no longer needed.
- Default Value:
0
Names
Item Name Property datePicker.currentMonthPos
-
(nullable) date-picker.days-outside-month :string
-
Dictates the behavior of days outside the current viewing month.
See the date-picker attribute for usage examples.
- Deprecated:
-
Since Description 17.0.0
The Redwood UX specification does not support visible. - Default Value:
"hidden"
Supported Values:
Value Description hidden
Days outside the current viewing month will be hidden selectable
Days outside the current viewing month will be visible + selectable visible
Days outside the current viewing month will be visible Names
Item Name Property datePicker.daysOutsideMonth
-
(nullable) date-picker.footer-layout :string
-
Will dictate what content is shown within the footer of the calendar.
See the date-picker attribute for usage examples.
- Deprecated:
-
Since Description 8.2.0
This attribute is deprecated and should not be used as it will be ignored in new UX design.
- Default Value:
"today"
Supported Values:
Value Description Do not show anything today
Show the today button. When user clicks on the Today button, it will highlight the current day in the calendar. Names
Item Name Property datePicker.footerLayout
-
(nullable) date-picker.number-of-months :number
-
The number of months to show at once. Note that if one is using a numberOfMonths > 4 then one should define a CSS rule for the width of each of the months. For example if numberOfMonths is set to 6 then one should define a CSS rule .oj-datepicker-multi-6 .oj-datepicker-group providing the width each month should take in percentage.
See the date-picker attribute for usage examples.
- Deprecated:
-
Since Description 17.0.0
This is not supported in the Redwood UX specification for Date Picker. See the Range Picker UX specification.
- Default Value:
1
Names
Item Name Property datePicker.numberOfMonths
-
(nullable) date-picker.show-on :string
-
When the datepicker should be shown.
See the date-picker attribute for usage examples.
- Deprecated:
-
Since Description 17.0.0
This is not supported in the Redwood UX specification.
- Default Value:
"image"
Supported Values:
Value Description focus
when the element receives focus or when the trigger calendar image is clicked. When the picker is closed, the field regains focus and is editable. image
when the trigger calendar image is clicked. Keyboard users must use the Up or Down Arrow key to open the datepicker when show-on is 'image'. userFocus
when the element receives focus from a user action (such as tab key press) or the calendar image is clicked. Programmatic calls to .focus() do not show the picker. Names
Item Name Property datePicker.showOn
-
(nullable) date-picker.step-big-months :number
-
Number of months to step back/forward for the (Alt + Page up) + (Alt + Page down) key strokes.
See the date-picker attribute for usage examples.
- Deprecated:
-
Since Description 17.0.0
This is not in the Redwood UX specification.
- Default Value:
12
Names
Item Name Property datePicker.stepBigMonths
-
(nullable) date-picker.step-months :('numberOfMonths'|number)
-
How the prev + next will step back/forward the months. The following are the valid values:
-
"numberOfMonths"
- When set to this string, will use numberOfMonths property value as value. -
<number>
- Number of months to step back/forward.
See the date-picker attribute for usage examples.
- Deprecated:
-
Since Description 17.0.0
This is not in the Redwood UX specification.
- Default Value:
"numberOfMonths"
Names
Item Name Property datePicker.stepMonths
-
-
(nullable) date-picker.week-display :string
-
Whether week of the year will be shown in the datepickeer. The default calculation follows the ISO 8601 definition: the week starts on Monday, the first week of the year contains the first Thursday of the year. This means that some days from one year may be placed into weeks 'belonging' to another year.
See the date-picker attribute for usage examples.
- Default Value:
"none"
Supported Values:
Value Description none
The week of the year column will not be shown number
Will show the week of the year as a number Names
Item Name Property datePicker.weekDisplay
-
(nullable) date-picker.year-range :string
-
The range of years displayed in the year drop-down: either relative to today's year ("-nn:+nn"), relative to the currently selected year ("c-nn:c+nn"), absolute ("nnnn:nnnn"), or combinations of these formats ("nnnn:-nn").
See the date-picker attribute for usage examples.
- Deprecated:
-
Since Description 17.0.0
This is not in the Redwood UX specification. The 'min' and 'max' properties should be used instead.
- Default Value:
"c-10:c+10"
Names
Item Name Property datePicker.yearRange
-
day-formatter :(param: ojInputDate.DayFormatterInput)=> (null|'all'|ojInputDate.DayFormatterOutput)
-
Additional info to be used when rendering the day This should be a JavaScript Function reference which accepts as its argument the following JSON format {fullYear: Date.getFullYear(), month: Date.getMonth()+1, date: Date.getDate()} and returns null or JSON data of {disabled: true|false}
Deprecated in 17.0.0: We no longer support className or tooltip in the JSON data return value, as this does not match the Redwood UX specification. 'all' as the function return has no effect, so it too is deprecated.
- Default Value:
null
Names
Item Name Property dayFormatter
Property change event dayFormatterChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-day-formatter-changed
-
day-meta-data :{[key:string]: {[key:string]: {[key:string]: {disabled?: boolean, className?: string, tooltip?: string}}}}
-
Additional info to be used when rendering the day This should be in the following JSON format with the year, month, day based on Date.getFullYear(), Date.getMonth()+1, and Date.getDate(): {year: {month: {day: {disabled: true|false, className: "additionalCSS", tooltip: 'Stuff to display'}}} There also exists a special '*' character which represents ALL within that field [i.e. * within year, represents for ALL year]. Note that this property will override the value of the dayFormatter property. Setting both dayFormatter and dayMetaData properties is not supported.
- Deprecated:
-
Since Description 17.0.0
Use dayFormatter instead, as it is more flexible.
- Default Value:
null
Names
Item Name Property dayMetaData
Property change event dayMetaDataChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-day-meta-data-changed
-
(nullable) described-by :string
-
The oj-label sets the described-by attribute programmatically on the form component. This attribute is not meant to be set by an application developer directly. The described-by is copied to the aria-describedby attribute on the component's inner dom element, and it is needed for accessibility.
- Since:
- 4.0.0
Names
Item Name Property describedBy
Property change event describedByChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-described-by-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
- Since:
- 0.7.0
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 :Object
-
Display options for auxiliary content that determines whether or not it should be displayed.
In the Redwood theme, the sub-properties of the display-options configure whether or not the types of information is shown. The values of these sub-properties are either 'display' or 'none'.
When display-options changes due to programmatic intervention, the component updates its display to reflect the updated choices. For example, if you don't want to show the converter hint, set the display-options.converter-hint to 'none'.
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. The allowed html tags are: span, b, i, em, br, hr, li, ol, ul, p, small, pre. To format the help.instruction, you could do this:
<html>Enter <b>at least</b> 6 characters</html>
- Since:
- 0.7
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
-
display-options.converter-hint :Array<'placeholder'|'notewindow'|'none'>|'placeholder'|'notewindow'|'display'|'none' display-options.converter-hint :('display'|'none')
-
Display options for auxiliary converter hint text. The supported attribute values are theme dependent.
In the Redwood theme, this attribute determines whether or not the converter hint should be displayed. The supported values are 'display' and 'none'. If you don't want to show the converter hint, set display-options.converter-hint to 'none'. It defaults to 'display'. To control where the hints display, e.g., inline or in a notewindow, then use the user-assistance-density attribute.
- Deprecated:
-
Since Value Description 9.1.0
Array<'placeholder'|'notewindow'|'none'>,'placeholder','notewindow' These types are no longer supported. They are used for the Alta theme only. The Redwood theme uses 'display'|'none' and the user-assistance-density attribute. 17.0.0
Please use help-hints instead.
- Since:
- 17.0.0
Names
Item Name Property displayOptions.converterHint
-
display-options.help-instruction :Array<'notewindow'|'none'>|'notewindow'|'none'
-
Display options for auxiliary help instruction text that determines where it should be displayed in relation to the component.
- Deprecated:
-
Since Description 9.0.0
If you want none, remove help-instruction attribute.
- Default Value:
['notewindow']
- Since:
- 9.0.0
Names
Item Name Property displayOptions.helpInstruction
-
display-options.messages :Array<'inline'|'notewindow'|'none'>|'inline'|'notewindow'|'display'|'none' display-options.messages :('display'|'none')
-
Display options for auxiliary message text. The supported attribute values are theme dependent.
In the Redwood theme, this attribute determines whether or not the messages should be displayed. The supported values are 'display' and 'none'. If you don't want to show messages, set display-options.messages to 'none'. It defaults to 'display'. To control where the messages display, e.g., inline or in a notewindow, then use the user-assistance-density attribute.
- Deprecated:
-
Since Value Description 9.1.0
Array<'inline'|'notewindow'|'none'>,'inline','notewindow' These types are no longer supported. They are used for the Alta theme only. The Redwood theme uses 'display'|'none' and the user-assistance-density attribute.
- Since:
- 9.1.0
Names
Item Name Property displayOptions.messages
-
display-options.validator-hint :Array<'notewindow'|'none'>|'notewindow'|'display'|'none' display-options.validator-hint :('display'|'none')
-
Display options for auxiliary validator hint text. The supported attribute values are theme dependent.
In the Redwood theme, this attribute determines whether or not the validator hint should be displayed. The supported values are 'display' and 'none'. If you don't want to show the validator hint, set display-options.validator-hint to 'none'. It defaults to 'display'. To control where the hints display, e.g., inline or in a notewindow, then use the user-assistance-density attribute.
- Deprecated:
-
Since Value Description 9.1.0
Array<'notewindow'|'none'>,'notewindow' These types are no longer supported. They are used for the Alta theme only. The Redwood theme uses 'display'|'none' and the user-assistance-density attribute.
- Since:
- 9.1.0
Names
Item Name Property displayOptions.validatorHint
-
help :Object
-
Form component help information.
- Since:
- 0.7.0
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.instruction :string
-
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.
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.
In the Redwood theme, 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.
How is help.instruction better than the html 'title' attribute? The html 'title' attribute only shows up as a tooltip on mouse over, not on keyboard and not in a mobile device. So the html 'title' 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 the 'title' window. For these reasons, the JET EditableValue components do not use the HTML's 'title' attribute and instead use the help.instruction attribute.
To include formatted text in the help.instruction, format the string using html tags. The allowed html tags are: span, b, i, em, br, hr, li, ol, ul, p, small, pre. For example the help.instruction might look like:
If you use formatted text, it should be accessible and make sense to the user if formatting wasn't there.<oj-some-element help.instruction="<html>Enter <b>at least</b> 6 characters</html>"></oj-some-element>
- Default Value:
""
- Since:
- 4.0.0
Names
Item Name Property help.instruction
-
help-hints :Object
-
The helpHints object contains a definition property and a source property.
definition
- hint for help definition text.source
- hint for help source URL.
- Since:
- 4.1.0
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
-
(nullable) help-hints.definition :string
-
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.
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.
In the Redwood theme, 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.
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
-
(nullable) help-hints.source :string
-
Help source URL associated with the component.
In the Redwood theme, the help-hints.source will show as a link inline to the field. For input components, it shows when the field takes focus. For other components, it shows all the time.
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
-
keyboard-edit :"enabled"|"disabled"
-
Determines if keyboard entry of the text is allowed. When disabled the picker must be used to select a date. Themes can override the default value.
- Deprecated:
-
Since Description 17.0.0
This is not supported in the Redwood UX specification.
- Default Value:
"enabled"
Supported Values:
Value Description disabled
Changing the date can only be done with the picker. enabled
Allow keyboard entry of the date. Names
Item Name Property keyboardEdit
Property change event keyboardEditChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-keyboard-edit-changed
-
label-edge :('inside'|'none'|'provided')
-
Specifies how the label of the component is created when the
label-hint
attribute is set on the component.The default value varies by theme, and it works well for the theme in most cases. If the component is in an oj-form-layout, the label-edge attribute could come from the oj-form-layout's label-edge attribute. The oj-form-layout component uses the MetadataTypes.PropertyBinding
provide
property to provide and uses the MetadataTypes.ProvidePropertytransform
property to transform itslabel-edge
attribute to any descendent components that are configured to consume it. For example, if the oj-form-layout's label-edge attribute is set to "top" or "start", and a descendent form component does not have its label-edge attribute set, the form component's label-edge will be the transformed value "provided".- Since:
- 8.0.0
Supported Values:
Value Description inside
The component creates the label using the label-hint
attribute.For text input components (such as oj-input-text), the label floats over the input element but moves up on focus or when the component has a value.
For non-text input components (such as oj-checkboxset), the label is created at the top of the component and doesn't move.
none
The component will not have a label, regardless of whether it's in an oj-form-layout or not. If the component has a
label-hint
attribute but no labelled-by, aria-label, or aria-labelledby attribute, the label-hint value will be used as the aria-label.Note that if the component already has an external label, "none" should not be specified and "provided" should be used instead. Otherwise it may end up with conflicting label information.
provided
Label is provided by the parent if the parent is an oj-form-layout. oj-form-layout provides the label using the label-hint from the form control and the label-edge from oj-form-layout.
If there is no oj-form-layout, use an oj-label.
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.
When label-edge is "provided", it gives a hint to oj-form-layout parent element to create an oj-label element for the component. When the
label-hint
attribute changes, oj-form-layout element refreshes to display the updated label information.When label-edge is "inside", it gives a hint to the component itself to render a label.
When label-edge is "none", and if the component has no labelled-by, aria-label, or aria-labelledby attribute, the label-hint value will be used as the aria-label.
- Default Value:
""
- Since:
- 4.1.0
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
-
labelled-by :string|null
-
The oj-label sets the labelledBy property programmatically on the form component to make it easy for the form component to find its oj-label component (a document.getElementById call.)
The application developer should use the 'for'/'id api to link the oj-label with the form component; the 'for' on the oj-label to point to the 'id' on the input form component. This is the most performant way for the oj-label to find its form component.
- Deprecated:
-
Since Description 17.0.0
This is an internal API and is not supported in the Redwood UX specification.
- Default Value:
null
- Since:
- 17.0.0
Names
Item Name Property labelledBy
Property change event labelledByChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-labelled-by-changed
-
max :string|null
-
The maximum selectable datetime, in ISO string format. When set to null, there is no maximum.
So it can be properly compared with the value the user selects, this should be in the same format as the converter's isoStrFormat. By default, value is a local isostring for oj-input-date-time.
- Default Value:
null
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.Message>
-
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 Message for details. 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. The allowed html tags are: span, b, i, em, br, hr, li, ol, ul, p, small, pre. To format the message detail, you could do this:
<html>Enter <b>at least</b> 6 characters</html>
A messagesCustom message with severity error will make the component's valid state invalidShown. However, a messagesCustom message, no matter the severity, does not prevent the value from being changed, as well as pushed to the view model.
Messages are shown on an enabled component, but not on a disabled component. On a readonly component, if readonlyMessagesCustom is set to 'confirmationOrInfoMessages', then info and confirmation custom messages are shown.
See the Validation and Messages section for details on when the component clears
messagesCustom
; for example, when full validation is run.In the Redwood theme, the Message summary is not displayed to the user, so make sure to have a Message detail set in your Message object.
- Default Value:
[]
- Supports writeback:
true
- Since:
- 0.7.0
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 datetime, in ISO string format. When set to null, there is no minimum.
So it can be properly compared with the value the user selects, this should be in the same format as the converter's isoStrFormat since the value the user selects is parsed with the converter. By default, value is a local isostring for oj-input-date-time.
- Default Value:
null
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
-
name :string
-
Specifies the name of the component.
Deprecated:
Since Description 6.0.0
JET does not use form submit, so this is not needed. - Default Value:
""
- Since:
- 4.0.0
Names
Item Name Property name
Property change event nameChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-name-changed
-
(nullable) picker-attributes :Object
-
Attributes specified here will be set on the picker DOM element when it's launched.
The supported attribute is
class
, which is appended to the picker's class, if any. Note: 1) pickerAttributes is not applied in the native theme. 2) setting this property after element creation has no effect.- Deprecated:
-
Since Description 17.0.0
Changing the Class or Style property is not recommended, as it leads to an inconsistent UI.
- Deprecated:
-
Since Description 17.0.0
We are recommending not to change the Class property of pickerAttribute as it leads to an inconsistent UI. - Deprecated:
-
Since Description 7.0.0
Style property of pickerAttribute violates the recommended Content Security Policy for JET which disallows inline styles. Use class property instead. As of 11.0.0 this attribute is ignored and an error is logged. - Default Value:
null
Properties:
Name Type Argument Description class
string <optional>
style
string <optional>
Names
Item Name Property pickerAttributes
Property change event pickerAttributesChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-picker-attributes-changed
-
placeholder :string
-
The placeholder text to set on the element.
- Deprecated:
-
Since Description 17.0.0
The date field contains mask segments instead of a general input, so placeholder is not supported.
Names
Item Name Property placeholder
Property change event placeholderChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-placeholder-changed
-
(readonly) raw-value :RV
-
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'. Then when the user blurs or presses Enter thevalue
property gets converted and validated (if there is a converter or validators) and then gets updated if valid.This is a read-only attribute 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, 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.
The default value for readonly is false. However, if the form component is a descendent of
oj-form-layout
, the default value for readonly could come from theoj-form-layout
component's readonly attribute. Theoj-form-layout
uses the MetadataTypes.PropertyBindingprovide
property to provide itsreadonly
attribute value to be consumed by descendent components. The form components are configured to consume the readonly property if an ancestor provides it and it is not explicitly set. For example, if the oj-form-layout's readonly attribute is set to true, and a descendent form component does not have its readonly attribute set, the form component's readonly will be true.- Default Value:
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'
- Since:
- 17.1.0
Supported Values:
Value Description confirmationAndInfoMessages
messagesCustom messages of severity 'confirmation' and 'info' are shown when the component is readonly. Other severities will be filtered out and an info log message will be logged to the console. none
no user assistance is shown when the component is readonly 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
-
render-mode :"jet"|"native"
-
Allows applications to specify whether to render date and time pickers in JET or as a native picker control. Note that the native renderMode will attempt to load a Cordova plugin that will launch the native picker. If the plugin is not found, the default JET picker will be used. With native renderMode, the functionality that is sacrificed compared to jet renderMode are:
- Date and time pickers cannot be themed
- Accessibility is limited to what the native picker supports
- pickerAttributes is not applied
- Sub-IDs are not available
- hide() and hideTimePicker() functions are no-op
- translations sub properties pertaining to the picker is not available
- All of the 'datepicker' sub-properties except 'showOn' are not available
- 'timePicker.timeIncrement' property is limited to iOS and will only take a precision of minutes
- Deprecated:
-
Since Description 8.0.0
The "native" mode rendering is deprecated because JET is promoting a consistent Oracle UX over native look and feel in Redwood. Since this property takes only two values the property itself is deprecated. The theme variable "$inputDateTimeRenderModeOptionDefault" is also deprecated for the same reason.
- Default Value:
"jet"
Supported Values:
Value Description jet
Applications get full JET functionality. native
Applications get the functionality of the native picker. Native picker is not available when the picker is inline, defaults to 'jet' instead. Names
Item Name Property renderMode
Property change event renderModeChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-render-mode-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
translations.required
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 invalid and has deferred messages 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 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 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
- Since:
- 0.7.0
- See:
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
-
time-picker :Object
-
Note that Jet framework prohibits setting subset of properties which are object types.
For example myInputDateTime.timePicker = {timeIncrement: "00:30:00:00"}; is prohibited as it will wipe out all other sub-properties for "timePicker" object.
If one wishes to do this [by above syntax or knockout] one will have to get the "timePicker" object, modify the necessary sub-property and pass it to above syntax.
Names
Item Name Property timePicker
Property change event timePickerChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-time-picker-changed
-
time-picker.footer-layout :""|"now"
-
Will dictate what content is shown within the footer of the wheel timepicker.
See the time-picker attribute for usage examples.
- Deprecated:
-
Since Description 8.2.0
This attribute is deprecated and should not be used as it will be ignored in new UX design.
- Default Value:
""
Supported Values:
Value Description Do not show anything now
Show the now button. When user clicks on the Now button, it will highlight the current time in the timepicker. Names
Item Name Property timePicker.footerLayout
-
time-picker.show-on :"focus"|"userFocus"|"image"
-
When the timepicker should be shown.
See the time-picker attribute for usage examples.
- Default Value:
"focus"
Supported Values:
Value Description focus
when the element receives focus or when the trigger clock image is clicked. When the picker is closed, the field regains focus and is editable. image
when the trigger clock image is clicked userFocus
when the element receives focus from a user action (such as tab key press) or the calendar image is clicked. Programmatic calls to .focus() do not show the picker. Names
Item Name Property timePicker.showOn
-
time-picker.time-increment :string
-
Time increment to be used for InputDateTime, the format is hh:mm:ss:SS.
Note that when renderMode is 'native', timeIncrement property is limited to iOS and will only take a precision of minutes.
See the time-picker attribute for usage examples.
- Default Value:
"00:05:00:00"
Names
Item Name Property timePicker.timeIncrement
-
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, see Events and Listeners for additional information.) on-translations-changed
-
translations.accessible-max-length-exceeded :string
-
Message to announce to AT via aria-live when the length.max is exceeded.
- Deprecated:
-
Since Description 17.0.0
This is not supported by the component.
- Since:
- 17.0.0
Names
Item Name Property translations.accessibleMaxLengthExceeded
-
translations.accessible-max-length-remaining :string
-
Message to annnouce to AT via aria-live for the remaining character count.
- Deprecated:
-
Since Description 17.0.0
This is not supported by the component.
- Since:
- 17.0.0
Names
Item Name Property translations.accessibleMaxLengthRemaining
-
(nullable) translations.cancel :string
-
The text to display for the Cancel link.
See the translations attribute for usage examples.
- Default Value:
"Cancel"
- Since:
- 0.7
Names
Item Name Property translations.cancel
-
(nullable) translations.current-text :string
-
The text to display for the current day link.
See the translations attribute for usage examples.
- Deprecated:
-
Since Description 17.0.0
The Redwood UX specification does not allow this to be configurable.
- Default Value:
"Today"
- Since:
- 17.0.0
Names
Item Name Property translations.currentText
-
(nullable) translations.date-restriction :Object
-
Provides properties to customize the hint and message text used by the implicit date restriction validator associated to the InputDateTime and InputDate components.
See the translations attribute for usage examples.
- Since:
- 0.7
Names
Item Name Property translations.dateRestriction
-
(nullable) translations.date-restriction.hint :string
-
Hint text used by the implicit date restriction validator associated to the InputDateTime and InputDate components.
See the translations attribute for usage examples.
- Deprecated:
-
Since Description 17.0.0
Please use help-hints instead.
- Default Value:
""
- Since:
- 17.0.0
- See:
Names
Item Name Property translations.dateRestriction.hint
-
(nullable) translations.date-restriction.message-detail :string
-
Message detail for the implicit date restriction validator associated to the InputDateTime and InputDate components.
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. The allowed html tags are: span, b, i, em, br, hr, li, ol, ul, p, small, pre.
See the translations attribute for usage examples.
- Default Value:
""
- Since:
- 0.7
- See:
Names
Item Name Property translations.dateRestriction.messageDetail
-
(nullable) translations.date-restriction.message-summary :string
-
Message summary for the implicit date restriction validator associated to the InputDateTime and InputDate components.
See the translations attribute for usage examples.
- Deprecated:
-
Since Description 17.0.0
This is not supported in the Redwood UX specification.
- Default Value:
""
- Since:
- 17.0.0
- See:
Names
Item Name Property translations.dateRestriction.messageSummary
-
(nullable) translations.date-time-range :Object
-
Provides properties to customize the hint and message text used by the implicit datetime range validator associated to the InputDateTime, InputDate, and InputTime components.
See the translations attribute for usage examples.
- Since:
- 0.7
Names
Item Name Property translations.dateTimeRange
-
(nullable) translations.date-time-range.hint :Object
-
Provides properties to customize the hint text used by the implicit datetime range validator associated to the InputDateTime, InputDate, and InputTime components.
See the translations attribute for usage examples.
- Deprecated:
-
Since Description 17.0.0
Please use help-hints instead.
- Since:
- 17.0.0
Names
Item Name Property translations.dateTimeRange.hint
-
(nullable) translations.date-time-range.hint.in-range :string
-
Hint text used by the implicit datetime range validator associated to the InputDateTime, InputDate, and InputTime components. 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.
- Deprecated:
-
Since Description 17.0.0
Please use help-hints instead.
- Default Value:
""
- Since:
- 17.0.0
- See:
Names
Item Name Property translations.dateTimeRange.hint.inRange
-
(nullable) translations.date-time-range.hint.max :string
-
Hint text used by the implicit datetime range validator associated to the InputDateTime, InputDate, and InputTime components. 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.
- Deprecated:
-
Since Description 17.0.0
Please use help-hints instead.
- Default Value:
""
- Since:
- 17.0.0
- See:
Names
Item Name Property translations.dateTimeRange.hint.max
-
(nullable) translations.date-time-range.hint.min :string
-
Hint text used by the implicit datetime range validator associated to the InputDateTime, InputDate, and InputTime components. 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.
- Deprecated:
-
Since Description 17.0.0
Please use help-hints instead.
- Default Value:
""
- Since:
- 17.0.0
- See:
Names
Item Name Property translations.dateTimeRange.hint.min
-
(nullable) translations.date-time-range.message-detail :Object
-
Provides properties to customize the error message text used by the implicit datetime range validator associated to the InputDateTime, InputDate, and InputTime components.
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. The allowed html tags are: span, b, i, em, br, hr, li, ol, ul, p, small, pre.
See the translations attribute for usage examples.
- Since:
- 0.7
Names
Item Name Property translations.dateTimeRange.messageDetail
-
(nullable) translations.date-time-range.message-detail.range-overflow :string
-
Error message text used by the implicit datetime range validator associated to the InputDateTime, InputDate, and InputTime components. 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.dateTimeRange.messageDetail.rangeOverflow
-
(nullable) translations.date-time-range.message-detail.range-underflow :string
-
Error message text used by the implicit datetime range validator associated to the InputDateTime, InputDate, and InputTime components. 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.dateTimeRange.messageDetail.rangeUnderflow
-
(nullable) translations.date-time-range.message-summary :Object
-
Provides properties to customize the error message summary text used by the implicit datetime range validator associated to the InputDateTime, InputDate, and InputTime components.
See the translations attribute for usage examples.
- Deprecated:
-
Since Description 17.0.0
This is not supported in the Redwood UX specification.
- Since:
- 17.0.0
Names
Item Name Property translations.dateTimeRange.messageSummary
-
(nullable) translations.date-time-range.message-summary.range-overflow :string
-
Error message summary text used by the implicit datetime range validator associated to the InputDateTime, InputDate, and InputTime components. messageSummary.rangeOverflow is shown when max is set, and the value is greater than the maximum.
See the translations attribute for usage examples.
- Deprecated:
-
Since Description 17.0.0
This is not supported in the Redwood UX specification.
- Default Value:
""
- Since:
- 17.0.0
- See:
Names
Item Name Property translations.dateTimeRange.messageSummary.rangeOverflow
-
(nullable) translations.date-time-range.message-summary.range-underflow :string
-
Error message summary text used by the implicit datetime range validator associated to the InputDateTime, InputDate, and InputTime components. messageSummary.rangeUnderflow is shown when min is set, and the value is less than the minimum.
See the translations attribute for usage examples.
- Deprecated:
-
Since Description 17.0.0
This is not supported in the Redwood UX specification.
- Default Value:
""
- Since:
- 17.0.0
- See:
Names
Item Name Property translations.dateTimeRange.messageSummary.rangeUnderflow
-
(nullable) translations.done :string
-
The text to display for the switcher's Done link.
See the translations attribute for usage examples.
- Default Value:
"Done"
- Since:
- 0.7
Names
Item Name Property translations.done
-
(nullable) translations.next-text :string
-
The text to display for the next month link.
See the translations attribute for usage examples.
- Deprecated:
-
Since Description 17.0.0
The Redwood UX specification does not allow this to be configurable.
- Default Value:
"Next"
- Since:
- 17.0.0
Names
Item Name Property translations.nextText
-
(nullable) translations.prev-text :string
-
The text to display for the previous month link.
See the translations attribute for usage examples.
- Deprecated:
-
Since Description 17.0.0
The Redwood UX specification does not allow this to be configurable.
- Default Value:
"Previous"
- Since:
- 17.0.0
Names
Item Name Property translations.prevText
-
(nullable) translations.regexp :Object
-
Provides properties to customize the message text used by the implicit regexp validator associated to the InputText and TextArea components.
See the translations attribute for usage examples.
- Deprecated:
-
Since Description 17.0.0
This is not supported by the component.
- Since:
- 17.0.0
Names
Item Name Property translations.regexp
-
(nullable) translations.regexp.message-detail :string
-
Provides properties to customize the error message detail used by the implicit regexp validator associated to the InputText and TextArea components.
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. The allowed html tags are: span, b, i, em, br, hr, li, ol, ul, p, small, pre.
See the translations attribute for usage examples.
- Deprecated:
-
Since Description 17.0.0
This is not supported by the component.
- Since:
- 17.0.0
Names
Item Name Property translations.regexp.messageDetail
-
(nullable) translations.regexp.message-summary :string
-
Provides properties to customize the error message summary used by the implicit regexp validator associated to the InputText and TextArea components.
See the translations attribute for usage examples.
- Deprecated:
-
Since Description 17.0.0
This is not supported by the component.
- Since:
- 17.0.0
Names
Item Name Property translations.regexp.messageSummary
-
(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.
- Deprecated:
-
Since Description 17.0.0
Please use help-hints instead.
- Default Value:
""
- Since:
- 17.0.0
- 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.
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. The allowed html tags are: span, b, i, em, br, hr, li, ol, ul, p, small, pre.
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.
- Deprecated:
-
Since Description 14.0.0
This is deprecated because in the Redwood design system form components do not show validator summaries, so this is no longer needed.
- Default Value:
""
- Since:
- 14.0.0
- See:
Names
Item Name Property translations.required.messageSummary
-
(nullable) translations.time :string
-
The aria-label text for the time input in a oj-date-time-picker. When the screen reader user tabs to the input, they will hear 'Time' so that they know they are on the time field of the oj-date-time-picker.
See the translations attribute for usage examples.
- Default Value:
"Time"
- Since:
- 12.0.0
Names
Item Name Property translations.time
-
(nullable) translations.tooltip-calendar :string
-
Tooltip text for the calendar icon.
See the translations attribute for usage examples.
- Deprecated:
-
Since Description 17.0.0
This is not configurable per component instance in the Redwood UX specification.
- Default Value:
"Select Date"
Names
Item Name Property translations.tooltipCalendar
-
(nullable) translations.tooltip-calendar-disabled :string
-
Tooltip text for the calendar icon when the component is disabled.
See the translations attribute for usage examples.
- Deprecated:
-
Since Description 17.0.0
This is not configurable per component instance in the Redwood UX specification.
- Default Value:
"Select Date Disabled"
Names
Item Name Property translations.tooltipCalendarDisabled
-
(nullable) translations.tooltip-calendar-time :string
-
Tooltip text for the calendar + time icon.
See the translations attribute for usage examples.
- Deprecated:
-
Since Description 17.0.0
This is not configurable per component instance in the Redwood UX specification.
- Default Value:
"Select Date Time"
Names
Item Name Property translations.tooltipCalendarTime
-
(nullable) translations.tooltip-calendar-time-disabled :string
-
Tooltip text for the calendar + time icon when the component is disabled.
See the translations attribute for usage examples.
- Deprecated:
-
Since Description 17.0.0
This is not configurable per component instance in the Redwood UX specification.
- Default Value:
"Select Date Time Disabled"
Names
Item Name Property translations.tooltipCalendarTimeDisabled
-
(nullable) translations.week-header :string
-
The text to display for the week of the year column heading.
See the translations attribute for usage examples.
- Deprecated:
-
Since Description 17.0.0
The Redwood UX specification does not allow this to be configurable.
- Default Value:
"Wk"
- Since:
- 17.0.0
Names
Item Name Property translations.weekHeader
-
user-assistance-density :('reflow'|'efficient'|'compact')
-
Note: This attribute is not supported in the following themes:
Alta
-
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.
The default value is 'reflow' when the form component is not a descendent of an oj-form-layout component. When the form component is a descendent of an oj-form-layout, the default value comes from the oj-form-layout's
user-assistance-density
attribute value.The oj-form-layout component uses the MetadataTypes.PropertyBinding
provide
property to provide itsuser-assistance-density
attribute value to be consumed by descendent components. The form components are configured to consume theuser-assistance-density
property if an ancestor provides it and it is not explicitly set on the form component. Example, oj-form-layout defaults user-assistance-density='efficient', so all its form components descendents will have user-assistance-density='efficient' by default.- Default Value:
"reflow"
- Since:
- 9.0.0
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
- Since:
- 4.2.0
Supported Values:
Value Description invalidHidden
The component has invalid messages hidden and no invalid messages showing. An invalid message is one with severity "error" or higher. invalidShown
The component has invalid messages showing. An invalid message is one with severity "error" or higher. 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.<(oj.Validator.<string>|oj.AsyncValidator.<string>|oj.Validation.RegisteredValidator)>|null) validators :(Array.<(oj.Validator.<string>|oj.AsyncValidator.<string>)>|null)
-
List of validators, synchronous or asynchronous, used by component along with asynchronous validators from the deprecated async-validators option 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 themin
and/ormax
attribute is set, an implicit oj.DateTimeRangeValidator is created. If thedayFormatter
attribute is set, an implicit oj.DateRestrictionValidator is created. At runtime when the component runs validation, it combines all the implicit validators with all the validators specified through thisvalidators
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.When
validators
property changes due to programmatic intervention, the element 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 element is valid when validators changes, element does nothing other than the steps it always performs.
- if element is invalid and is showing messages when
validators
changes then all element messages are cleared and full validation run using the display value on the element.- 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 element 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 element are cleared.
messagesCustom
property is not cleared.
- Deprecated:
-
Since Value Description 8.0.0
oj.Validation.RegisteredValidator Defining a validator with an object literal with validator type and its options (aka JSON format) has been deprecated and does nothing. If needed, you can make the JSON format work again by importing the deprecated ojvalidation-datetime module.
- 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
-
The value of the InputDateTime element which should be an ISOString.
If the converter's timeZone option is not set and the value is a zulu or offset (not local) ISOString, the timeZone will default to the user's system's timeZone.
- 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
Events
-
ojAnimateEnd
-
Triggered when a default animation has ended.
- Deprecated:
-
Since Description 12.1.0
This web component no longer supports this event.
- "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
- Since:
- 12.1.0
Properties:
All of the event payloads listed below can be found under
event.detail
. See Events and Listeners for additional information.Name Type Description action
string The action that triggered the animation. Supported values are: element
Element The element being animated. -
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 toevent.detail.endCallback
.event.detail.endCallback
should be called immediately afterevent.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 callevent.detail.endCallback
may prevent the component from working properly.For more information on customizing animations, see the documentation of AnimationUtils.
The default animations are controlled via the theme: // default animations for notewindow help and hints and messages $popupTailOpenAnimation: (effect: "zoomIn", transformOrigin: "#myPosition") !default; $popupTailCloseAnimation: (effect: "none") !default; // default animations for Redwood's inline messages shown when userAssistanceDensity // is reflow or efficient. $messageComponentInlineOpenAnimation: (effect: "fadeIn", duration: "100ms", timingFunction: "linear") !default; $messageComponentInlineCloseAnimation: (effect: "fadeOut", duration: "100ms", timingFunction: "linear") !default;
- Deprecated:
-
Since Description 12.1.0
This web component no longer supports this event.
- "inline-hints-open" - when an inline helphints container opens
- "inline-hints-close" - when an inline helphints container closes
- "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
- Since:
- 12.1.0
Properties:
All of the event payloads listed below can be found under
event.detail
. See Events and Listeners for additional information.Name Type Description action
string The action that triggers the animation. Supported values are: 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.
Methods
-
getProperty(property) : {any}
-
Retrieves the value of a property or a subproperty. The return type will be the same as the type of the property as specified in this API document. If the method is invoked with an incorrect property/subproperty name, it returns undefined.
Parameters:
Name Type Description property
string The property name to get. Supports dot notation for subproperty access. - Since:
- 4.0.0
Returns:
- Type
- any
Example
let subpropValue = myComponent.getProperty('complexProperty.subProperty1.subProperty2');
-
hide : {void}
-
Hides the datepicker. Note that this function is a no-op when renderMode is 'native'.
- Deprecated:
-
Since Description 17.0.0
This is not supported in the Redwood UX specification.
Returns:
- Type
- void
-
hideTimePicker : {void}
-
Returns:
- Type
- void
-
refresh : {void}
-
Refreshes the element. Usually called after dom changes have been made.
- Deprecated:
-
Since Description 17.0.0
This is not supported in Core Pack components.
Returns:
- Type
- void
-
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.0
Returns:
- Type
- void
-
setProperties(properties) : {void}
-
Performs a batch set of properties. The type of value for each property being set must match the type of the property as specified in this API document.
Parameters:
Name Type Description properties
Object An object containing the property and value pairs to set. - Since:
- 4.0.0
Returns:
- Type
- void
Example
myComponent.setProperties({"prop1": "value1", "prop2.subprop": "value2", "prop3": "value3"});
-
setProperty(property, value) : {void}
-
Sets a property or a subproperty (of a complex property) and notifies the component of the change, triggering a [property]Changed event. The value should be of the same type as the type of the attribute mentioned in this API document.
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. - Since:
- 4.0.0
Returns:
- Type
- void
Example
myComponent.setProperty('complexProperty.subProperty1.subProperty2', "someValue");
-
show : {void}
-
- Deprecated:
-
Since Description 17.0.0
This is not supported in the Redwood UX specification.
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.
- Since:
- 0.7.0
Returns:
- Type
- void
-
showTimePicker : {void}
-
Method to show the internally created InputTime
Returns:
- Type
- void
-
validate : {Promise<'valid'|'invalid'>}
-
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 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.
- 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. - 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<'valid'|'invalid'>