Element: <oj-select-single>

Oracle® JavaScript Extension Toolkit (JET)
8.0.0
F18189-01

Signature:

class ojSelectSingle<V, D>

QuickNav

Slots

Attributes

Events

Methods

Type Definitions

JET Custom Elements

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

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

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



Version:
  • 8.0.0
Since:
  • 8.0.0
Module:
  • ojselectsingle

Module usage

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

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

//For the transpiled javascript to load the element's module, import as below
import "ojs/ojselectsingle";
Generic Parameters
ParameterDescription
VType of value of the component/key of the dataprovider
DType of data from the dataprovider

JET In Typescript

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


JET Select Single

Description: JET Select Single provides support for single-select and search filtering.

A JET Select Single can be created with the following markup.


<oj-select-single data="[[dataProvider]]">
</oj-select-single>

Validation and Messaging

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

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

Normal Validation

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

Deferred Validation

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

Mixed Validation

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

Showing Deferred Messages

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

Validators Participating in Deferred Validation

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

Touch End User Information

Target Gesture Action
Input 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.
Arrow Button Tap If the drop down is not open, expand the drop down list. Otherwise, close the drop down list.
Option Item Tap Tap on an option item in the drop down list to select.

Keyboard End User Information

Target Key Action
Option item Enter Select the highlighted choice from the drop down.
Input field Enter Set the input text as the value.
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.
Drop down Esc Collapse the drop down list. If the drop down is already closed, do nothing.
Select Tab In Set focus to the Select. If hints, title or messages exist in a notewindow, pop up the notewindow.

Performance

Page Load

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

The dropdown data isn't fetched until the user opens the dropdown.

Styling

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

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

Class Description
oj-form-control-text-align-right Aligns the text to the right regardless of the reading direction. This is normally used for right aligning numbers
oj-form-control-text-align-start Aligns the text to the left in ltr and to the right in rtl
oj-form-control-text-align-end Aligns the text to the right in ltr and to the left in rtl
oj-select-results Apply to the collection element (e.g. <oj-list-view>) in the collectionTemplate

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

It is up to the application developer to associate an oj-label to the Select element. You should put an id on the Select element, and then set the for attribute on the oj-label to be the Select element's id.

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

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

Slots

JET components that allow child content support slots. Please see the slots section of the JET component overview doc for more information on allowed slot content and slot types.

collectionTemplate

The collectionTemplate slot is used to specify the template for rendering the items in the dropdown. The slot must be a <template> element containing a child collection element (e.g. <oj-table>) supporting single selection. The data, selected, and selectedItem properties should be set on the appropriate collection component attributes, e.g. data, selected, and first-selected-item for oj-list-view and data, selected.row, and first-selected-row for oj-table. Note as well that the selectedItem must be bound using a writeback expression (i.e. {{$current.selectedItem}}) so that it can be updated when the user selects a new value. The oj-select-results class must also be applied to the collection element in the template.

When the template is executed, it will have access to the binding context containing the following properties:

  • $current - an object that contains information for the collection. (See the table below for a list of properties available on $current)
  • alias - if the data-oj-as attribute was specified on the template, the value will be used to provide an application-named alias for $current.

If no collectionTemplate is specified, the component will check whether an itemTemplate is specified. Otherwise, the component will render based on the value of the itemText property.

Properties of $current:
Name Type Description
data oj.DataProvider.<V, D> The data for the collection.
selected KeySet.<V> The selected item key.
selectedItem CommonTypes.ItemContext.<V, D> The selected item context.
searchText string Search text.

itemTemplate

The itemTemplate slot is used to specify the template for rendering each item in the dropdown list when an external collectionTemplate is not provided. The slot must be a <template> element.

When the template is executed for each item, it will have access to the binding context containing the following properties:

  • $current - an object that contains information for the current item. (See the table below for a list of properties available on $current)
  • alias - if the data-oj-as attribute was specified on the template, the value will be used to provide an application-named alias for $current.

If no itemTemplate or collectionTemplate is specified, the component will render based on the value of the itemText property.

Note that the properties depth, leaf, parentKey, are only available when the supplied dataProvider is a oj.TreeDataProvider.

Properties of $current:
Name Type Description
componentElement Element The Select custom element
data D The data for the current item being rendered
index number The zero-based index of the current item
key V The key of the current item being rendered
searchText string The search text entered by the user
depth number (TreeDataProvider only) The depth of the current item (available when hierarchical data is provided) being rendered. The depth of the first level children under the invisible root is 1.
leaf boolean (TreeDataProvider only) True if the current item is a leaf node (available when hierarchical data is provided).
parentKey V (TreeDataProvider only) The key of the parent item (available when hierarchical data is provided). The parent key is null for root nodes.

