Usage
Signature:
interface SelectSingleElement<V, D>
Generic Parameters
Parameter Description V Type of value of the component/key of the dataprovider D Type of data from the dataprovider
Typescript Import Format
//To typecheck the element APIs, import as below.
import { SelectSingleElement } from "ojs/ojselectsingle";
//For the transpiled javascript to load the element's module, import as below
import "ojs/ojselectsingle";
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-select-results
-
Apply this class to the collection element (e.g. an <oj-list-view>) in the collectionTemplate.
-
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-select-single class="oj-form-control-max-width-md"> </oj-select-single>
-
-
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-select-single class="oj-form-control-width-md"> </oj-select-single>
-
-
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-select-single class="oj-form-control-text-align-right"> </oj-select-single>
-
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. Thedata
,selected
, andselectedItem
properties should be set on the appropriate collection component attributes, e.g.data
,selected
, andfirst-selected-item
foroj-list-view
anddata
,selected.row
, andfirst-selected-row
foroj-table
. Note as well that theselectedItem
must be bound using a writeback expression (i.e.{{$current.selectedItem}}
) so that it can be updated when the user selects a new value. Theoj-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 anitemTemplate
is specified. Otherwise, the component will render based on the value of theitemText
property.- Deprecated:
-
Since Description 9.0.0
The selectedItem property is deprecated in favor of currentRow and handleRowAction properties, which provide additional functionalities.
Properties of $current:
Name Type Description currentRow
Object The
using a writable expression.currentRow
property is used to set the focus to current active row in theoj-table
. This is also used to get the key for the current row when navigating through the options in the dropdown. Since, this property is used to listen to the changes made by theoj-table
, it should be bound to thecurrent-row
attribute of theoj-table
Example:
<oj-table ... current-row="{{$current.currentRow}}" ...>
Properties
Name Type Description rowKey
V When using
using a writable expression.oj-list-view
, this sub-property of thecurrentRow
property should be used instead. This should be bound to thecurrent-item
attribute of theoj-list-view
Example:
<oj-list-view ... current-item="{{$current.currentRow.rowKey}}" ...>
data
DataProvider.<V, D> The data for the collection. handleRowAction
((event: Event, context: ojcommontypes.ItemContext<V, D>) => void) The
handleRowAction
property is used to make selection foroj-select-single
whenojItemAction
is triggered in theoj-list-view
(ojRowAction
ifoj-table
is used).This should be bound to the
on-oj-item-action
attribute ofoj-list-view
if it is used for the collectionTemplate.When using
oj-table
as the collectionTemplate this should be bound to theon-oj-row-action
attribute of theoj-table
instead.searchText
string Search text. selected
KeySet.<V> The
selected
property is used to push the current selected option to the collection. This is also used to highlight the option when navigating through the dropdown.This should be bound to the
selected
attribute ofoj-list-view
if it is used for the collectionTemplate.When using
oj-table
as the collectionTemplate this should be bound to theselected.row
attribute of theoj-table
instead.selectedItem
ojcommontypes.ItemContext.<V, D> The selected item context. -
itemTemplate
-
The
itemTemplate
slot is used to specify the template for rendering each item in the dropdown list when an externalcollectionTemplate
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
orcollectionTemplate
is specified, the component will render based on the value of theitemText
property.Note that the properties
depth, leaf, parentKey
, are only available when the supplied dataProvider is a TreeDataProvider.Properties of $current:
Name Type Description componentElement
Element The Select custom element data
D The data for the current item being rendered 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. index
number The zero-based index of the current item key
V The key of the current item being rendered leaf
boolean (TreeDataProvider only) True if the current item is a leaf node (available when hierarchical data is provided). metadata
oj.ItemMetadata<V> The metadata for the current item being rendered parentKey
V (TreeDataProvider only) The key of the parent item (available when hierarchical data is provided). The parent key is null for root nodes. searchText
string The search text entered by the user
Attributes
-
data :DataProvider.<V, D>
-
The data for the Select.
Note that the
item-text
attribute and theitemTemplate
andcollectionTemplate
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.- See also Improve page load performance
- 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 thevalueChanged
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.
- if component is invalid and showing messages then all component messages are cleared,
and full validation run using the display value.
- 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
- when a required component is initialized as disabled
-
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'.
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 message, set the display-options.messages 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.help-instruction :Array<'notewindow'|'none'>|'notewindow'|'none'
-
Display options for auxiliary help instruction text that determines whether or not it should be displayed.
- 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 suppoorted 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.
- 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
-
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.
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:
If you use formatted text, it should be accessible and make sense to the user if formatting wasn't there.<oj-some-element help.instruction="<html>Enter <b>at least</b> 6 characters</html>"></oj-some-element>
- 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.
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.
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: ojcommontypes.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, 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.ProvidePropertytransform
property to transform itslabel-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".- Since:
- 8.0.0
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.
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
-
match-by :Array<TextFilter<D>['matchBy']>|null
-
The list of text filter matching behaviors to use when fetching data filtered by a user's typed search text, in order of descending priority with the preferred behavior first. If the preferred behavior is not supported by the DataProvider, then the component will check the next behavior, and so on, until it finds one that is supported. If none of the specified behaviors are supported or if this property is not specified, then the behavior will effectively be "unknown".
- Default Value:
null
- Since:
- 16.0.2
Names
Item Name Property matchBy
Property change event matchByChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-match-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 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
-
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.
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 theoj-form-layout
component's readonly attribute. Theoj-form-layout
uses the MetadataTypes.PropertyBindingprovide
property to provide itsreadonly
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 totrue
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 thevalueChanged
event on the component to clear custom errors.
- if there are validation errors, then
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
- 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-clear-value :string
-
Label of the clear value icon for screen readers.
- Default Value:
"clear value"
Names
Item Name Property translations.labelAccClearValue
-
translations.label-acc-open-dropdown :string
-
Label of the dropdown arrow for screen readers.
- Deprecated:
-
Since Description 10.0.0
This option has been deprecated because the dropdown arrow should be ignored by 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.
- Deprecated:
-
Since Description 9.0.0
This option has been deprecated since oj-select-single will no longer show the dropdown when there are no results to show.
- 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.
- Deprecated:
-
Since Description 9.0.0
This option has been deprecated since oj-select-single will no longer show the dropdown when there are no results to show.
- 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.
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:
"Select a 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 itsuser-assistance-density
attribute value to be consumed by descendent components. The form components are configured to consume theuser-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.- Default Value:
"reflow"
- Since:
- 9.0.0
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. 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.
- Supports writeback:
true
- Since:
- 4.2.0
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 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 :ojcommontypes.ItemContext.<V, D>
-
The
valueItem
is similar to thevalue
, but is a ItemContext<V, D> object which contains both a key and data, and optional metadata. The key will be set as thevalue
of the element. Thevalue
andvalueItem
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 thevalue
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 a value on mobile browsers. This attribute has no effect on desktop browsers.
- Default Value:
"search"
Supported Values:
Value Description email
Use a virtual keyboard for entering email addresses. number
Use a virtual keyboard for entering numbers. 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 numbers. text
Use a virtual keyboard for entering text. url
Use a virtual keyboard for URL entry. 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.
- Deprecated:
-
Since Description 12.1.0
This web component no longer supports this event.
- "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
- Since:
- 12.1.0
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: element
Element The element being animated. -
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 toevent.detail.endCallback
.event.detail.endCallback
should be called immediately afterevent.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 callevent.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;
- Deprecated:
-
Since Description 12.1.0
This web component no longer supports this event.
- "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
- Since:
- 12.1.0
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: 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. -
ojValueAction
-
Triggered when a value is submitted by the user, even if the value is the same as the previous value. Submission is triggered by selecting a value from the dropdown using the keyboard, mouse, or a touch gesture. Note that the value property is guaranteed to be up-to-date at the time the ojValueAction event is dispatched.
- Since:
- 10.0.0
Properties:
All of the event payloads listed below can be found under
event.detail
. See Events and Listeners for additional information.Name Type Description itemContext
ojcommontypes.ItemContext.<V, D> The data provider context for the value. previousValue
V | null The previous selected value. value
V | null The selected value.
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
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
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
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}
-
- All messages are cleared, including custom messages added by the app.
- The implicit required validator is run if the component is marked required.
- At the end of validation if there are errors, the messages are shown.
If there were no errors, then the
value
option is updated.
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>
-
- Deprecated:
-
Since Description 9.0.0
The selectedItem property is deprecated in favor of currentRow and handleRowAction properties, which provide additional functionalities.
Properties:
Name Type Description currentRow
Object The
using a writable expression.currentRow
property is used to set the focus to current active row in theoj-table
. This is also used to get the key for the current row when navigating through the options in the dropdown. Since, this property is used to listen to the changes made by theoj-table
, it should be bound to thecurrent-row
attribute of theoj-table
Example:
<oj-table ... current-row="{{$current.currentRow}}" ...>
Properties
Name Type Description rowKey
V When using
using a writable expression.oj-list-view
, this sub-property of thecurrentRow
property should be used instead. This should be bound to thecurrent-item
attribute of theoj-list-view
Example:
<oj-list-view ... current-item="{{$current.currentRow.rowKey}}" ...>
data
DataProvider.<V, D> The data for the collection. handleRowAction
((event: Event, context: ojcommontypes.ItemContext<V, D>) => void) The
handleRowAction
property is used to make selection foroj-select-single
whenojItemAction
is triggered in theoj-list-view
(ojRowAction
ifoj-table
is used).This should be bound to the
on-oj-item-action
attribute ofoj-list-view
if it is used for the collectionTemplate.When using
oj-table
as the collectionTemplate this should be bound to theon-oj-row-action
attribute of theoj-table
instead.searchText
string Search text. selected
KeySet.<V> The
selected
property is used to push the current selected option to the collection. This is also used to highlight the option when navigating through the dropdown.This should be bound to the
selected
attribute ofoj-list-view
if it is used for the collectionTemplate.When using
oj-table
as the collectionTemplate this should be bound to theselected.row
attribute of theoj-table
instead.selectedItem
ojcommontypes.ItemContext.<V, D> The selected item context. -
ItemTemplateContext<V, D>
-
Properties:
Name Type Description componentElement
Element The Select custom element data
D The data for the current item being rendered 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. index
number The zero-based index of the current item key
V The key of the current item being rendered leaf
boolean (TreeDataProvider only) True if the current item is a leaf node (available when hierarchical data is provided). metadata
oj.ItemMetadata<V> The metadata for the current item being rendered parentKey
V (TreeDataProvider only) The key of the parent item (available when hierarchical data is provided). The parent key is null for root nodes. searchText
string The search text entered by the user