Element: <oj-combobox-many>

Oracle® JavaScript Extension Toolkit (JET)
15.1.0
F83698-01

Since:
  • 0.6.0
Module:
  • ojselectcombobox

QuickNav

Slots

Attributes

Events

Methods

Other Topics


JET Combobox Many

Description: JET Combobox Many provides support for multi-select, text input, and search filtering.

Inline options allow you to configure dropdown content with minimal effort. Adding start and end icons can be done directly in markup. However, this approach fully realizes every option into live DOM and is thus not suitable for large data. Inline options also do not support dynamic content.

For medium-sized static content or cases where the set of options can only be computed at runtime while initializing the component (and is not subject to further modification), using oj-bind-for-each bound to a simple (non-observable) Array is more convenient than manually inlining each option. However, just like directly specifying inline options, this approach is not suitable for large or dynamic data.

For cases where the data is large or dynamic, options should be specified using a DataProvider. This approach will limit the amount of live DOM, regardless of data size, and is also capable of reacting to changes in data. However, configuring dropdown content may require more work than the previous approaches.

A JET Combobox Many can be created with the following markup.


<oj-combobox-many>
  <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-combobox-many>

A JET Combobox Many can be created with a DataProvider.


<oj-combobox-many options="[[dataprovider]]">
</oj-combobox-many>

See the Combobox many demo for inline options and DataProvider usage.

Differences between Select and Combobox components

oj-select-* components and oj-combobox-* components may look and feel similar, but these components are different and are intended for very different use cases.

While oj-select-* components allow one to filter the data in the dropdown, it is not possible to enter values that are not available in the data. This makes oj-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 one 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-select-single instead of the deprecated oj-select-one.

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

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.

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

Target Gesture Action
Input Field Tap 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.
Option Item Tap Tap on an option item in the drop down list to add to selection.
Selected item with remove icon Tap Remove item from the selected items list by tapping on the remove icon.

Disabled option items receive no highlight and are not selectable.

Keyboard End User Information

Target Key Action
Option item Enter Select the highlighted item from the drop down.
Input field Enter Add the input text to selections.
Drop down UpArrow or DownArrow Highlight the option item on the drop down list in the direction of the arrow. If the drop down is not open, expand the drop down list.
Combobox LeftArrow or RightArrow Move focus to the previous or next selected item.
Selected item with remove icon Backspace or Delete Remove the selected item having focus.
Drop down Esc Collapse the drop down list. If the drop down is already closed, do nothing.
Combobox Tab In Set focus to the combobox. If hints, title or messages exist in a notewindow, pop up the notewindow.

Disabled option items receive no highlight and are not selectable.

Performance

Page Load

If the options attribute is a data provider, and if there are initially selected values, setting the valueOptions attribute initially can improve page load performance because the element will not have to fetch the selected labels from the data provider.

When using a data provider, 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 Combobox 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.


Usage

Signature:

interface ComboboxManyElement<K, D, V= any>

Generic Parameters
ParameterDescription
KType of key of the dataprovider
DType of data from the dataprovider
VType of each item in the value of the component
Typescript Import Format
//To typecheck the element APIs, import as below.
import { ComboboxManyElement } from "ojs/ojselectcombobox";

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

For additional information visit:

Note: Application logic should not interact with the component's properties or invoke its methods until the BusyContext indicates that the component is ready for interaction.


Styling Classes

.oj-form-control-full-width
Changes the max-width to 100% so that form components will occupy all the available horizontal space.
Example
<oj-combobox-many 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-combobox-many>

Category: Max Width

Note: This category of style classes is not supported in the following themes: Alta

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

Classes:

.oj-form-control-max-width-sm
.oj-form-control-max-width-md

Example
<oj-combobox-many 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-combobox-many>

Category: Width

Note: This category of style classes is not supported in the following themes: Alta

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

Classes:

.oj-form-control-width-sm
.oj-form-control-width-md

Example
<oj-combobox-many 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-combobox-many>

Category: Text Alignment

Classes that help align text of the element.

Classes:

.oj-form-control-text-align-right
.oj-form-control-text-align-start
.oj-form-control-text-align-end

Example
<oj-combobox-many 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-combobox-many>

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.

Default

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

contextMenu

