Element: <oj-select-one>

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 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.ojInputText#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#asyncValidators .
Deferred validation messages are displayed only when page author requests for it explicitly in one of the following ways:
calls the `showMessages` method on the component
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.
In the Redwood theme, by default all user assistance text shows inline. For input components, it shows when the field takes focus. In other components it shows all the time. See the user-assistance-density property for other ways the user assistance text can render, 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.

In the Alta theme all the user assistance text are displayed to the user. By default help.instruction and the validator/converter hints show in a notewindow that is displayed when the field takes focus. The help-hints render as a help icon on the label and when clicked show in a notewindow. Note: If there is no label, help-hints help icon will not show.

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 Select box or Arrow button If the drop down is not open, expand the drop down list. Otherwise, close the drop down list. If hints, title or messages exist in a notewindow, pop up the notewindow on tapping on select box. Option item Tap on a option item in the drop down list to select a new item. Drop down `swipe up/down` Scroll the drop down list vertically Drop down `UpArrow or DownArrow` Highlight the option item in the direction of the arrow. If the drop down is not open, expand the drop down list. Drop down Collapse the drop down list. If the drop down is already closed, do nothing. Select box or search box `any characters for the search term` filter down the results with the search term. Select `Tab In` Set focus to the select. If hints, title or messages exist in a notewindow, pop up the notewindow.

Page Load

If the options attribute is a data provider, and if there is an initially selected value, setting the valueOption attribute initially can improve page load performance because the element will not have to fetch the selected label from the data provider.

When using a data provider and renderMode is 'jet', the dropdown data isn't fetched until the user opens the dropdown.

Reading direction

As with any JET element, in the unusual case that the directionality (LTR or RTL) changes post-init, the Select must be refresh() ed. Accessibility The element will decorate its associated label with required and help information, if the required and help attributes are set. For accessibility, set label-hint or associate an oj-label with the form component. 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. If using an oj-label instead of the label-hint attribute, then put an id on the form component element, and set the oj-label's for attribute to be the form component's id.

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.

Migration To migrate from oj-select-many to oj-c-select-multiple, you need to revise the import statement and references to oj-c-select-multiple in your app. Please note the changes between the two components below.

ItemText attribute

This attribute is required to specify how to get the text string to render for a data item.

LabelEdge attribute

The enum values for the label-edge attribute have been changed from 'inside', 'provided' and 'none' to 'start', 'inside', 'top' and 'none'. If you are using this component in a form layout and would like the form layout to drive the label edge of this component, leave this attribute unset. The application no longer has to specify 'provided' for this attribute. If you want to override how the label is positioned, set this attribute to the corresponding value.

MaximumResultCount attribute

This attribute is not supported. The dropdown list supports fetching more data in blocks as the user scrolls.

MessagesCustom attribute

The type of the


   severity

property of the messages in the array has changed from


   Message.SEVERITY_TYPE | Message.SEVERITY_LEVEL

, essentially


   string | number

, to simply


   'error' | 'confirmation' | 'info' | 'warning'

. These values are the same as the previously supported string values. The application can no longer specify severity as a number, including hardcoded numbers, one of the


   Message.SEVERITY_LEVEL

constants, or the value returned from a call to the


   Message.getSeverityLevel

method.

MinimumResultsForSearch attribute

This attribute is not supported. Searching is always enabled by typing into the text field.

OptionRenderer attribute

This attribute is not supported. The text rendered for an item can be customized via the item-text attribute.

Options attribute

The only way to provide data to JET Select Multiple is through a DataProvider set via the data attribute. Using <oj-option> and <oj-optgroup> child tags is not supported. For cases with a small set of fixed data, use an ArrayDataProvider .

OptionsKeys attribute

This attribute is not supported. The text rendered for an item can be customized via the item-text attribute.

PickerAttributes attribute

This attribute is not supported. There is no replacement.

TextAlign attribute

The usage of the style classes: oj-form-control-text-align-right, oj-form-control-text-align-start and oj-form-control-text-align-end is now replaced with this attribute. The value of this attribute maps to these style classes as shown below: .oj-form-control-text-align-right maps to 'right' .oj-form-control-text-align-start maps to 'start' .oj-form-control-text-align-end maps to 'end'

Translations attribute

The translations.required.message-detail attribute has changed to required-message-detail.

Value attribute

The value attribute accepts a Set of data provider keys instead of an array of keys.

ValueOptions attribute

The value-options attribute is not supported. The replacement is the valueItems attribute.

Refresh method

