Element: <oj-input-date-time>

Oracle® JavaScript Extension Toolkit (JET)
7.1.0

F18183-01

Signature:

class ojInputDateTime<SP extends ojInputDateTimeSettableProperties = ojInputDateTimeSettableProperties>

QuickNav

Attributes

JET Custom Elements

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

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

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



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

Version:
  • 7.1.0
Since:
  • 0.6.0
Module:
  • ojdatetimepicker

Module usage

See JET Module Loading for an overview of module usage within JET.

Typescript Import Format
//To typecheck the element APIs, import as below.
import {ojInputDateTime} from "ojs/ojdatetimepicker";

//For the transpiled javascript to load the element's module, import as below
import "ojs/ojdatetimepicker";

JET In Typescript

A detailed description of working with JET elements and classes in your typescript project can be found at: JET Typescript Usage.


JET InputDateTime

Description:

A JET InputDateTime extends from InputDate providing additionally time selection drop down. The time format is based on the converter and default converter uses the locale to determine the time format. If the lang attribute is specified in the html tag then the converter picks locale based on the lang attribute. If there is no lang attribute specified then the locale is based on the browser language setting. Default value for locale is "en". For example, if locale is "en-US", the default for time is 12-hour format and if locale is "fr", the default for time is 24-hour format.

<oj-input-date-time></oj-input-date-time>

Validation and Messaging

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

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

Normal Validation

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

Deferred Validation

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

Mixed Validation

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

Showing Deferred Messages

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

Validators Participating in Deferred Validation

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

Touch End User Information

Target Gesture Action
Input element and calendar trigger icon Tap When not inline, shows the grid and moves the focus into the expanded date grid.
Time trigger icon Tap Shows the time picker and moves the focus into the expanded time picker
Input element with picker open Tap Set focus to the input. If hints, title or messages exist in a notewindow, pop up the notewindow.
Picker Swipe Left Switch to next month (or previous month on RTL page).
Picker Swipe Right Switch to previous month (or next month on RTL page).

Keyboard End User Information

Target Key Action
Input element DownArrow or UpArrow When not in inline mode, shows the calendar grid and moves the focus into the expanded grid. When in inline mode, shows the time picker and moves the focus into the expanded time picker
Input element Shift + DownArrow or UpArrow Shows the time picker and moves the focus into the expanded time picker
Input element Esc Close the grid.
Input Element Tab In Set focus to the input. If hints, title or messages exist in a notewindow, pop up the notewindow.
Picker Enter Select the currently focused day
Picker UpArrow Move up in the grid.
Picker DownArrow Move down in the grid.
Picker RightArrow Move right in the grid.
Picker LeftArrow Move left in the grid.
Picker Esc Close the grid.
Picker Home Move focus to first day of the month.
Picker End Move focus to last day of the month.
Picker PageUp Switch to previous month.
Picker PageDown Switch to next month.
Picker Alt + PageUp Switch to previous year.
Picker Alt + PageDown Switch to next year.
Picker Ctrl + Alt + PageUp Switch to previous by stepBigMonths.
Picker Ctrl + Alt + PageDown Switch to next by stepBigMonths.
Picker Ctrl + Alt + T Places focus on Today button if it exists.

Styling

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

The form control style classes can be applied to the component, or an ancestor element. When applied to an ancestor element, all form components that support the style classes will be affected.

Class Description
oj-form-control-full-width Changes the max-width to 100% so that form components will occupy all the available horizontal space
oj-form-control-text-align-right Aligns the text to the right regardless of the reading direction. This is normally used for right aligning numbers
oj-form-control-text-align-start Aligns the text to the left in ltr and to the right in rtl
oj-form-control-text-align-end Aligns the text to the right in ltr and to the left in rtl

Accessibility

It is up to the application developer to associate the label to the element. For InputDateTime, you should put an id on the element, and then set the for attribute on the label to be the element's id. If there is no oj-label for the InputDateTime, add aria-label on InputDateTime to make it accessible.

The placeholder text is not read reliably by the screen reader. For accessibility reasons, you need to associate the text to its JET form component using aria-describedby.

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

Label and InputDateTime