The contextMenu slot is set on the oj-menu within this element. This is used to designate the JET Menu that this component should launch as a context menu on right-click, Shift-F10, Press & Hold, or component-specific gesture. If specified, the browser's native context menu will be replaced by the JET Menu specified in this slot.

The application can register a listener for the Menu's ojBeforeOpen event. The listener can cancel the launch via event.preventDefault(), or it can customize the menu contents by editing the menu DOM directly, and then calling refresh() on the Menu.

To help determine whether it's appropriate to cancel the launch or customize the menu, the ojBeforeOpen listener can use component API's to determine which table cell, chart item, etc., is the target of the context menu. See the JSDoc of the individual components for details.

Keep in mind that any such logic must work whether the context menu was launched via right-click, Shift-F10, Press & Hold, or component-specific touch gesture.

Deprecated:
Since Description
13.0.0 This web component no longer supports launching a context menu.

Attributes

async-validators :Array.<oj.AsyncValidator.<Array.<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 e.g. for number new NumberConverter.IntlNumberConverter(converterOption) to get the converter instance, then call converter.format(value).

Hints exposed by validators are shown inline by default in the Redwood theme when the field has focus. In the Alta theme, validator hints are shown in a notewindow on focus, or as determined by the 'validatorHint' property set on the display-options attribute. In either theme, you can turn off showing validator hints by using the 'validatorHint' property set to 'none' on 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 validators attribute.


Deprecated:
Since Description
8.0.0 Use the validators property instead for either regular Validators or AsyncValidators.
Default Value:
  • []
Names
Item Name
Property asyncValidators
Property change event asyncValidatorsChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-async-validators-changed

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

A converter instance or Promise to a converter instance or one that duck types oj.Converter.

In combobox, the converter is used to parse/format the values entered by the user in the text field while the dropdown items will be unaffected.

Please note that the option items provided will not be formatted using the converter. The text provided by the label property (or the property specified by the options-keys.label api) of the option item or in case of the inline options the text provided in the <oj-option> will be used for the display label of the option items in the dropdown.
Similarly, when an option from the dropdown is selected, the value and the label will be used as it appears in the data. This applies to both for rendering the selected item in the UI as well as for populating the valueOption or valueOptions property. In order to have consistent formatting, it is recommended that the app developers use the same converter instance to format the options.

The hint exposed by the converter is shown inline by default in the Redwood theme when the field has focus. In the Alta theme, converter hints are shown in a notewindow on focus, or as determined by the 'converterHint' property set on the display-options attribute. In either theme, you can turn off showing converter hints by using the 'converterHint' property set to 'none' on the display-options attribute.

In the Redwood theme, only one hint shows at a time, so the precedence rules are: help.instruction shows; if no help.instruction then validator hints show; if none, then help-hints.definition shows; if none, then converter hint shows. help-hints.source always shows along with the other help or hint.

When converter property changes due to programmatic intervention, the element performs various tasks based on the current state it is in.

Steps Performed Always

  • Any cached converter instance is cleared and new converter created. The converter hint is pushed to messaging. E.g., notewindow displays the new hint(s).

Running Validation

  • if element is valid when converter property changes, the display value is refreshed.
  • if element is invalid and is showing messages when converter property changes, then all messages generated by the element are cleared and full validation run using its current display value.
    • if there are validation errors, then value property is not updated, and the errors are shown. The display value is not refreshed in this case.
    • if no errors result from the validation, value property is updated; page author can listen to the valueChanged event on the value property 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, then the display value is refreshed with the formatted value provided by converter.

Clearing Messages

  • When element messages are cleared in the cases described above, messages created by the element are cleared.
  • messages-custom property is not cleared. Page authors can choose to clear it explicitly when setting the converter property.

Deprecated:
Since Value Description
8.0.0 oj.Validation.RegisteredConverter Defining a converter with an object literal with converter type and its options (aka JSON format) has been deprecated and does nothing. If needed, you can make the JSON format work again by importing the deprecated module you need, like ojvalidation-base.
Default Value:
  • null
Names
Item Name
Property converter
Property change event converterChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-converter-changed

(nullable) described-by :string

The oj-label sets the described-by attribute programmatically on the form component. This attribute is not meant to be set by an application developer directly. The described-by is copied to the aria-describedby attribute on the component's inner dom element, and it is needed for accessibility.
Since:
  • 4.0.0