The refresh method is no longer supported. The application should no longer need to use this method. If the application wants to reset the component (remove messages and reset the value of the component), please use the reset method.

Animation Events

ojAnimateStart and ojAnimateEnd events are no longer supported.

Custom Label

Adding a custom <oj-label> for the form component is no longer supported. The application should use the label-hint attribute to add a label for the form component. The application should no longer need to use the <oj-label-value> component to layout the form component. The application can use the label-edge attribute and label-start-width attribute to customize the label position and label width (only when using start label).

DescribedBy attribute

The described-by attribute is not meant to be set by an application developer directly as stated in the attribute documentation. This attribute is not carried forward to the core pack component.

Typescript Import Format

//To typecheck the element APIs, import as below.
import { SelectOneElement } from "ojs/ojselectcombobox";

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

For additional information visit:

Using JET Custom Elements

Using JET with TypeScript

JET Module Loading

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.

<oj-select-one class="oj-form-control-full-width">
  <oj-option value="option 1">option 1</oj-option>
  <oj-option value="option 2">option 2</oj-option>
  <oj-option value="option 3">option 3</oj-option>
  <oj-option value="option 4">option 4</oj-option>
</oj-select-one>

In the Redwood theme the default max width of a text field is 100%. These max width convenience classes are available to create a medium or small field.
The class is applied to the root element.

Classes:

<oj-select-one class="oj-form-control-max-width-md">
  <oj-option value="option 1">option 1</oj-option>
  <oj-option value="option 2">option 2</oj-option>
  <oj-option value="option 3">option 3</oj-option>
</oj-select-one>

In the Redwood theme the default width of a text field is 100%. These width convenience classes are available to create a medium or small field.
The class is applied to the root element.

Classes:

<oj-select-one class="oj-form-control-width-md">
  <oj-option value="option 1">option 1</oj-option>
  <oj-option value="option 2">option 2</oj-option>
  <oj-option value="option 3">option 3</oj-option>
</oj-select-one>

<oj-select-one class="oj-form-control-text-align-right">
  <oj-option value="option 1">option 1</oj-option>
  <oj-option value="option 2">option 2</oj-option>
  <oj-option value="option 3">option 3</oj-option>
  <oj-option value="option 4">option 4</oj-option>
</oj-select-one>

The <oj-select-one> element accepts oj-option elements as children. See the oj-option documentation for details about accepted children and slots.

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. The oj-label sets the described-by attribute programmatically on the form component. This attribute is not meant to be set by an application developer directly. The described-by is copied to the aria-describedby attribute on the component's inner dom element, and it is needed for accessibility. Property change listener attribute ( must be of type function, see Events and Listeners for additional information. ) on-described-by-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

Display options for auxiliary content that determines whether or not it should be displayed. In the Redwood theme, the sub-properties of the display-options configure whether or not the types of information is shown. The values of these sub-properties are either 'display' or 'none'. In the Alta theme the sub-properties of the display-options configure aspects of visual behavior such as where types of information is shown. The values of these sub-properties are specified either as an array of strings or a string. When an array is specified the first display option takes precedence over the second display option and so on. When display-options changes due to programmatic intervention, the component updates its display to reflect the updated choices. For example, if you don't want to show the converter hint, set the display-options.converter-hint to 'none'. A side note: help.instruction and message detail text can include formatted HTML text, whereas hints and message summary text cannot. If you use formatted text, it should be accessible and make sense to the user if formatting wasn't there. The allowed html tags are: span, b, i, em, br, hr, li, ol, ul, p, small, pre. To format the help.instruction, you could do this:

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

Property change listener attribute ( must be of type function, see Events and Listeners for additional information. )


   on-display-options-changed