For accessibility, you should associate a label element with the input by putting an id on the input, and then setting the for attribute on the label to be the input's id.

The element will decorate its associated label with required and help information, if the required and help attributes are set.

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.

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.

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, use validators, 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 the async-validators attribute and the validators attribute. At runtime when the component runs validation, it combines the implicit validators with the list specified through the validators attribute and also the list specified through the async-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 oj.IntlConverterUtils.getConverterInstance(converterOption) to get the converter instance, then call converter.format(value).

Hints exposed by async-validators and validators are shown in the notewindow by default, or as determined by the 'validatorHint' property set on the display-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.


Default Value:
  • []
Names
Item Name
Property asyncValidators
Property change event asyncValidatorsChanged
Property change listener attribute (must be of type function) 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".

Default Value:
  • "on"
Since:
  • 4.0.0
See:
Names
Item Name
Property autocomplete
Property change event autocompleteChanged
Property change listener attribute (must be of type function) 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.
Default Value:
  • false
Since:
  • 4.0.0
Names
Item Name
Property autofocus
Property change event autofocusChanged
Property change listener attribute (must be of type function) on-autofocus-changed

converter :(Promise.<oj.Converter.<string>>|oj.Converter.<string>|oj.Validation.RegisteredConverter)

Default converter for InputDateTime. If one wishes to provide a custom converter for the InputDateTime override the factory returned for oj.Validation.converterFactory('datetime')

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 the valueChanged event to clear custom errors. The display value is refreshed with the formatted value provided by converter.
  • 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.

Default Value:
  • oj.Validation.converterFactory('datetime').createConverter({"day": "2-digit", "month": "2-digit", "year": "2-digit", "hour": "2-digit", "minute": "2-digit"})
Names
Item Name
Property converter
Property change event converterChanged
Property change listener attribute (must be of type function) 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) 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.

Supported Values:
Value Description
'none' month is rendered as a text
'select' month is rendered as a button
Default Value:
  • "select"
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.

Supported Values:
Value Description
'none' As text
'select' As a button
Default Value:
  • "select"
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.

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.

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
Default Value:
  • "hidden"
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.

Supported Values:
Value Description
'' Do not show anything
'today' Show the today button
Default Value:
  • "today"
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.

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.

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
Default Value:
  • "focus"
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.

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.

Default Value:
  • "numberOfMonths"
Names
Item Name
Property datePicker.stepMonths

(nullable) date-picker.week-display :string

Whether week of the year will be shown.

See the date-picker attribute for usage examples.

Supported Values:
Value Description
'none' Nothing will be shown
'number' Will show the week of the year as a number
Default Value:
  • "none"
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.

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 all or partial JSON data of {disabled: true|false, className: "additionalCSS", tooltip: 'Stuff to display'}
Default Value:
  • null
Names
Item Name
Property dayFormatter
Property change event dayFormatterChanged
Property change listener attribute (must be of type function) 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.
Default Value:
  • null
Names
Item Name
Property dayMetaData
Property change event dayMetaDataChanged
Property change listener attribute (must be of type function) on-day-meta-data-changed

(nullable) described-by :string

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

disabled :boolean

Whether the component is disabled. The default is false.

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

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

Default Value:
  • false
Since:
  • 0.7.0
Names
Item Name
Property disabled
Property change event disabledChanged
Property change listener attribute (must be of type function) on-disabled-changed

display-options :Object

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

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

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

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

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

Since:
  • 0.7
Names
Item Name
Property displayOptions
Property change event displayOptionsChanged
Property change listener attribute (must be of type function) on-display-options-changed

display-options.converter-hint :Array<'placeholder'|'notewindow'|'none'>|'placeholder'|'notewindow'|'none'

Display options for auxilliary converter hint text that determines where it should be displayed in relation to the component. When there is already a placeholder set on the component, the converter hint falls back to display type of 'notewindow'.
Default Value:
  • ['placeholder','notewindow']
Since:
  • 0.7
Names
Item Name
Property displayOptions.converterHint

display-options.help-instruction :Array<'notewindow'|'none'>|'notewindow'|'none'

Display options for auxilliary help instruction text that determines where it should be displayed in relation to the component.
Default Value:
  • ['notewindow']