Attributes

data :oj.DataProvider.<V, D>

The data for the Select.

Note that the item-text attribute and the itemTemplate and collectionTemplate slots allow for customizing the rendering of each data item. If those are not specified, then the component will attempt to render as text the 'label' field in the data item by default.

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

(nullable) described-by :string

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

disabled :boolean

Whether the component is disabled. The default is false.

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

  • when a required component is initialized as disabled value="{{currentValue}}" required disabled, deferred validation is skipped.
  • when a disabled component is enabled,
    • if component is invalid and showing messages then all component messages are cleared, and full validation run using the display value.
      • if there are validation errors, they are shown.
      • if no errors result from the validation, the value property is updated. Page authors can listen to 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 where it should be displayed in relation to the component.

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 'help.instruction' property goes from 'notewindow' to 'none' then it no longer shows in the notewindow.

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

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

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

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.
Default Value:
  • ['notewindow']
Since:
  • 0.7
Names
Item Name
Property displayOptions.helpInstruction

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

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

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

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

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

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

How is help.instruction better than the html 'title' attribute? The html 'title' attribute only shows up as a tooltip on mouse over, not on keyboard and not in a mobile device. So the html 'title' would only be for text that is not important enough to show all users, or for text that you show the users in another way as well, like in the label. Also you cannot theme the native browser's title window like you can the JET notewindow, so low vision users may have a hard time seeing the 'title' window. For these reasons, the JET EditableValue components do not use the HTML's 'title' attribute and instead use the help.instruction attribute.

To include formatted text in the help.instruction, format the string using html tags. For example the help.instruction might look like: 

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

help-hints :Object

Represents hints to render help information on the label of the editable component. This is used when an oj-form-layout creates labels for its editable value component children. Also when an editable value component (inside or outside oj-form-layout) creates a label for itself (if you set labelEdge), these hints will be used to render the help information. However, please note that, help information will not be rendered if the label is created inside the input field (labelEdge ='inside').

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

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

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

(nullable) help-hints.definition :string

Hint for help definition text associated with the label.

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

See the help-hints attribute for usage examples.

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

(nullable) help-hints.source :string

Hint for help source URL associated with the label.

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

See the help-hints attribute for usage examples.

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

item-text :keyof D | ((itemContext: CommonTypes.ItemContext<V, D>) => string)

Specifies the text string to render for a data item. This attribute can be set to either:
  • a string that specifies the name of a top level data field to render as text, or
  • a callback function that takes a context object and returns the text string to display

By default, the component will attempt to render a 'label' data field as text.

This text will be rendered for the selected value of the component. It will also be rendered for each data item in the dropdown if no itemTemplate or collectionTemplate is provided. When rendered for the dropdown items, default matching search term highlighting will still be applied.

Default Value:
  • 'label'
Names
Item Name
Property itemText
Property change event itemTextChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-item-text-changed

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

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

The default value varies by theme, and it works well for the theme in most cases. If the component is in an oj-form-layout, and the label-edge attribute on oj-form-layout is set to an explicit value, the label-edge attribute on all form controls should also be set to an explict value. For example, if the label-edge attribute on oj-form-layout is set to "start" or "top", the label-edge attribute of all form controls should be set to "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.

The help-hints attribute will be ignored. No help related information will be rendered on the label.
"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
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

messages-custom :Array.<oj.Message>

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

Each message in the array is an object that duck types oj.Message. See oj.Message for details.

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

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

placeholder :string

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:
  • ''
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 :boolean

Dictates element's readonly state.
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

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

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

Running Validation

  • if element is valid when required is set to true, then it runs deferred validation on the value. This is to ensure errors are not flagged unnecessarily.
  • if element is invalid and has deferred messages when required is set to false, then element messages are cleared but no deferred validation is run.
  • if element is invalid and currently showing invalid messages when required is set, then element 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 value property to clear custom errors.

Clearing Messages

  • Only messages created by the element are cleared.
  • messages-custom attribute is not cleared.

This property set to false implies that a value is not required to be provided by the user. This is the default. This property set to true implies that a value is required to be provided by user and the input's label will render a required icon. A required validator - oj.RequiredValidator - is implicitly used.
Default Value:
  • false
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.cancel :string

Label of the cancel button of the mobile dropdown.

Default Value:
  • "Cancel"
Names
Item Name
Property translations.cancel

translations.label-acc-open-dropdown :string

Label of the dropdown arrow for screen readers.

Default Value:
  • "expand"
Names
Item Name
Property translations.labelAccOpenDropdown

translations.multiple-matches-found :string