Display options for auxiliary converter hint text. The supported attribute values are theme dependent. In the Redwood theme, this attribute determines whether or not the converter hint should be displayed. The supported values are 'display' and 'none'. If you don't want to show the converter hint, set display-options.converter-hint to 'none'. It defaults to 'display'. To control where the hints display, e.g., inline or in a notewindow, then use the user-assistance-density attribute. In the Alta theme this attribute determines where and whether to show the converter hint. If you don't want to show the converter hint, set display-options.converter-hint to 'none'. The Alta theme supports these attribute values, most of which are deprecated: Array|'placeholder'|'notewindow'|'none'. The default is ['placeholder','notewindow']. Display options for auxiliary help instruction text that determines where it should be displayed in relation to the component. Display options for auxiliary message text. The supported attribute values are theme dependent. In the Redwood theme, this attribute determines whether or not the messages should be displayed. The supported values are 'display' and 'none'. If you don't want to show messages, set display-options.messages to 'none'. It defaults to 'display'. To control where the messages display, e.g., inline or in a notewindow, then use the user-assistance-density attribute. In the Alta theme this attribute determines where and whether to show the messages. If you don't want to show messages, set display-options.messages to 'none'. The Alta theme supports these attribute values, most of which are deprecated: Array|'inline'|'notewindow'|'none'. The default is ['inline']. Display options for auxiliary validator hint text. The supported attribute values are theme dependent. In the Redwood theme, this attribute determines whether or not the validator hint should be displayed. The supported values are 'display' and 'none'. If you don't want to show the validator hint, set display-options.validator-hint to 'none'. It defaults to 'display'. To control where the hints display, e.g., inline or in a notewindow, then use the user-assistance-density attribute. In the Alta theme this attribute determines where and whether to show the validator hint. If you don't want to show the validator hint, set display-options.validator-hint to 'none'. The Alta theme supports these attribute values, most of which are deprecated: Array|'notewindow'|'none'. The default is ['notewindow']. Property change listener attribute ( must be of type function, see Events and Listeners for additional information. )


   on-help-changed

A type of user assistance text. User assistance text is used to provide guidance to help the user understand what data to enter or select.

In the Redwood theme for clarity only one user assistance text shows to the user. The precedence rules are:

help.instruction shows;

if no help.instruction, then validator hint shows;

if no help.instruction or validator hint, then help-hints.definition shows;

if no help.instruction, validator hint, or help-hints.definition, then converter hint shows.

help-hints.source always shows along side the above.

In the Redwood theme, by default all user assistance text shows inline. For input components, it shows when the field takes focus. In other components it shows all the time. See the user-assistance-density property for other ways the user assistance text can render. In Alta theme, help.instruction displays in a notewindow when the field takes 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. The allowed html tags are: span, b, i, em, br, hr, li, ol, ul, p, small, pre. For example the help.instruction might look like:

<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. Property change listener attribute ( must be of type function, see Events and Listeners for additional information. )


   on-help-hints-changed

A type of user assistance text. User assistance text is used to provide guidance to help the user understand what data to enter or select. help-hints could come from a help system.

In the Redwood theme for clarity only one user assistance text shows to the user. The precedence rules are:

help.instruction shows;

if no help.instruction, then validator hint shows;

if no help.instruction or validator hint, then help-hints.definition shows;

if no help.instruction, validator hint, or help-hints.definition, then converter hint shows.

help-hints.source always shows along side the above.

In the Alta theme the help-hint.definition shows up when the user hovers over the help icon on the label, 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.

Help source URL associated with the component.

In the Redwood theme, the help-hints.source will show as a link inline to the field. For input components, it shows when the field takes focus. For other components, it shows all the time.

In the Alta theme, the help-hints.source will show as a a help icon next to the label. When clicked the page will navigate to the source url. 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.

Specifies how the label of the component is created when the


   label-hint

attribute is set on the component.

The default value varies by theme, and it works well for the theme in most cases. If the component is in an oj-form-layout, the label-edge attribute could come from the oj-form-layout's label-edge attribute. The oj-form-layout component uses the MetadataTypes.PropertyBinding provide property to provide and uses the MetadataTypes.ProvideProperty transform property to transform its label-edge attribute to any descendent components that are configured to consume it. For example, if the oj-form-layout's label-edge attribute is set to "top" or "start", and a descendent form component does not have its label-edge attribute set, the form component's label-edge will be the transformed value "provided".

The component creates the label using the


   label-hint

attribute.

For text input components (such as oj-input-text), the label floats over the input element but moves up on focus or when the component has a value.

For non-text input components (such as oj-checkboxset), the label is created at the top of the component and doesn't move.

The component will not have a label, regardless of whether it's in an oj-form-layout or not.

If the component has a label-hint attribute but no labelled-by, aria-label, or aria-labelledby attribute, the label-hint value will be used as the aria-label.

Note that if the component already has an external label, "none" should not be specified and "provided" should be used instead. Otherwise it may end up with conflicting label information.

Label is provided by the parent if the parent is an oj-form-layout.

oj-form-layout provides the label using the label-hint from the form control and the label-edge from oj-form-layout.

If there is no oj-form-layout, use an oj-label.

Property change listener attribute ( must be of type function, see Events and Listeners for additional information. )


   on-label-edge-changed

Represents a hint for rendering a label on the component.