Since:
  • 0.7
Names
Item Name
Property displayOptions.helpInstruction

display-options.messages :Array<'inline'|'notewindow'|'none'>|'inline'|'notewindow'|'none'

Display options for auxilliary message text that determines where it should be displayed in relation to the component.
Default Value:
  • ['inline']
Since:
  • 0.7
Names
Item Name
Property displayOptions.messages

display-options.validator-hint :Array<'notewindow'|'none'>|'notewindow'|'none'

Display options for auxilliary validator hint text that determines where it should be displayed in relation to the component.
Default Value:
  • ['notewindow']
Since:
  • 0.7
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) on-help-changed

help.instruction :string

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

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

JET takes the help instruction text and creates a notewindow with the text. The notewindow pops up when the field takes focus and closes when the field loses focus.

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. For example the help.instruction might look like:

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

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

help-hints :Object

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

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

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

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

(nullable) help-hints.definition :string

Hint for help definition text associated with the label.

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

See the help-hints attribute for usage examples.

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

(nullable) help-hints.source :string

Hint for help source URL associated with the label.

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

See the help-hints attribute for usage examples.

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

keyboard-edit :"enabled"|"disabled"

Determines if keyboard entry of the text is allowed. When disabled the picker must be used to select a date. Default value depends on the theme. In alta-android, alta-ios and alta-windows themes, the default is "disabled" and it's "enabled" for alta web theme.
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) on-keyboard-edit-changed

label-hint :string

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

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

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

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

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.

Default Value:
  • null
Since:
  • 7.0.0
Names
Item Name
Property labelledBy
Property change event labelledByChanged
Property change listener attribute (must be of type function) on-labelled-by-changed

max :string|null

The maximum selectable datetime, in ISO string format. When set to null, there is no maximum.
Default Value:
  • null
Names
Item Name
Property max
Property change event maxChanged
Property change listener attribute (must be of type function) 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 oj.Message for details.

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

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

min :string|null

The minimum selectable datetime, in ISO string format. When set to null, there is no minimum.
Default Value:
  • null
Names
Item Name
Property min
Property change event minChanged
Property change listener attribute (must be of type function) 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) 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.

Properties:
Name Type Argument Description
style string <optional>
Deprecated: this property is deprecated since 7.0.0 and will be removed in the future. Please use the "class" property to set a CSS class instead.
class string <optional>
Default Value:
  • null
Names
Item Name
Property pickerAttributes
Property change event pickerAttributesChanged
Property change listener attribute (must be of type function) on-picker-attributes-changed

placeholder :string

The placeholder text to set on the element.
Names
Item Name
Property placeholder
Property change event placeholderChanged
Property change listener attribute (must be of type function) 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 of rawValue is a converter.

The rawValue updates on the 'input' javascript event, so the rawValue changes as the value of the input is changed. If the user types in '1,200' into the field, the rawValue will be '1', then '1,', then '1,2', ..., and finally '1,200'. Then when the user blurs or presses Enter the value property gets 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) 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.
Default Value:
  • false
Names
Item Name
Property readonly
Property change event readonlyChanged
Property change listener attribute (must be of type function) on-readonly-changed

render-mode :'jet'|'native'

Allows applications to specify whether to render date and time pickers in JET or as a native picker control.
Valid values: jet, native Default value depends on the theme. In alta-android, alta-ios and alta-windows themes, the default is "native" and it's "jet" for alta web theme.
  • jet - Applications get full JET functionality.
  • native - Applications get the functionality of the native picker.

  • Note that the native picker support is limited to Cordova plugin published at 'https://github.com/VitaliiBlagodir/cordova-plugin-datepicker'.
    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
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.

Note that the native picker support is limited to Cordova plugin published at 'https://github.com/VitaliiBlagodir/cordova-plugin-datepicker'.

With native renderMode, the functionality that is sacrificed compared to jet renderMode are:
  • Date Time picker cannot be themed
  • Accessibility is limited to what the native picker supports
  • pickerAttributes is not applied
  • Sub-IDs are not available
  • hide() function is 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
Names
Item Name
Property renderMode
Property change event renderModeChanged
Property change listener attribute (must be of type function) on-render-mode-changed