Names
Item Name
Property describedBy
Property change event describedByChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-described-by-changed

disabled :boolean

Whether the component is disabled. The default is false.

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

  • when a required component is initialized as disabled value="{{currentValue}}" required disabled, deferred validation is skipped.
  • when a disabled component is enabled,
    • if component is invalid and showing messages then all component messages are cleared, and full validation run using the display value.
      • if there are validation errors, they are shown.
      • if no errors result from the validation, the value property is updated. Page authors can listen to 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, see Events and Listeners for additional information.) on-disabled-changed

display-options :Object

Display options for auxiliary content that determines whether or not it should be displayed.

In the Redwood theme, the sub-properties of the display-options configure whether or not the types of information is shown. The values of these sub-properties are either 'display' or 'none'.

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>

Since:
  • 0.7
Names
Item Name
Property displayOptions
Property change event displayOptionsChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-display-options-changed

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

Display options for auxiliary converter hint text. The supported attribute values are theme dependent.

In the Redwood theme, this attribute determines whether or not the converter hint should be displayed. The supported values are 'display' and 'none'. If you don't want to show the converter hint, set display-options.converter-hint to 'none'. It defaults to 'display'. To control where the hints display, e.g., inline or in a notewindow, then use the user-assistance-density attribute.

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'>|'placeholder'|'notewindow'|'none'. The default is ['placeholder','notewindow'].

Deprecated:
Since Value Description
9.1.0 Array<'placeholder'|'notewindow'|'none'>,'placeholder','notewindow' These types are no longer supported. They are used for the Alta theme only. The Redwood theme uses 'display'|'none' and the user-assistance-density attribute.
Since:
  • 9.1.0
Names
Item Name
Property displayOptions.converterHint

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

Display options for auxiliary help instruction text that determines where it should be displayed in relation to the component.
Deprecated:
Since Description
9.0.0 If you want none, remove help-instruction attribute.
Default Value:
  • ['notewindow']
Since:
  • 9.0.0
Names
Item Name
Property displayOptions.helpInstruction

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

Display options for auxiliary message text. The supported attribute values are theme dependent.

In the Redwood theme, this attribute determines whether or not the messages should be displayed. The supported values are 'display' and 'none'. If you don't want to show messages, set display-options.messages to 'none'. It defaults to 'display'. To control where the messages display, e.g., inline or in a notewindow, then use the user-assistance-density attribute.

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'>|'inline'|'notewindow'|'none'. The default is ['inline'].

Deprecated:
Since Value Description
9.1.0 Array<'inline'|'notewindow'|'none'>,'inline','notewindow' These types are no longer supported. They are used for the Alta theme only. The Redwood theme uses 'display'|'none' and the user-assistance-density attribute.
Since:
  • 9.1.0
Names
Item Name
Property displayOptions.messages

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

Display options for auxiliary validator hint text. The supported attribute values are theme dependent.

In the Redwood theme, this attribute determines whether or not the validator hint should be displayed. The supported values are 'display' and 'none'. If you don't want to show the validator hint, set display-options.validator-hint to 'none'. It defaults to 'display'. To control where the hints display, e.g., inline or in a notewindow, then use the user-assistance-density attribute.

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'>|'notewindow'|'none'. The default is ['notewindow'].

Deprecated:
Since Value Description
9.1.0 Array<'notewindow'|'none'>,'notewindow' These types are no longer supported. They are used for the Alta theme only. The Redwood theme uses 'display'|'none' and the user-assistance-density attribute.
Since:
  • 9.1.0
Names
Item Name
Property displayOptions.validatorHint

help :Object

Form component help information.
Since:
  • 0.7.0
Names
Item Name
Property help
Property change event helpChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-help-changed

help.instruction :string

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

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

  • help.instruction shows;
  • if no help.instruction, then validator hint shows;
  • if no help.instruction or validator hint, then help-hints.definition shows;
  • if no help.instruction, validator hint, or help-hints.definition, then converter hint shows.
  • help-hints.source always shows along side the above.

In the Redwood theme, by default all user assistance text shows inline. For input components, it shows when the field takes focus. In other components it shows all the time. See the user-assistance-density property for other ways the user assistance text can render.

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.

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

