Element: <oj-input-search>

Oracle® JavaScript Extension Toolkit (JET)
16.1.0
F92237-01

Since:
  • 9.0.0
Module:
  • ojinputsearch

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

QuickNav

Slots

Attributes

Events

Methods

Type Definitions

Other Topics


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 up to a maximum of 12 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.

Note: Input Search is not a full-fledged form control and does not support some of the common features of form controls. For example, it is not expected to be used in an oj-form-layout, it does not support a label, and it does not support assistive text.

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.


Usage

Signature:

interface InputSearchElement<K,D>

Generic Parameters
ParameterDescription
KType of key of the dataprovider
DType of data from the dataprovider
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";

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-input-search-hero
Render a larger search field that is more prominent on the page
Example
<oj-input-search class="oj-input-search-hero">
 <!-- Content -->
 </oj-input-search>

Category: form-control-max-width

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
Sets the max width for a small field.
.oj-form-control-max-width-md
Sets the max width for a medium field.

Category: form-control-width

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
Sets the width for a small field.
.oj-form-control-width-md
Sets the width for a medium field.

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 Argument 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 ItemMetadata.<K> The metadata for the current suggestion
searchText string | null <optional>
 The search text entered by the user

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 :string|null

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:ojcommontypes.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 :(DataProvider.<K, D>|null)

Data for the InputSearch suggestions. This data is used to populate the list of suggestions in the dropdown. When a user selects a suggestion from the dropdown, the ojValueAction event will contain the data for that suggestion. If no suggestions data is provided, then the dropdown will not be shown. Note that the InputSearch only shows up to a maximum of 12 suggestions in the dropdown even if there are more suggestions available in the data.

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 :string|null

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

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 Argument Description
itemContext ojcommontypes.ItemContext.<K, D> <optional>
 The data provider context for the search text, if available.
previousValue string <optional>
 The previous search text.
value string <optional>
 The search text.

Methods

getProperty(property) : {any}

Retrieves a value for a property or a single subproperty for complex properties.
Parameters:
Name Type Description
property string The property name to get. Supports dot notation for subproperty access.
Returns:
Type
any

setProperties(properties) : {void}

Performs a batch set of properties.
Parameters:
Name Type Description
properties Object An object containing the property and value pairs to set.
Returns:
Type
void

setProperty(property, value) : {void}

Sets a property or a single subproperty for complex properties and notifies the component of the change, triggering a [property]Changed event.
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.
Returns:
Type
void

Type Definitions

SuggestionItemTemplateContext<K,D>

Properties:
Name Type Argument 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 ItemMetadata.<K> The metadata for the current suggestion
searchText string | null <optional>
 The search text entered by the user