required :boolean

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

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

Running Validation

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

Clearing Messages

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

This property set to false implies that a value is not required to be provided by the user. This is the default. This property set to true implies that a value is required to be provided by user and the input's label will render a required icon. Additionally a required validator - oj.RequiredValidator - is implicitly used if no explicit required validator is set. An explicit required validator can be set by page authors using the validators attribute.
Default Value:
  • false
Since:
  • 0.7.0
See:
Names
Item Name
Property required
Property change event requiredChanged
Property change listener attribute (must be of type function) 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) 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.

Supported Values:
Value Description
'' Do not show anything
'now' Show the now button
Default Value:
  • ""
Names
Item Name
Property timePicker.footerLayout

time-picker.show-on :'focus'|'image'

When the timepicker should be shown.

See the time-picker attribute for usage examples.

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
Default Value:
  • "focus"
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) on-translations-changed

(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.

Default Value:
  • "Today"
Since:
  • 0.7
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.

Default Value:
  • ""
Since:
  • 0.7
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.

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.

Default Value:
  • ""
Since:
  • 0.7
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.

Since:
  • 0.7
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.

Default Value:
  • ""
Since:
  • 0.7
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.

Default Value:
  • ""
Since:
  • 0.7
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.

Default Value:
  • ""
Since:
  • 0.7
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.

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.

Since:
  • 0.7
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.

Default Value:
  • ""
Since:
  • 0.7
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.

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

(nullable) translations.done :string

The text to display for the switchers 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.

Default Value:
  • "Next"
Since:
  • 0.7
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.

Default Value:
  • "Prev"
Since:
  • 0.7
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.

Since:
  • 0.7
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.

See the translations attribute for usage examples.

Since:
  • 0.7
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.

Since:
  • 0.7
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.

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

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

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

See the translations attribute for usage examples.

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

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

Message text for summarizing a required validation error.

See the translations attribute for usage examples.

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

(nullable) translations.tooltip-calendar :string

Tooltip text for the calendar icon.

See the translations attribute for usage examples.

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.

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.

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.

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.

Default Value:
  • "Wk"
Since:
  • 0.7
Names
Item Name
Property translations.weekHeader

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

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

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

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

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

Supported Values:
Value Description
"invalidHidden" The component has invalid messages hidden and no invalid messages showing. An invalid message is one with severity "error" 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
Supports writeback:
  • true
Since:
  • 4.2.0
Names
Item Name
Property valid
Property change event validChanged
Property change listener attribute (must be of type function) on-valid-changed

validators :(Array.<(oj.Validator.<string>|oj.Validation.RegisteredValidator)>|null)

List of validators used by element when performing validation. Each item is either an instance that duck types oj.Validator, or is an Object literal containing the properties listed below.

Implicit validators 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.DateTimeRangeValidator is created. If the dayFormatter 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 this validators attribute, and runs all of them.

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

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 the valueChanged event to clear custom errors.
  • 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.

Properties:
Name Type Argument Description
type string the validator type that has a oj.ValidatorFactory that can be retrieved using the oj.Validation module. For a list of supported validators refer to oj.ValidatorFactory.
options Object <optional>
optional Object literal of options that the validator expects.
Default Value:
  • []
Names
Item Name
Property validators
Property change event validatorsChanged
Property change listener attribute (must be of type function) on-validators-changed

value :string

The value of the InputDateTime element which should be an ISOString
Supports writeback:
  • true
Names
Item Name
Property value
Property change event valueChanged
Property change listener attribute (must be of type function) on-value-changed

Events

ojAnimateEnd

Triggered when a default animation has ended.
Properties:

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

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

ojAnimateStart

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

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

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

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

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

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

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

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

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

Get a single subproperty of a complex property:

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

hide() → {void}

Hides the datepicker. Note that this function is a no-op when renderMode is 'native'.
Returns:
Type
void

hideTimePicker() → {void}

Returns:
Type
void

refresh() → {void}

Refreshes the element. Usually called after dom changes have been made.
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

Set a batch of properties:

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

Set a single subproperty of a complex property:

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

show() → {void}

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

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

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

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

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