Element: <oj-input-search>

Oracle® JavaScript Extension Toolkit (JET)
9.1.0
F30737-01

Signature:

class ojInputSearch<K, D>

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

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:
  • 9.1.0
Since:
  • 9.0.0
Module:
  • ojinputsearch

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 {InputSearchElement} from "ojs/ojinputsearch";

//For the transpiled javascript to load the element's module, import as below
import "ojs/ojinputsearch";
Generic Parameters
ParameterDescription
KType of 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 Input Search

Description: JET Input Search provides support for entering search text.

JET Input Search displays an input field that a user can type into, as well as an optional dropdown list of suggestions.

An Input Search that shows only an input field can be created with the following markup.


<oj-input-search aria-label='Search'>
</oj-input-search>

An Input Search that shows an input field with a dropdown list of suggestions can be created with the following markup.


<oj-input-search suggestions='[[dataProvider]]'
                 aria-label='Search'>
</oj-input-search>

Input Search will only show a limited number of suggestions in the dropdown list. The list could show most recently used searches or high confidence suggested results. It is intended to help the user enter search text in order to conduct a subsequent search. It is up to the application to conduct the search and display results elsewhere on the page.

An application should register a listener for the ojValueAction event in order to be notified when the user submits search text. The application should then conduct the search and display the results.


<oj-input-search on-oj-value-action='[[handleValueAction]]'
                 aria-label='Search'>
</oj-input-search>

If an application provides a separate search button, then it may choose to ignore ojValueAction events and instead bind to the value. When the search button is clicked, the application would conduct a search with the currently set value.


<oj-input-search value='{{searchText}}'
                 aria-label='Search'>
</oj-input-search>
<oj-button on-oj-action='[[conductSearch]]'>
  Search
</oj-button>

The value property is guaranteed to be up-to-date at the time the ojValueAction event is dispatched.

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.

Keyboard End User Information

Target Key Action
Input field Enter Set the input text as the value.
Input field UpArrow or DownArrow If the drop down is not open, expand the drop down list.
Input field Esc Collapse the drop down list. If the drop down is already closed, do nothing.
Input field Tab In Set focus to the Input Search.

Accessibility

It is up to the application developer to set an aria-label on the Input Search.

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.

suggestionItemTemplate

The suggestionItemTemplate slot is used to specify the template for rendering each suggestion in the dropdown list. The slot must be a <template> element.

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

  • $current - an object that contains information for the current suggestion. (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 suggestionItemTemplate is specified, the component will render based on the value of the suggestionItemText property.

Properties of $current:
Name Type Description
data D The data for the current suggestion
index number The zero-based index of the current suggestion
key K The key of the current suggestion
metadata oj.ItemMetadata<K> The metadata for the current suggestion
searchText string The search text entered by the user
Since:
  • 9.1.0

Attributes

placeholder :string

The placeholder text to set on the element. The placeholder specifies a short hint that can be displayed before the 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) raw-value :null|string

The rawValue is the read-only property for retrieving the current value from the input field in string form.

The rawValue updates on the 'input' javascript event, so the rawValue changes as the value of the input is changed. If the user types in '1,200' into the field, the rawValue will be '1', then '1,', then '1,2', ..., and finally '1,200'. Then when the user blurs or presses Enter the value property gets updated.

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

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

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

Specifies the text string to render for a suggestion. 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 suggestion in the dropdown if no suggestionItemTemplate is provided. When rendered for the dropdown suggestions, default matching search term highlighting will still be applied.

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

suggestions :null | oj.DataProvider<K, D>

The suggestions data for the InputSearch.

Note that the suggestion-item-text attribute allows for customizing the rendering of each suggestion. If it is not specified, then the component will attempt to render as text the 'label' field in the suggestion by default.

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

value :null|string

The value of the element.
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

Events

ojValueAction

Triggered when search text is submitted by the user, even if the text hasn't changed. Submission is triggered by the enter key, either to directly submit text or to select a highlighted value from the suggestions dropdown, or by selecting a value from the dropdown using a mouse or touch gesture. Note that the value property is guaranteed to be up-to-date at the time the ojValueAction event is dispatched.
Properties:

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

Name Type Description
value null | string The search text.
itemContext null | CommonTypes.ItemContext.<K, D> The data provider context for the search text, if available.

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

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

Type Definitions

SuggestionItemTemplateContext<K, D>

Properties:
Name Type Description
data D The data for the current suggestion
index number The zero-based index of the current suggestion
key K The key of the current suggestion
metadata oj.ItemMetadata<K> The metadata for the current suggestion
searchText string The search text entered by the user