help-hints :Object

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

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

(nullable) help-hints.definition :string

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

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

  • help.instruction shows;
  • if no help.instruction, then validator hint shows;
  • if no help.instruction or validator hint, then help-hints.definition shows;
  • if no help.instruction, validator hint, or help-hints.definition, then converter hint shows.
  • help-hints.source always shows along side the above.

In the Redwood theme, by default all user assistance text shows inline. For input components, it shows when the field takes focus. In other components it shows all the time. See the user-assistance-density property for other ways the user assistance text can render.

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.

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

(nullable) help-hints.source :string

Help source URL associated with the component.

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

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.

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

label-edge :('inside'|'none'|'provided')

Specifies how the label of the component is created when the label-hint attribute is set on the component.

The default value varies by theme, and it works well for the theme in most cases. If the component is in an oj-form-layout, the label-edge attribute could come from the oj-form-layout's label-edge attribute. The oj-form-layout component uses the MetadataTypes.PropertyBinding provide property to provide and uses the MetadataTypes.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".

Supported Values:
Value Description
inside The component creates the label using the label-hint attribute.

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

For non-text input components (such as oj-checkboxset), the label is created at the top of the component and doesn't move.
none The component will not have a label, regardless of whether it's in an oj-form-layout or not.

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

Note that if the component already has an external label, "none" should not be specified and "provided" should be used instead. Otherwise it may end up with conflicting label information.
provided Label is provided by the parent if the parent is an oj-form-layout.

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

If there is no oj-form-layout, use an oj-label.
Since:
  • 8.0.0
Names
Item Name
Property labelEdge
Property change event labelEdgeChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-label-edge-changed

label-hint :string

Represents a hint for rendering a label on the component.

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

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

When label-edge is "inside", it gives a hint to the component itself to render a label.

When label-edge is "none", and if the component has no labelled-by, aria-label, or aria-labelledby attribute, the label-hint value will be used as the aria-label.

Default Value:
  • ""
Since:
  • 4.1.0
Names
Item Name
Property labelHint
Property change event labelHintChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-label-hint-changed

labelled-by :string|null

The oj-label sets the labelledBy property programmatically on the form component to make it easy for the form component to find its oj-label component (a document.getElementById call.)

The application developer should use the 'for'/'id api to link the oj-label with the form component; the 'for' on the oj-label to point to the 'id' on the input form component. This is the most performant way for the oj-label to find its form component.

// setter myComp.labelledBy = "labelId";
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, see Events and Listeners for additional information.) on-labelled-by-changed

maximum-result-count :number

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.

Default Value:
  • 15
Since:
  • 8.0.0
Names
Item Name
Property maximumResultCount
Property change event maximumResultCountChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-maximum-result-count-changed

messages-custom :Array<oj.Message>

List of messages an app would add to the component when it has business/custom validation errors that it wants the component to show. This allows the app to perform further validation before sending data to the server. When this option is set the message shows to the user right away. To clear the custom message, set messagesCustom back to an empty array.

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

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

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

In the Redwood theme, the Message summary is not displayed to the user, so make sure to have a Message detail set in your Message object.

Default Value:
  • []
Supports writeback:
  • true
Since:
  • 0.7.0
Names
Item Name
Property messagesCustom
Property change event messagesCustomChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-messages-custom-changed

min-length :number

The minimum number of characters a user must type before a options filtering is performed. Zero is useful for local data with just a few items, but a higher value should be used when a single character search could match a few thousand items.
Default Value:
  • 0
Names
Item Name
Property minLength
Property change event minLengthChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-min-length-changed

(nullable) option-renderer :((param0: ojCombobox.OptionContext<D>) => Element)|null

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:

Key Description
componentElement A reference to the Combobox element.
parent The parent of the data item. The parent is null for root node.
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.
leaf Whether the option is a leaf or a group.
data The data object for the option.
parentElement The option label element. The renderer can use this to directly append content.
Default Value:
  • null
Names
Item Name
Property optionRenderer
Property change event optionRendererChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-option-renderer-changed

options :(Array.<(oj.ojCombobox.Option|oj.ojCombobox.Optgroup)>|DataProvider.<K, D>|null)

