class sap.m.InputBase

Control sample: sap.m.InputBase
Visiblity: public
UX Guidelines:
Implements: sap.ui.core.IFormContent
Available since: N/A
Module: sap/m/InputBase
Application Component: CA-UI5-CTR

The sap.m.InputBase control provides a basic functionality for input controls.


Constructor

Constructor for a new sap.m.InputBase.

Accepts an object literal mSettings that defines initial property values, aggregated and associated objects as well as event handlers. See sap.ui.base.ManagedObject#constructor for a general description of the syntax of the settings object.

new sap.m.InputBase(sId?, mSettings?)
Param Type Default Value Description
sId? string

ID for the new control, generated automatically if no ID is given

mSettings? object

Initial settings for the new control


Properties

Name Type Default Value Description
editable boolean true

Defines whether the control can be modified by the user or not. Note: A user can tab to non-editable control, highlight it, and copy the text from it.

Since: 1.12.0.

Visibility: public
enabled boolean true

Indicates whether the user can interact with the control or not. Note: Disabled controls cannot be focused and they are out of the tab-chain.

Visibility: public
name string

The name to be used in the HTML code (for example, for HTML forms that send data to the server via submission).

Visibility: public
placeholder string

Defines a short hint intended to aid the user with data entry when the control has no value.

Visibility: public
required boolean false

Indicates that user input is required. This property is only needed for accessibility purposes when a single relationship between the field and a label (see aggregation labelFor of sap.m.Label) cannot be established (e.g. one label should label multiple fields).

Since: 1.38.4.

Visibility: public
showValueStateMessage boolean true

Indicates whether the value state message should be shown or not.

Since: 1.26.0.

Visibility: public
textAlign sap.ui.core.TextAlign Initial

Defines the horizontal alignment of the text that is shown inside the input field.

Since: 1.26.0.

Visibility: public
textDirection sap.ui.core.TextDirection Inherit

Defines the text directionality of the input field, e.g. RTL, LTR

Since: 1.28.0.

Visibility: public
value string

Defines the value of the control.

Visibility: public
valueState sap.ui.core.ValueState None

Visualizes the validation state of the control, e.g. Error, Warning, Success.

Visibility: public
valueStateText string

Defines the text that appears in the value state message pop-up. If this is not specified, a default text is shown from the resource bundle.

Since: 1.26.0.

Visibility: public
width sap.ui.core.CSSSize

Defines the width of the control.

Note: If the provided width is too small, the control gets stretched to its min width, which is needed in order for the control to be usable and well aligned.

Visibility: public

Aggregations

Default Aggregation:

Name Cardinality Type Description
_beginIcon 0..n sap.ui.core.Icon

Icons that will be placed before the input field

Since: 1.58.

_endIcon 0..n sap.ui.core.Icon

Icons that will be placed after the input field

Since: 1.58.

_invisibleFormattedValueStateText 0..1 sap.m.FormattedText

Clone of the formattedValueStateText aggregation created for the accessibility elements used by screen readers.

Since: 1.84.

formattedValueStateText 0..1 sap.m.FormattedText

Defines the formatted text that appears in the value state message pop-up. It can include links. If both valueStateText and formattedValueStateText are set - the latter is shown.

Since: 1.78.


Associations

Name Cardinality Type Description
ariaDescribedBy 0..n sap.ui.core.Control

Association to controls / IDs that describe this control (see WAI-ARIA attribute aria-describedby).

Since: 1.90.

ariaLabelledBy 0..n sap.ui.core.Control

Association to controls / IDs that label this control (see WAI-ARIA attribute aria-labelledby).

Since: 1.27.0.


Events Overview

Event Description
change

Is fired when the text in the input field has changed and the focus leaves the input field or the enter key is pressed.

change

Is fired when the text in the input field has changed and the focus leaves the input field or the enter key is pressed.

Param Type Description
oControlEvent sap.ui.base.Event
getSource sap.ui.base.EventProvider
getParameters object
value string

The new value of the control.


Methods Overview

Method Description
addAriaDescribedBy

Adds some ariaDescribedBy into the association ariaDescribedBy.

addAriaLabelledBy

Adds some ariaLabelledBy into the association ariaLabelledBy.

addBeginIcon

Adds an icon to the beginning of the input

References:

  • sap.ui.core.IconPool.createControlByURI

addEndIcon

Adds an icon to the end of the input

References:

  • sap.ui.core.IconPool.createControlByURI

applyFocusInfo

Applies the focus info. To be overwritten by subclasses.

attachChange