Screen reader text for the drop down when multiple results are found.

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

translations.n-or-more-matches-found :string

Screen reader text for the drop down when N or more results are found.

Default Value:
  • "num or more matches found"
Names
Item Name
Property translations.nOrMoreMatchesFound

translations.no-matches-found :string

Screen reader text for the drop down when no results are found.

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

translations.no-results-line1 :string

First line of text in the no data template shown in the default listView.

Default Value:
  • "No results found"
Names
Item Name
Property translations.noResultsLine1

translations.no-results-line2 :string

Second line of text in the no data template shown in the default listView.

Default Value:
  • "We can\'t find anything matching your search."
Names
Item Name
Property translations.noResultsLine2

translations.one-match-found :string

Screen reader text for the drop down when one result is found.

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

(nullable) translations.required :Object

Provides properties to customize the summary, detail and hint text used by the implicit required validator associated to any editable component that supports the required option.

See the translations attribute and required option for usage examples.

Since:
  • 0.7
Names
Item Name
Property translations.required

(nullable) translations.required.hint :string

Hint text used by required validation error.

See the translations attribute for usage examples.

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

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

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

See the translations attribute for usage examples.

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

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

Message text for summarizing a required validation error.

See the translations attribute for usage examples.

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

(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

value :(V|null)

The value of the element. The type must be the same as the type of keys in the data provider.
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-item :CommonTypes.ItemContext.<V, D>

The valueItem is similar to the value, but is a CommonTypes.ItemContext<V, D> object which contains both a key and data, and optional metadata. The key will be set as the value of the element. The value and valueItem are kept in sync, both during programmatic property sets as well as during interactive user selection. If initially both are set, the selected value in the value attribute has precedence.

Note: If there is an initial selection, setting it via the valueItem attribute initially can improve page load performance because the element will not have to fetch the selected data from the data provider.

If valueItem is not specified or the selected value is missing, then the selected data will be fetched from the data provider.

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

virtual-keyboard :"email"|"number"|"search"|"tel"|"text"|"url"

The type of virtual keyboard to display for entering value on mobile browsers. This attribute has no effect on desktop browsers.
Supported Values:
Value Description
"email" Use a virtual keyboard for entering email.
"number" Use a virtual keyboard for entering number.

Note that on Android and Windows Mobile, the "number" keyboard does not contain the minus sign. This value should not be used on fields that accept negative values.
"search" Use a virtual keyboard for entering search terms.
"tel" Use a virtual keyboard for entering telephone number.
"text" Use a virtual keyboard for entering text.
"url" Use a virtual keyboard for entering URL.
Default Value:
  • "search"
Names
Item Name
Property virtualKeyboard
Property change event virtualKeyboardChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-virtual-keyboard-changed

Events

ojAnimateEnd

Triggered when a default animation has ended.
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-open" - when an inline message container opens or increases in size
  • "inline-close" - when an inline message container closes or decreases in size
  • "notewindow-open" - when a note window opens
  • "notewindow-close" - when a note window closes
element Element The element being animated.
Since:
  • 4.0.0

ojAnimateStart

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

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

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

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

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

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

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

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

Methods

getProperty(property) : {any}

Retrieves the value of a property or a subproperty. The return type will be the same as the type of the property as specified in this API document. If the method is invoked with an incorrect property/subproperty name, it returns undefined.
Parameters:
Name Type Description
property string The property name to get. Supports dot notation for subproperty access.
Since:
  • 4.0.0
Returns:
Type
any
Example

Get a single subproperty of a complex property:

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

refresh() : {void}

Refreshes the Select.

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. The implicit required validator is run if the component is marked required.
  3. 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 the component passed all validations. The Promise resolves to "invalid" if there were validation errors.
Type
Promise

Type Definitions

CollectionTemplateContext<V, D>

Properties:
Name Type Description
data oj.DataProvider.<V, D> The data for the collection.
selected KeySet.<V> The selected item key.
selectedItem CommonTypes.ItemContext.<V, D> The selected item context.
searchText string Search text.

ItemTemplateContext<V, D>

Properties:
Name Type Description
componentElement Element The Select custom element
data D The data for the current item being rendered
index number The zero-based index of the current item
key V The key of the current item being rendered
searchText string The search text entered by the user
depth number (TreeDataProvider only) The depth of the current item (available when hierarchical data is provided) being rendered. The depth of the first level children under the invisible root is 1.
leaf boolean (TreeDataProvider only) True if the current item is a leaf node (available when hierarchical data is provided).
parentKey V (TreeDataProvider only) The key of the parent item (available when hierarchical data is provided). The parent key is null for root nodes.