The option items for the Combobox. This attribute can be used instead of providing a list of oj-option or oj-optgroup child elements of the Combobox element. This attribute accepts:
  1. an array of oj.ojCombobox.Option and/or oj.ojCombobox.Optgroup.
    • Use oj.ojCombobox.Option for a leaf option.
    • Use oj.ojCombobox.Optgroup for a group option.
  2. a data provider. This data provider must implement DataProvider.
    • value in oj.ojCombobox.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.
    • If the data provider supports the filter criteria capability including the contains ($co or $regex) operator, JET Combobox will request the data provider to do filtering. Otherwise it will filter internally.
    • See also Improve page load performance
Default Value:
  • null
Names
Item Name
Property options
Property change event optionsChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-options-changed

(nullable) options-keys :(oj.ojCombobox.OptionsKeys|null)

Specify the key names to use in the options array.

Depending on options-keys means that the signature of the data does not match what is supported by the options attribute. When using Typescript, this would result in a compilation error.

Best practice is to use a oj.ListDataProviderView with data mapping as a replacement.

However, for the app that must fetch data from a REST endpoint where the data fields do not match those that are supported by the options attribute, you may use the options-keys with any dataProvider that implements DataProvider interface.

Note: child-keys and children properties in options-keys are ignored when using a oj.TreeDataProvider.

Default Value:
  • null
Names
Item Name
Property optionsKeys
Property change event optionsKeysChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-options-keys-changed

(nullable) options-keys.child-keys :oj.ojCombobox.OptionsKeys

The object for the child keys. It is ignored when using a oj.TreeDataProvider.
Properties:
Name Type Argument Description
childKeys oj.ojCombobox.OptionsKeys | null <optional>
<nullable>
 The object for the child keys.
children string <optional>
<nullable>
 The key name for the children.
label string <optional>
<nullable>
 The key name for the label.
value string <optional>
<nullable>
 The key name for the value.
Default Value:
  • null
Names
Item Name
Property optionsKeys.childKeys

(nullable) options-keys.children :string

The key name for the children. It is ignored when using a oj.TreeDataProvider.
Default Value:
  • null
Names
Item Name
Property optionsKeys.children

(nullable) options-keys.label :string

The key name for the label.
Default Value:
  • null
Names
Item Name
Property optionsKeys.label

(nullable) options-keys.value :string

The key name for the value.
Default Value:
  • null
Names
Item Name
Property optionsKeys.value

(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) picker-attributes is not applied in the native theme. 2) setting this attribute after element creation has no effect.

Properties:
Name Type Argument Description
class string <optional>
 The css class to append to the picker.
style string <optional>
 The css style to append to the picker.
Deprecated:
Since Description
7.0.0 Style property of pickerAttribute is deprecated as it violates the recommended Content Security Policy for JET which disallows inline styles. Use class property instead. As of 11.0.0 this property is ignored and an error is logged.
Default Value:
  • null
Names
Item Name
Property pickerAttributes
Property change event pickerAttributesChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-picker-attributes-changed

placeholder :string|null

The placeholder text to set on the element. The placeholder specifies a short hint that can be displayed before user selects or enters a value.
Default Value:
  • null
Names
Item Name
Property placeholder
Property change event placeholderChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-placeholder-changed

(readonly, nullable) raw-value :Array.<string>

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.

This is a read-only attribute so page authors cannot set or change it directly.

Consider a combobox with the following options: 


  <oj-option value="CH">Chrome</oj-option>
  <oj-option value="FF">Firefox</oj-option>
  <oj-option value="SA">Safari</oj-option>
  <oj-option value="OP">Opera</oj-option>

The rawValue updates on the 'input' javascript event, so the rawValue changes as the value of the input is changed. The rawValue is always an array when exists and the last element of the array represent the current text typed in the input text field. Consider the above example combobox. Now, if the user types in 'Edge' into the field, the rawValue will be ['E'], then ['Ed'], then ['Edg'], and finally ['Edge']. 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. In this case, without any converter the value will be updated to ['Edge'].

Then if the user continues to type in 'CH', the rawValue will be ['Edge', 'C'] and then ['Edge', 'CH']. The rawValue will contains the labels of all the selected values along with the text currently being typed in the text field. Now, when the user blurs or presses Enter and since the text now matches one of the keys(values) of the current set of options the value will be updated to ['Edge', 'CH'], while the rawValue gets updated to ['Edge', 'Chrome'] and the user now sees two pills 'Edge' and 'Chrome'.