Attaches event handler fnFunction to the change event of this sap.m.InputBase.

When called, the context of the event handler (its this) will be bound to oListener if specified, otherwise it will be bound to this sap.m.InputBase itself.

Is fired when the text in the input field has changed and the focus leaves the input field or the enter key is pressed.

bindValue

Binds property value to model data.

See ManagedObject.bindProperty for a detailed description of the possible properties of oBindingInfo

closeValueStateMessage

Close value state message popup.

destroyFormattedValueStateText

Destroys the formattedValueStateText in the aggregation formattedValueStateText.

detachChange

Detaches event handler fnFunction from the change event of this sap.m.InputBase.

The passed function and listener object must match the ones used for event registration.

sap.m.InputBase.extend

Creates a new subclass of class sap.m.InputBase with name sClassName and enriches it with the information contained in oClassInfo.

oClassInfo might contain the same kind of information as described in sap.ui.core.Control.extend.

fireChange

Fires event change to attached listeners.

fireChangeEvent

Fires the change event for the listeners

getAccessibilityInfo

References:

  • sap.ui.core.Control#getAccessibilityInfo

getAriaDescribedBy

Returns array of IDs of the elements which are the current targets of the association ariaDescribedBy.

getAriaLabelledBy

Returns array of IDs of the elements which are the current targets of the association ariaLabelledBy.

getDomRefForValueStateMessage

Gets the DOM element reference where the message popup is attached.

getEditable

Gets current value of property editable.

Defines whether the control can be modified by the user or not. Note: A user can tab to non-editable control, highlight it, and copy the text from it.

Default value is true.

getEnabled

Gets current value of property enabled.

Indicates whether the user can interact with the control or not. Note: Disabled controls cannot be focused and they are out of the tab-chain.

Default value is true.

getFocusInfo

Returns an object representing the serialized focus information. To be overwritten by subclasses.

getFormattedValueStateText

Gets content of aggregation formattedValueStateText.

Defines the formatted text that appears in the value state message pop-up. It can include links. If both valueStateText and formattedValueStateText are set - the latter is shown.

getLabels

Gets the labels referencing this control.

getLastValue

Gets the last value of the InputBase

sap.m.InputBase.getMetadata

Returns a metadata object for class sap.m.InputBase.

getName

Gets current value of property name.

The name to be used in the HTML code (for example, for HTML forms that send data to the server via submission).

getPlaceholder

Gets current value of property placeholder.

Defines a short hint intended to aid the user with data entry when the control has no value.

getRequired

Gets current value of property required.

Indicates that user input is required. This property is only needed for accessibility purposes when a single relationship between the field and a label (see aggregation labelFor of sap.m.Label) cannot be established (e.g. one label should label multiple fields).

Default value is false.

getSelectedText

Retrieves the selected text. Only supported for input control's type of Text, Url, Tel and Password.

getShowValueStateMessage

Gets current value of property showValueStateMessage.

Indicates whether the value state message should be shown or not.

Default value is true.

getTextAlign

Gets current value of property textAlign.

Defines the horizontal alignment of the text that is shown inside the input field.

Default value is Initial.

getTextDirection

Gets current value of property textDirection.

Defines the text directionality of the input field, e.g. RTL, LTR

Default value is Inherit.

getValue

Gets current value of property value.

Defines the value of the control.

getValueDescriptionInfo

Gets the value of the accessibility description info field.

getValueState

Gets current value of property valueState.

Visualizes the validation state of the control, e.g. Error, Warning, Success.

Default value is None.

getValueStateText

Gets current value of property valueStateText.

Defines the text that appears in the value state message pop-up. If this is not specified, a default text is shown from the resource bundle.

getWidth

Gets current value of property width.

Defines the width of the control.

Note: If the provided width is too small, the control gets stretched to its min width, which is needed in order for the control to be usable and well aligned.

isComposingCharacter

indicating if a character is currently composing.

onChange

Handles the change event.

onValueRevertedByEscape

Hook method that gets called when the input value is reverted with hitting escape. It may require to re-implement this method from sub classes for control specific behaviour.

openValueStateMessage

Open value state message popup.

preventChangeOnFocusLeave

Hook method to prevent the change event from being fired when the text input field loses focus.

removeAllAriaDescribedBy

Removes all the controls in the association named ariaDescribedBy.

removeAllAriaLabelledBy

Removes all the controls in the association named ariaLabelledBy.

removeAriaDescribedBy

Removes an ariaDescribedBy from the association named ariaDescribedBy.

removeAriaLabelledBy