This is used in combination with the label-edge attribute to control how the label should be rendered.

When label-edge is "provided", it gives a hint to oj-form-layout parent element to create an oj-label element for the component. When the


   label-hint

attribute changes, oj-form-layout element refreshes to display the updated label information. When label-edge is "inside", it gives a hint to the component itself to render a label. When label-edge is "none", and if the component has no labelled-by, aria-label, or aria-labelledby attribute, the label-hint value will be used as the aria-label. Property change listener attribute ( must be of type function, see Events and Listeners for additional information. )


   on-label-hint-changed

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. Property change listener attribute ( must be of type function, see Events and Listeners for additional information. )


   on-labelled-by-changed

The maximum number of results that will be displayed in the dropdown when the options attribute is bound to a data provider.

If more than the maximum number of results are available from data provider then user needs to filter further. A value less than 1 indicates there is no maximum limit and all the results will be fetched and displayed in the dropdown.

When the options attribute is bound to a hierarchical data source like a oj.TreeDataProvider , this attribute represents the maximum number of leaf results that will be displayed in the dropdown.

Note: This attribute has no effect when the options attribute is bound to an array/observable array or when the component renders an oj-option element or an oj-optgroup element as children.

Property change listener attribute ( must be of type function, see Events and Listeners for additional information. )


   on-maximum-result-count-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.

Each message in the array is an object that duck types oj.Message. See Message for details. message detail text can include formatted HTML text, whereas hints and message summary text cannot. If you use formatted text, it should be accessible and make sense to the user if formatting wasn't there. The allowed html tags are: span, b, i, em, br, hr, li, ol, ul, p, small, pre. To format the message detail, you could do this:

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

See the Validation and Messages section for details on when the component clears


   messagesCustom

; for example, when full validation is run.

In the Redwood theme, the Message summary is not displayed to the user, so make sure to have a Message detail set in your Message object. Property change listener attribute ( must be of type function, see Events and Listeners for additional information. ) on-messages-custom-changed The threshold for showing the search box in the dropdown when it's expanded. The search box is always displayed when the results size is greater than the threshold, otherwise the search box is initially turned off. However, the search box is displayed as soon as the user starts typing. Property change listener attribute ( must be of type function, see Events and Listeners for additional information. ) on-minimum-results-for-search-changed The renderer function that renders the content of each option. The function should return an oj-option element (for leaf option) or an oj-optgroup element (for group option).

It is not necessary to set the "value" attribute on the oj-option as it is available from the options data.

Note: Prior to version 6.1.0, the function could also return one of the following:

An Object with the following property:

insert: HTMLElement - A DOM element representing the content of the option.

undefined: If the developer chooses to manipulate the option content directly, the function should return undefined.

This is deprecated and support may be removed in the future.

The option-renderer decides only how the options' content has to be rendered in the drop down. Once an option is selected from the drop down, what value has to be displayed in the in input field is decided by the label field in the data object. See options and options-keys for configuring option label and value.

The context parameter passed to the renderer contains the following keys:

Description index The index of the option, where 0 is the index of the first option. In the hierarchical case the index is relative to its parent. depth The depth of the option. The depth of the first level children under the invisible root is 0. Whether the option is a leaf or a group. The data object for the option. parentElement The option label element. The renderer can use this to directly append content. Property change listener attribute ( must be of type function, see Events and Listeners for additional information. )


   on-option-renderer-changed

The option items for the Select. This attribute can be used instead of providing a list of


   oj-option


   oj-optgroup

child elements of the Select element. This attribute accepts:

an array of


    oj.ojSelect.Option

and/or


    oj.ojSelect.Optgroup

Use


    oj.ojSelect.Option

for a leaf option.

Use


    oj.ojSelect.Optgroup

for a group option.

a data provider. This data provider must implement oj.DataProvider .


    value


    oj.ojSelect.Option

must be the row key in the data provider.

A maximum of 15 rows will be displayed in the dropdown. If more than 15 results are available then users need to filter further. Please note that users can't filter further if render-mode is


    native

If the data provider supports the filter criteria capability including the contains (


    $co or $regex

) operator, JET Select will request the data provider to do filtering. Otherwise it will filter internally.

Running Validation when required property changes

if component is valid when required is set to true, then it runs deferred validation on the value property. If the field is empty, the valid state is invalidHidden. No errors are shown to the user.

if component is invalid and has deferred messages when required is set to false, then component messages are cleared (messages-custom messages are not cleared) but no deferred validation is run because required is false.