Note that a rawValueChanged event will be triggered when setting the value and the event payload will contain the current rawValue as ['Edge', 'Chrome'] and previous rawValue as ['Edge', 'CH'].

Default Value:
  • null
Supports writeback:
  • true
Since:
  • 1.2.1
Names
Item Name
Property rawValue
Property change event rawValueChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-raw-value-changed

readonly :boolean

Dictates element's readonly state.

The default value for readonly is false. However, if the form component is a descendent of oj-form-layout, the default value for readonly could come from the oj-form-layout component's readonly attribute. The oj-form-layout uses the MetadataTypes.PropertyBinding provide property to provide its readonly attribute value to be consumed by descendent components. The form components are configured to consume the readonly property if an ancestor provides it and it is not explicitly set. For example, if the oj-form-layout's readonly attribute is set to true, and a descendent form component does not have its readonly attribute set, the form component's readonly will be true.

Default Value:
  • false
Names
Item Name
Property readonly
Property change event readonlyChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-readonly-changed

required :boolean

This property set to false implies that a value is not required to be provided by the user. This is the default. This property set 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. In the Alta theme the input's label will render a required icon.

The Required error text is based on Redwood UX designs, and it is not recommended that it be changed. To override the required error message, use the translations.required attribute. The component's label text is passed in as a token {label} and can be used in the message detail.

When required is set to true, an implicit required validator is created, i.e., new RequiredValidator(). The required validator is the only validator to run during initial render, and its error is not shown to the user at this time; this is called deferred validation. The required validator also runs during normal validation; this is when the errors are shown to the user. See the Validation and Messaging section for details.

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

Running Validation when required property changes

  • if component is valid when required is set to true, then it runs deferred validation on the value property. If the field is empty, the valid state is invalidHidden. No errors are shown to the user.
  • if component is invalid and has deferred messages when required is set to false, then component messages are cleared (messages-custom messages are not cleared) but no deferred validation is run because required is false.
  • if component is invalid and currently showing invalid messages when required is set, then component messages are cleared and normal validation is run using the current display value.
    • if there are validation errors, then value property is not updated and the error is shown.
    • if no errors result from the validation, the value property is updated; page author can listen to 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.

Default Value:
  • false
Since:
  • 0.7.0
See:
Names
Item Name
Property required
Property change event requiredChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-required-changed

translations :object|null

A collection of translated resources from the translation bundle, or null if this component has no resources. Resources may be accessed and overridden individually or collectively, as seen in the examples.

If the component does not contain any translatable resource, the default value of this attribute will be null. If not, an object containing all resources relevant to the component.

If this component has translations, their documentation immediately follows this doc entry.

Names
Item Name
Property translations
Property change event translationsChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-translations-changed

translations.filter-further :string

Text at the top of drop down when not all results are fetched and users need to filter further.

Default Value:
  • "More results available, please filter further."
Names
Item Name
Property translations.filterFurther

translations.more-matches-found :string

Text for the drop down when more than one options are found.

Default Value:
  • "num matches found"
Names
Item Name
Property translations.moreMatchesFound

translations.no-matches-found :string

No options found text for drop down.

Default Value:
  • "No matches found"
Names
Item Name
Property translations.noMatchesFound

translations.no-more-results :string

Text for the drop down when all options are selected

Default Value:
  • "No more results"
Names
Item Name
Property translations.noMoreResults

translations.one-matches-found :string

Text for the drop down when one option is found.

Default Value:
  • "One match found"
Names
Item Name
Property translations.oneMatchesFound

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

Message detail text can include formatted HTML text, whereas hints and message summary text cannot. If you use formatted text, it should be accessible and make sense to the user if formatting wasn't there. The allowed html tags are: span, b, i, em, br, hr, li, ol, ul, p, small, pre.

See the translations attribute for usage examples.

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

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

Message text for summarizing a required validation error.

See the translations attribute for usage examples.

Deprecated:
Since Description
14.0.0 This is deprecated because in the Redwood design system form components do not show validator summaries, so this is no longer needed.
Default Value:
  • ""
Since:
  • 14.0.0
See:
Names
Item Name
Property translations.required.messageSummary