Removes an ariaLabelledBy from the association named ariaLabelledBy.

selectText

Selects the text within the input field between the specified start and end positions. Only supported for input control's type of Text, Url, Tel and Password.

setEditable

Sets a new value for property editable.

Defines whether the control can be modified by the user or not. Note: A user can tab to non-editable control, highlight it, and copy the text from it.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is true.

setEnabled

Sets a new value for property enabled.

Indicates whether the user can interact with the control or not. Note: Disabled controls cannot be focused and they are out of the tab-chain.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is true.

setFormattedValueStateText

Sets the aggregated formattedValueStateText.

setLastValue

Sets the last value of the InputBase

setName

Sets a new value for property name.

The name to be used in the HTML code (for example, for HTML forms that send data to the server via submission).

When called with a value of null or undefined, the default value of the property will be restored.

setPlaceholder

Sets a new value for property placeholder.

Defines a short hint intended to aid the user with data entry when the control has no value.

When called with a value of null or undefined, the default value of the property will be restored.

setRequired

Sets a new value for property required.

Indicates that user input is required. This property is only needed for accessibility purposes when a single relationship between the field and a label (see aggregation labelFor of sap.m.Label) cannot be established (e.g. one label should label multiple fields).

When called with a value of null or undefined, the default value of the property will be restored.

Default value is false.

setShowValueStateMessage

Sets a new value for property showValueStateMessage.

Indicates whether the value state message should be shown or not.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is true.

setTextAlign

Sets a new value for property textAlign.

Defines the horizontal alignment of the text that is shown inside the input field.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is Initial.

setTextDirection

Sets a new value for property textDirection.

Defines the text directionality of the input field, e.g. RTL, LTR

When called with a value of null or undefined, the default value of the property will be restored.

Default value is Inherit.

setValue

Setter for property value.

Default value is empty/undefined.

setValueState

Sets a new value for property valueState.

Visualizes the validation state of the control, e.g. Error, Warning, Success.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is None.

setValueStateText

Sets a new value for property valueStateText.

Defines the text that appears in the value state message pop-up. If this is not specified, a default text is shown from the resource bundle.

When called with a value of null or undefined, the default value of the property will be restored.

setWidth

Sets a new value for property width.

Defines the width of the control.

Note: If the provided width is too small, the control gets stretched to its min width, which is needed in order for the control to be usable and well aligned.

When called with a value of null or undefined, the default value of the property will be restored.

unbindValue

Unbinds property value from model data.

updateDomValue

Sets the DOM value of the input field and handles placeholder visibility.

addAriaDescribedBy

Adds some ariaDescribedBy into the association ariaDescribedBy.

Param Type DefaultValue Description
vAriaDescribedBy sap.ui.core.ID sap.ui.core.Control

The ariaDescribedBy to add; if empty, nothing is inserted

addAriaLabelledBy

Adds some ariaLabelledBy into the association ariaLabelledBy.

Param Type DefaultValue Description
vAriaLabelledBy sap.ui.core.ID sap.ui.core.Control

The ariaLabelledBy to add; if empty, nothing is inserted

addBeginIcon

Adds an icon to the beginning of the input

References:

Param Type DefaultValue Description
oIconSettings object

settings for creating an icon

addEndIcon

Adds an icon to the end of the input

References:

Param Type DefaultValue Description
oIconSettings object

settings for creating an icon

iPosition int

position to be inserted in the aggregation. If not provided, the icon gets inserted on last position.

applyFocusInfo

Applies the focus info. To be overwritten by subclasses.

Param Type DefaultValue Description
oFocusInfo object

attachChange

Attaches event handler fnFunction to the change event of this sap.m.InputBase.

When called, the context of the event handler (its this) will be bound to oListener if specified, otherwise it will be bound to this sap.m.InputBase itself.

Is fired when the text in the input field has changed and the focus leaves the input field or the enter key is pressed.

Param Type DefaultValue Description
oData object

An application-specific payload object that will be passed to the event handler along with the event object when firing the event

fnFunction function(sap.ui.base.Event) : void

The function to be called when the event occurs

oListener object

Context object to call the event handler with. Defaults to this sap.m.InputBase itself

bindValue

Binds property value to model data.

See ManagedObject.bindProperty for a detailed description of the possible properties of oBindingInfo

Param Type DefaultValue Description
oBindingInfo sap.ui.base.ManagedObject.PropertyBindingInfo

The binding information

closeValueStateMessage

Close value state message popup.

destroyFormattedValueStateText

Destroys the formattedValueStateText in the aggregation formattedValueStateText.