if component is invalid and currently showing invalid messages when required is set, then component messages are cleared and normal validation is run using the current display value.

if there are validation errors, then


    value

property is not updated and the error is shown.

if no errors result from the validation, the


    value

property is updated; page author can listen to 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

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. Property change listener attribute ( must be of type function, see Events and Listeners for additional information. ) on-translations-changed

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

The default value is 'reflow' when the form component is not a descendent of an oj-form-layout component. When the form component is a descendent of an oj-form-layout, the default value comes from the oj-form-layout's


   user-assistance-density

attribute value. The oj-form-layout component uses the MetadataTypes.PropertyBinding


   provide

property to provide its


   user-assistance-density

attribute value to be consumed by descendent components. The form components are configured to consume the


   user-assistance-density

property if an ancestor provides it and it is not explicitly set on the form component. Example, oj-form-layout defaults user-assistance-density='efficient', so all its form components descendents will have user-assistance-density='efficient' by default. Messages, help, hints, and required will not be shown inline; they will show in a mode that keeps the screen more compact, like a popup for the messages, and a required icon to indicate Required. 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

The value of the element. It supports any type. Select only accepts a value that's in the drop down list. When the value attribute is not set, the first option is used as its initial value if it exists. Trying to set a new value that's not in the drop down list fails validation and the new value is not set.

If a value is specified before the data for the drop down list is available, then that value is set initially. When the data for the drop down list is available, the initially set value is validated. If it fails validation, the first option will be set as the value instead.

Note: When the options attribute is bound to a data provider, the valueChanged event will include data and metadata information if it is available from data provider.

Property change listener attribute ( must be of type function, see Events and Listeners for additional information. )


   on-value-changed

The


   valueOption

is similar to the


   value

, but is an Object which contains both a value and display label. The


   value

and


   valueOption

are kept in sync. If initially both are set, the selected value in the


   value

attribute has precedence.

Note: When the options attribute is bound to a data provider, the valueOptionChanged event will include data and metadata information if it is available from data provider.

Setting the valueOption attribute initially can improve page load performance if there are initially selected values. But, the initial valueOptionChanged event will not include data and metadata information, because the element doesn't have to fetch the selected label from the data provider.

If valueOption is not specified or the selected value is missing, then the label 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-option-changed

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

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

The default animations are controlled via the theme: // default animations for notewindow help and hints and messages $popupTailOpenAnimation: (effect: "zoomIn", transformOrigin: "#myPosition") !default; $popupTailCloseAnimation: (effect: "none") !default; // default animations for Redwood's inline messages shown when userAssistanceDensity // is reflow or efficient. $messageComponentInlineOpenAnimation: (effect: "fadeIn", duration: "100ms", timingFunction: "linear") !default; $messageComponentInlineCloseAnimation: (effect: "fadeOut", duration: "100ms", timingFunction: "linear") !default; // default animations for Alta's "inline" display option $messageComponentInlineOpenAnimation: (effect: "expand", startMaxHeight: "#oldHeight") !default; $messageComponentInlineCloseAnimation: (effect: "collapse", endMaxHeight: "#newHeight") !default;

"inline-hints-open" - when an inline helphints container opens

"inline-hints-close" - when an inline helphints container closes

"inline-open" - when an inline message container opens or increases in size

"inline-close" - when an inline message container closes or decreases in size

"notewindow-open" - when a note window opens

"notewindow-close" - when a note window closes

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. 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. Refreshes the visual state of the select. JET elements require a


   refresh()

after the DOM is programmatically changed.

This method does not accept any arguments. 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. 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. 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. 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.

All messages are cleared, including custom messages added by the app.

The implicit required validator is run first if the component is marked required.

At the end of validation if there are errors, the messages are shown. If there were no errors, then the


    value

option is updated.

Documentation generated by JSDoc 3.4.3 on Sat May 11 2024 03:10:42 GMT+0000 (Coordinated Universal Time)

Index

Concepts

Elements

Non-Element API

Modules

Non-Element Styling

Globals

Page Load

ItemText attribute

LabelEdge attribute

MaximumResultCount attribute

MessagesCustom attribute

MinimumResultsForSearch attribute

OptionRenderer attribute

Options attribute

OptionsKeys attribute

PickerAttributes attribute

TextAlign attribute

Translations attribute

Value attribute

ValueOptions attribute

Refresh method

Animation Events

Custom Label

DescribedBy attribute

Typescript Import Format

Classes:

Classes:

Running Validation when required property changes

Clearing Messages when required property changes