user-assistance-density :('reflow'|'efficient'|'compact')

Note: This attribute is not supported in the following themes: Alta

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

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

The oj-form-layout component uses the MetadataTypes.PropertyBinding provide property to provide 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.

Supported Values:
Value Description
compact Messages, help, hints, and required will not be shown inline; they will show in a mode that keeps the screen more compact, like a popup for the messages, and a required icon to indicate Required.
efficient Messages, help, hints, and required are all shown inline under the field with reserved space.
reflow Messages, help, hints, and required are all shown inline under the field with no reserved space.
Default Value:
  • "reflow"
Since:
  • 9.0.0
Names
Item Name
Property userAssistanceDensity
Property change event userAssistanceDensityChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-user-assistance-density-changed

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

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

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

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

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, see Events and Listeners for additional information.) on-valid-changed

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

List of validators, synchronous or asynchronous, used by component along with asynchronous validators from the deprecated async-validators option and the implicit component validators when performing validation. Each item is either an instance that duck types oj.Validator or oj.AsyncValidator. As of v8.0.0, defining a validator with an object literal with validator type and its options (aka json format) has been deprecated and does nothing. If needed, you can make the json format work again by importing the deprecated module you need, e.g., ojvalidation-base module.

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. At runtime when the component runs validation, it combines all the implicit validators with all the validators specified through this validators attribute and the async-validators attribute, and runs all of them.

Hints exposed by validators are shown inline by default in the Redwood theme when the field has focus. In the Alta theme, validator hints are shown in a notewindow on focus, or as determined by the 'validatorHint' property set on the display-options attribute. In either theme, you can turn off showing validator hints by using the 'validatorHint' property set to 'none' on the display-options attribute.

In the Redwood theme, only one hint shows at a time, so the precedence rules are: help.instruction shows; if no help.instruction then validator hints show; if none, then help-hints.definition shows; if none, then converter hint shows. help-hints.source always shows along with the other help or hint.

When validators property changes due to programmatic intervention, the 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 - messages-shown property is non-empty, when validators or async-validators
  • 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 value property 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.
    • messages-custom property is not cleared.

    Deprecated:
    Since Value Description
    8.0.0 oj.Validation.RegisteredValidator Defining a validator with an object literal with validator type and its options (aka JSON format) has been deprecated and does nothing. If needed, you can make the JSON format work again by importing the deprecated ojvalidation module you need, like ojvalidation-base.
    Default Value:
    • []
    Names
    Item Name
    Property validators
    Property change event validatorsChanged
    Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-validators-changed

    value :Array<V>|null

    The value of the element. The value is an array with any type of items.

    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.

    Default Value:
    • null
    Supports writeback:
    • true
    Names
    Item Name
    Property value
    Property change event valueChanged
    Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-value-changed

    value-options :Array<{value: V, label?: string}> | null

    The valueOptions is similar to the value, but is an array of Objects and each Object contains both a value and display label. The value and valueOptions are kept in sync. If initially both are set, the selected values in the value attribute has precedence.

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

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

    If valueOptions is not specified or one of the selected values is missing, then the labels will be fetched from the data provider.

    Properties:
    Name Type Argument Description
    label string <optional>
    		 display label of value above. If missing, String(value) is used.
    value any the current value of JET Combobox
    Default Value:
    • null
    Supports writeback:
    • true
    Names
    Item Name
    Property valueOptions
    Property change event valueOptionsChanged
    Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-value-options-changed

    Events

    ojAnimateEnd

    Triggered when a default animation has ended.
    Deprecated:
    Since Description
    12.1.0 This web component no longer supports this event.
    Properties:

    All of the event payloads listed below can be found under event.detail. See Events and Listeners for additional information.

    Name Type Description
    action string The action that triggered the animation.

    Supported values are:
    • "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:
    • 12.1.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 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;
    Deprecated:
    Since Description
    12.1.0 This web component no longer supports this event.
    Properties:

    All of the event payloads listed below can be found under event.detail. See Events and Listeners for additional information.

    Name Type Description
    action string The action that triggers the animation.

    Supported values are:
    • "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
    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:
    • 12.1.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');

    refresh : {void}

    Refreshes the combobox.

    This method does not accept any arguments.

    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");

    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

    validate : {Promise}

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