detachChange

Detaches event handler fnFunction from the change event of this sap.m.InputBase.

The passed function and listener object must match the ones used for event registration.

Param Type DefaultValue Description
fnFunction function(sap.ui.base.Event) : void

The function to be called, when the event occurs

oListener object

Context object on which the given function had to be called

sap.m.InputBase.extend

Creates a new subclass of class sap.m.InputBase with name sClassName and enriches it with the information contained in oClassInfo.

oClassInfo might contain the same kind of information as described in sap.ui.core.Control.extend.

Param Type DefaultValue Description
sClassName string

Name of the class being created

oClassInfo object

Object literal with information about the class

FNMetaImpl function

Constructor function for the metadata object; if not given, it defaults to the metadata implementation used by this class

fireChange

Fires event change to attached listeners.

Param Type DefaultValue Description
mParameters object

Parameters to pass along with the event

value string

The new value of the control.

fireChangeEvent

Fires the change event for the listeners

Param Type DefaultValue Description
sValue string

value of the input.

oParams object

extra event parameters.

getAccessibilityInfo

References:

getAriaDescribedBy

Returns array of IDs of the elements which are the current targets of the association ariaDescribedBy.

getAriaLabelledBy

Returns array of IDs of the elements which are the current targets of the association ariaLabelledBy.

getDomRefForValueStateMessage

Gets the DOM element reference where the message popup is attached.

getEditable

Gets current value of property editable.

Defines whether the control can be modified by the user or not. Note: A user can tab to non-editable control, highlight it, and copy the text from it.

Default value is true.

getEnabled

Gets current value of property enabled.

Indicates whether the user can interact with the control or not. Note: Disabled controls cannot be focused and they are out of the tab-chain.

Default value is true.

getFocusInfo

Returns an object representing the serialized focus information. To be overwritten by subclasses.

getFormattedValueStateText

Gets content of aggregation formattedValueStateText.

Defines the formatted text that appears in the value state message pop-up. It can include links. If both valueStateText and formattedValueStateText are set - the latter is shown.

getLabels

Gets the labels referencing this control.

getLastValue

Gets the last value of the InputBase

sap.m.InputBase.getMetadata

Returns a metadata object for class sap.m.InputBase.

getName

Gets current value of property name.

The name to be used in the HTML code (for example, for HTML forms that send data to the server via submission).

getPlaceholder

Gets current value of property placeholder.

Defines a short hint intended to aid the user with data entry when the control has no value.

getRequired

Gets current value of property required.

Indicates that user input is required. This property is only needed for accessibility purposes when a single relationship between the field and a label (see aggregation labelFor of sap.m.Label) cannot be established (e.g. one label should label multiple fields).

Default value is false.

getSelectedText

Retrieves the selected text. Only supported for input control's type of Text, Url, Tel and Password.

getShowValueStateMessage

Gets current value of property showValueStateMessage.

Indicates whether the value state message should be shown or not.

Default value is true.

getTextAlign

Gets current value of property textAlign.

Defines the horizontal alignment of the text that is shown inside the input field.

Default value is Initial.

getTextDirection

Gets current value of property textDirection.

Defines the text directionality of the input field, e.g. RTL, LTR

Default value is Inherit.

getValue

Gets current value of property value.

Defines the value of the control.

getValueDescriptionInfo

Gets the value of the accessibility description info field.

getValueState

Gets current value of property valueState.

Visualizes the validation state of the control, e.g. Error, Warning, Success.

Default value is None.

getValueStateText

Gets current value of property valueStateText.

Defines the text that appears in the value state message pop-up. If this is not specified, a default text is shown from the resource bundle.

getWidth

Gets current value of property width.

Defines the width of the control.

Note: If the provided width is too small, the control gets stretched to its min width, which is needed in order for the control to be usable and well aligned.

isComposingCharacter

indicating if a character is currently composing.

onChange

Handles the change event.

Param Type DefaultValue Description
oEvent object
mParameters object

Additional event parameters to be passed in to the change event handler if the value has changed

sNewValue string

Passed value on change

onValueRevertedByEscape

Hook method that gets called when the input value is reverted with hitting escape. It may require to re-implement this method from sub classes for control specific behaviour.

Param Type DefaultValue Description
sValue string

Reverted value of the input.

openValueStateMessage

Open value state message popup.

preventChangeOnFocusLeave

Hook method to prevent the change event from being fired when the text input field loses focus.

Param Type DefaultValue Description
oEvent jQuery.Event

The event object.

removeAllAriaDescribedBy

