The only way to provide data to JET Select Single is through a
DataProvider
. For cases with
a small set of fixed data, use an
ArrayDataProvider
.
Differences between Select and Combobox components
While oj-c-select-* components allow a user to filter the data in the dropdown,
it is not possible to enter values that are not available in the data.
This makes oj-c-select-* components ideal for usecases where the user can only
select values that are available in the dropdown, but not provide custom
values of their own.
In contrast, oj-combobox-* components allow a user to enter new values that are
not available in the data in addition to using the text field for filtering dropdown data.
This makes oj-combobox-* components ideal for usecases where the users can provide
custom values in addition to those that are already available in the dropdown data.
Application developers should consider the above differences when choosing between
Select and Combobox components.
Additionally, applications are advised to use oj-c-select-single instead of oj-select-single.
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.
All messages are cleared and
messagesCustom
property is cleared
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.
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
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
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 converter property changes. See
converter
property for details.
when required property changes. See
required
property for details.
when validators property changes. See
validators
property for details.
Showing Deferred Messages
Deferred validation messages are displayed only when page author requests for it explicitly in
one of the following ways:
Validators Participating in Deferred Validation
The required validator is the only validator type that participates in deferred validation.
The required property needs to be set to true for the required validator to run.
User Assistance Text
User assistive text provides guidance to help the user understand what data to enter or select.
By default all user assistance text shows inline.
For input components, it shows when the field takes focus. In other components
it shows all the time. See the user-assistance-density property for other ways
the user assistance text can render, like in 'compact' mode, it will render as an icon on the label
which when clicked will show the user assistance text in a notewindow.
The JET form component properties that are used for user assistance text are help.instruction,
validator and converter hints, and help-hints.
In the Redwood theme for clarity only one user assistance text shows to the user.
The precedence rules are:
help.instruction shows;
if no help.instruction, then validator hint shows;
if no help.instruction or validator hint, then help-hints.definition shows;
if no help.instruction, validator hint, or help-hints.definition, then converter hint shows.
help-hints.source always shows along side the above.
Sometimes a validator or converter hints shows that you do not want. To not show it,
set the display-options.validator-hint and/or display-options.converter-hint property to 'none'.
required and placeholder properties also can be used to guide the user.
In Redwood, a required field shows the word Required under the field
when the field is empty and does not have focus.
Placeholder is shown when the field is empty and has focus.
Touch End User Information
If the dropdown is not open, expand the dropdown list.
If hints, title or messages exist in a notewindow,
pop up the notewindow.
Arrow button
If the dropdown is not open, expand the dropdown list. Otherwise, close the dropdown list.
Option item
Tap on an option item in the dropdown list to select.
Option item
Enter or Space
Select the highlighted choice from the dropdown and close the dropdown.
Option item
Select the highlighted choice from the dropdown and transfer focus to the next
tabbable element on the page.
Input field
Collapse the dropdown list. If the dropdown is already closed, do nothing.
Input field
Enter
If the selected value text has been deleted, clear the value and close the dropdown.
If filtering, select the highlighted choice from the dropdown and close the
dropdown.
Input field
If the selected value text has been deleted, clear the value and transfer focus
to the next tabbable element on the page. If filtering, select the highlighted choice
from the dropdown and transfer focus to the next tabbable element on the page.
Input field
UpArrow or DownArrow
If the dropdown is not open, expand the dropdown list. Otherwise, transfer
focus into the dropdown list.
Dropdown
UpArrow or DownArrow
Highlight the option item in the dropdown list in the direction of the arrow.
Dropdown
Collapse the dropdown list.
Select
Tab In
Set focus to the Select. If hints, title or messages exist in a notewindow,
pop up the notewindow.
Page Load
If there is an initially selected value, setting the
valueItem
attribute initially can improve page load performance because the element will not have to fetch the selected data from the data provider.
The dropdown data isn't fetched until the user opens the dropdown.
Accessibility
For accessibility, set the
label-hint
property.
If there is no visible label, then to make this accessible to screen reader users,
set the
label-hint
and
label-edge
='none'
which renders an aria-label with the label-hint text.
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.
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.
The
itemTemplate
slot is used to specify the template
for rendering each item in the dropdown list.
The slot must be a <template> element.
When the template is executed for each item, it will have access to the binding context
containing the following properties:
$current - an object that contains information for the current item. (See the table
below for a list of properties available on $current)
alias - if the data-oj-as attribute was specified on the template, the value will be
used to provide an application-named alias for $current.
If no
itemTemplate
is specified, the component will
render based on the value of the
itemText
property.
Specifies whether the advanced search link is shown in the dropdown when the user filters.
It is up to the application to show its own UI when the link is triggered.
Property change listener attribute (
must be of type function, see
Events and Listeners
for additional information.
)
on-advanced-search-changed
Specifies how many columns this component should span.
This only takes effect when this component is a child of a form layout
that has direction 'row'.
Property change listener attribute (
must be of type function, see
Events and Listeners
for additional information.
)
on-column-span-changed
Specifies whether an ancestor container, like oj-c-form-layout, is readonly.
This affects whether a readonly component renders in full or mixed readonly mode.
This is also currently used to determine if there is an ancestor container by checking if the value
is not equal to undefined.
Property change listener attribute (
must be of type function, see
Events and Listeners
for additional information.
)
on-container-readonly-changed
Property change listener attribute (
must be of type function, see
Events and Listeners
for additional information.
)
on-data-changed
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.
Property change listener attribute (
must be of type function, see
Events and Listeners
for additional information.
)
on-disabled-changed
Property change listener attribute (
must be of type function, see
Events and Listeners
for additional information.
)
on-display-options-changed
Property change listener attribute (
must be of type function, see
Events and Listeners
for additional information.
)
on-help-changed
Property change listener attribute (
must be of type function, see
Events and Listeners
for additional information.
)
on-help-hints-changed
Specifies how to get the text string to render for a data item.
This attribute can be set to either:
a string that specifies the name of a top level data attribute to render as text, or
a callback function that takes a properties object and returns the text string to
display
This text will be rendered for the selected value of the component and for each data item
in the dropdown. When rendered for the dropdown items, default matching search term
highlighting will be applied.
Property change listener attribute (
must be of type function, see
Events and Listeners
for additional information.
)
on-item-text-changed
Property change listener attribute (
must be of type function, see
Events and Listeners
for additional information.
)
on-label-edge-changed
Property change listener attribute (
must be of type function, see
Events and Listeners
for additional information.
)
on-label-hint-changed
Property change listener attribute (
must be of type function, see
Events and Listeners
for additional information.
)
on-label-start-width-changed
Property change listener attribute (
must be of type function, see
Events and Listeners
for additional information.
)
on-label-wrapping-changed
List of messages an app would add to the component when it has business/custom validation
errors that it wants the component to show. This allows the app to perform further validation
before sending data to the server. When this option is set the message shows to the
user right away. To clear the custom message, set
messagesCustom
back to an empty array.
See the
Validation and Messages
section
for details on when the component clears
messagesCustom
;
for example, when full validation is run.
Property change listener attribute (
must be of type function, see
Events and Listeners
for additional information.
)
on-messages-custom-changed
Property change listener attribute (
must be of type function, see
Events and Listeners
for additional information.
)
on-placeholder-changed
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.
Property change listener attribute (
must be of type function, see
Events and Listeners
for additional information.
)
on-readonly-changed
This property set to
false
implies that a value is not required to be provided by the user.
This is the default.
This property set to
true
implies that a value is required to be provided by the user.
In the Redwood theme, by default, a Required text is rendered inline when the field is empty.
If user-assistance-density is 'compact', it will show on the label as an icon.
The Required error text is based on Redwood UX designs, and it is not recommended that
it be changed.
To override the required error message,
use the
required-message-detail
attribute.
The component's label text is passed in as a token {label} and can be used in the message detail.
When required is set to true, an implicit
required validator is created, i.e.,
new RequiredValidator()
. The required validator is the only
validator to run during initial render, and its error is not shown to the user at this time;
this is called deferred validation. The required validator also runs during normal validation;
this is when the errors are shown to the user.
See the
Validation and Messaging
section for details.
When the
required
property changes due to programmatic intervention,
the component may clear component messages and run validation, based on the current state it's in.
Running Validation when required property changes
if component is valid when required is set to true, then it runs deferred validation on
the value property. If the field is empty, the valid state is invalidHidden. No errors are
shown to the user.
if component is valid when required is set from true to false, then no validation is run.
if component is invalid and has deferred messages (invalidHidden) when required is set to false, then
component messages are cleared (messages-custom messages are not cleared)
but no deferred validation is run because required is false.
if component is invalid and currently showing invalid messages (invalidShown) when required is changed
to either true or false, then
component messages are cleared and normal validation is run using the current display value.
if there are validation errors, then
value
property is not updated and the error is shown.
if no errors result from the validation, the
value
property is updated; page author can listen to the
valueChanged
event on the component to clear custom errors.
Clearing Messages when required property changes
Only messages created by the component, like validation messages, are cleared when the required property changes.
messagesCustom
property is not cleared.
Property change listener attribute (
must be of type function, see
Events and Listeners
for additional information.
)
on-required-changed
The component-specific message detail when the required validation fails.
If the component needs a required validation error message that is different from the default,
set this property. It should be a translated string.
Property change listener attribute (
must be of type function, see
Events and Listeners
for additional information.
)
on-required-message-detail-changed
Property change listener attribute (
must be of type function, see
Events and Listeners
for additional information.
)
on-text-align-changed
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.
Property change listener attribute (
must be of type function, see
Events and Listeners
for additional information.
)
on-user-assistance-density-changed
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.
Property change listener attribute (
must be of type function, see
Events and Listeners
for additional information.
)
on-valid-changed
When the
value
property changes due to programmatic
intervention, the component always clears all messages
including
messagesCustom
, runs deferred validation, and
always refreshes the UI display value.
Running Validation
component always runs deferred validation; the
valid
property is updated with the result.
Property change listener attribute (
must be of type function, see
Events and Listeners
for additional information.
)
on-value-changed
The
valueItem
is similar to the
value
, but is a an object that
contain both a key and data, and optional metadata.
The key will be set as the
value
of the element.
The
value
and
valueItem
are kept in sync, both during programmatic property sets as well as during interactive user
selection.
If initially both are set, the selected value in the
value
attribute have precedence.
Note: If there is an initial selection, setting it via the
valueItem
attribute initially can improve page load
performance because the element will not have to fetch the selected data from the data
provider.
If
valueItem
is not specified or the selected value is
missing, then the selected data will be fetched from the data provider.
Property change listener attribute (
must be of type function, see
Events and Listeners
for additional information.
)
on-value-item-changed
Property change listener attribute (
must be of type function, see
Events and Listeners
for additional information.
)
on-virtual-keyboard-changed
Event triggered when the user clicks or presses Enter on the advanced search link in the
dropdown.
Set the
advancedSearch
property to
'on'
to enable this feature.
Resets the component by clearing all messages and messagesCustom attribute
and updates the component's display value using the attribute value.
User entered will be erased when this method is called.
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.
If enabled, validates the component's display value (or null if display value is empty) 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.
If the component is readonly or disabled, returns a Promise that resolves to 'valid'
without doing any validation.
Promise resolves to "valid" if there were no converter parse errors and the component
passed all validations. The Promise resolves to "valid" if the component is disabled or readonly.
The Promise resolves to "invalid" if there were converter
parse errors or if there were validation errors.
Documentation generated by
JSDoc 3.6.11
on Fri May 03 2024 18:10:00 GMT+0000 (Coordinated Universal Time)