Removes all the controls in the association named ariaDescribedBy.

removeAllAriaLabelledBy

Removes all the controls in the association named ariaLabelledBy.

removeAriaDescribedBy

Removes an ariaDescribedBy from the association named ariaDescribedBy.

Param Type DefaultValue Description
vAriaDescribedBy int sap.ui.core.ID sap.ui.core.Control

The ariaDescribedBy to be removed or its index or ID

removeAriaLabelledBy

Removes an ariaLabelledBy from the association named ariaLabelledBy.

Param Type DefaultValue Description
vAriaLabelledBy int sap.ui.core.ID sap.ui.core.Control

The ariaLabelledBy to be removed or its index or ID

selectText

Selects the text within the input field between the specified start and end positions. Only supported for input control's type of Text, Url, Tel and Password.

Param Type DefaultValue Description
iSelectionStart int

The index into the text at which the first selected character is located.

iSelectionEnd int

The index into the text at which the last selected character is located.

setEditable

Sets a new value for property editable.

Defines whether the control can be modified by the user or not. Note: A user can tab to non-editable control, highlight it, and copy the text from it.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is true.

Param Type DefaultValue Description
bEditable boolean true

New value for property editable

setEnabled

Sets a new value for property enabled.

Indicates whether the user can interact with the control or not. Note: Disabled controls cannot be focused and they are out of the tab-chain.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is true.

Param Type DefaultValue Description
bEnabled boolean true

New value for property enabled

setFormattedValueStateText

Sets the aggregated formattedValueStateText.

Param Type DefaultValue Description
oFormattedValueStateText sap.m.FormattedText

The formattedValueStateText to set

setLastValue

Sets the last value of the InputBase

Param Type DefaultValue Description
sValue string

setName

Sets a new value for property name.

The name to be used in the HTML code (for example, for HTML forms that send data to the server via submission).

When called with a value of null or undefined, the default value of the property will be restored.

Param Type DefaultValue Description
sName string

New value for property name

setPlaceholder

Sets a new value for property placeholder.

Defines a short hint intended to aid the user with data entry when the control has no value.

When called with a value of null or undefined, the default value of the property will be restored.

Param Type DefaultValue Description
sPlaceholder string

New value for property placeholder

setRequired

Sets a new value for property required.

Indicates that user input is required. This property is only needed for accessibility purposes when a single relationship between the field and a label (see aggregation labelFor of sap.m.Label) cannot be established (e.g. one label should label multiple fields).

When called with a value of null or undefined, the default value of the property will be restored.

Default value is false.

Param Type DefaultValue Description
bRequired boolean false

New value for property required

setShowValueStateMessage

Sets a new value for property showValueStateMessage.

Indicates whether the value state message should be shown or not.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is true.

Param Type DefaultValue Description
bShowValueStateMessage boolean true

New value for property showValueStateMessage

setTextAlign

Sets a new value for property textAlign.

Defines the horizontal alignment of the text that is shown inside the input field.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is Initial.

Param Type DefaultValue Description
sTextAlign sap.ui.core.TextAlign Initial

New value for property textAlign

setTextDirection

Sets a new value for property textDirection.

Defines the text directionality of the input field, e.g. RTL, LTR

When called with a value of null or undefined, the default value of the property will be restored.

Default value is Inherit.

Param Type DefaultValue Description
sTextDirection sap.ui.core.TextDirection Inherit

New value for property textDirection

setValue

Setter for property value.

Default value is empty/undefined.

Param Type DefaultValue Description
sValue string

New value for property value.

setValueState

Sets a new value for property valueState.

Visualizes the validation state of the control, e.g. Error, Warning, Success.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is None.

Param Type DefaultValue Description
sValueState sap.ui.core.ValueState None

New value for property valueState

setValueStateText

Sets a new value for property valueStateText.

Defines the text that appears in the value state message pop-up. If this is not specified, a default text is shown from the resource bundle.

When called with a value of null or undefined, the default value of the property will be restored.

Param Type DefaultValue Description
sValueStateText string

New value for property valueStateText

setWidth

Sets a new value for property width.

Defines the width of the control.

Note: If the provided width is too small, the control gets stretched to its min width, which is needed in order for the control to be usable and well aligned.

When called with a value of null or undefined, the default value of the property will be restored.

Param Type DefaultValue Description
sWidth sap.ui.core.CSSSize

New value for property width

unbindValue

Unbinds property value from model data.

updateDomValue

Sets the DOM value of the input field and handles placeholder visibility.

Param Type DefaultValue Description
sValue string

value of the input field.